Merge pull request #201 from inhabitedtype/misc-comments

add some miscellaneous comments from a long-term branch
inhabitedtype · Apr 20, 2021 · d523e6f · d523e6f
2 parents 10ce839 + 8213e22
commit d523e6f
Show file tree

Hide file tree

Showing 5 changed files with 51 additions and 47 deletions.
diff --git a/lib/body.ml b/lib/body.ml
@@ -115,6 +115,7 @@ let rec do_execute_read t on_eof on_read =
     t.on_eof         <- default_on_eof;
     t.on_read        <- default_on_read;
     on_eof ()
+  (* [Faraday.operation] never returns an empty list of iovecs *)
   | `Writev []       -> assert false
   | `Writev (iovec::_) ->
     t.read_scheduled <- false;

diff --git a/lib/httpaf.mli b/lib/httpaf.mli
@@ -459,8 +459,8 @@ module Body : sig
       consume, or when the input channel has been closed and no further bytes
       will be received by the application.
 
-      Once either of these callbacks have been called, they become inactive. 
-      The application is responsible for scheduling subsequent reads, either 
+      Once either of these callbacks have been called, they become inactive.
+      The application is responsible for scheduling subsequent reads, either
       within the [on_read] callback or by some other mechanism. *)
 
   val write_char : [`write] t -> char -> unit
@@ -481,7 +481,7 @@ module Body : sig
   val schedule_bigstring : [`write] t -> ?off:int -> ?len:int -> Bigstringaf.t -> unit
   (** [schedule_bigstring w ?off ?len bs] schedules [bs] to be transmitted at
       the next opportunity without performing a copy. [bs] should not be
-      modified until a subsequent call to {!flush} has successfully 
+      modified until a subsequent call to {!flush} has successfully
       completed. *)
 
   val flush : [`write] t -> (unit -> unit) -> unit
@@ -690,7 +690,7 @@ module Server_connection : sig
       connection to consume. *)
 
   val read_eof : t -> Bigstringaf.t -> off:int -> len:int -> int
-  (** [read_eof t bigstring ~off ~len] reads bytes of input from the provided 
+  (** [read_eof t bigstring ~off ~len] reads bytes of input from the provided
       range of [bigstring] and returns the number of bytes consumed by the
       connection.  {!read_eof} should be called after {!next_read_operation}
       returns a [`Read] and an EOF has been received from the communication
@@ -779,7 +779,7 @@ module Client_connection : sig
       connection to consume. *)
 
   val read_eof : t -> Bigstringaf.t -> off:int -> len:int -> int
-  (** [read_eof t bigstring ~off ~len] reads bytes of input from the provided 
+  (** [read_eof t bigstring ~off ~len] reads bytes of input from the provided
       range of [bigstring] and returns the number of bytes consumed by the
       connection.  {!read_eof} should be called after {!next_read_operation}
       returns a [`Read] and an EOF has been received from the communication

diff --git a/lib/message.ml b/lib/message.ml
@@ -38,7 +38,8 @@
 
 let persistent_connection ?(proxy=false) version headers =
   let _ = proxy in
-  (* XXX(seliopou): use proxy argument in the case of HTTP/1.0 *)
+  (* XXX(seliopou): use proxy argument in the case of HTTP/1.0 as per
+     https://tools.ietf.org/html/rfc7230#section-6.3 *)
   match Headers.get headers "connection" with
   | Some "close"      -> false
   | Some "keep-alive" -> Version.(compare version v1_0) >= 0

diff --git a/lib/parse.ml b/lib/parse.ml
@@ -263,6 +263,8 @@ module Reader = struct
         handler response Body.empty;
         ok
       | `Fixed _ | `Chunked | `Close_delimited as encoding ->
+        (* We do not trust the length provided in the [`Fixed] case, as the
+           client could DOS easily. *)
         let response_body = Body.create_reader Bigstringaf.empty in
         handler response response_body;
         body ~encoding response_body *> ok

diff --git a/lib/status.ml b/lib/status.ml
@@ -37,7 +37,7 @@ type informational = [
   | `Switching_protocols
   ]
 
-type successful = [ 
+type successful = [
   | `OK
   | `Created
   | `Accepted
@@ -205,53 +205,53 @@ let to_code = function
 
 let really_unsafe_of_code = function
  (* Informational *)
-  | 100 -> `Continue 
-  | 101 -> `Switching_protocols 
+  | 100 -> `Continue
+  | 101 -> `Switching_protocols
  (* Successful *)
-  | 200 -> `OK 
-  | 201 -> `Created 
-  | 202 -> `Accepted 
-  | 203 -> `Non_authoritative_information 
-  | 204 -> `No_content 
-  | 205 -> `Reset_content 
-  | 206 -> `Partial_content 
+  | 200 -> `OK
+  | 201 -> `Created
+  | 202 -> `Accepted
+  | 203 -> `Non_authoritative_information
+  | 204 -> `No_content
+  | 205 -> `Reset_content
+  | 206 -> `Partial_content
  (* Redirection *)
-  | 300 -> `Multiple_choices 
-  | 301 -> `Moved_permanently 
-  | 302 -> `Found 
-  | 303 -> `See_other 
-  | 304 -> `Not_modified 
-  | 305 -> `Use_proxy 
-  | 307 -> `Temporary_redirect 
+  | 300 -> `Multiple_choices
+  | 301 -> `Moved_permanently
+  | 302 -> `Found
+  | 303 -> `See_other
+  | 304 -> `Not_modified
+  | 305 -> `Use_proxy
+  | 307 -> `Temporary_redirect
  (* Client error *)
-  | 400 -> `Bad_request 
-  | 401 -> `Unauthorized 
-  | 402 -> `Payment_required 
-  | 403 -> `Forbidden 
-  | 404 -> `Not_found 
-  | 405 -> `Method_not_allowed 
+  | 400 -> `Bad_request
+  | 401 -> `Unauthorized
+  | 402 -> `Payment_required
+  | 403 -> `Forbidden
+  | 404 -> `Not_found
+  | 405 -> `Method_not_allowed
   | 406 -> `Not_acceptable
-  | 407 -> `Proxy_authentication_required 
-  | 408 -> `Request_timeout 
-  | 409 -> `Conflict 
-  | 410 -> `Gone 
-  | 411 -> `Length_required 
-  | 412 -> `Precondition_failed 
-  | 413 -> `Payload_too_large 
-  | 414 -> `Uri_too_long 
-  | 415 -> `Unsupported_media_type 
-  | 416 -> `Range_not_satisfiable 
-  | 417 -> `Expectation_failed 
-  | 418 -> `I_m_a_teapot 
-  | 420 -> `Enhance_your_calm 
+  | 407 -> `Proxy_authentication_required
+  | 408 -> `Request_timeout
+  | 409 -> `Conflict
+  | 410 -> `Gone
+  | 411 -> `Length_required
+  | 412 -> `Precondition_failed
+  | 413 -> `Payload_too_large
+  | 414 -> `Uri_too_long
+  | 415 -> `Unsupported_media_type
+  | 416 -> `Range_not_satisfiable
+  | 417 -> `Expectation_failed
+  | 418 -> `I_m_a_teapot
+  | 420 -> `Enhance_your_calm
   | 426 -> `Upgrade_required
  (* Server error *)
-  | 500 -> `Internal_server_error 
-  | 501 -> `Not_implemented 
-  | 502 -> `Bad_gateway 
+  | 500 -> `Internal_server_error
+  | 501 -> `Not_implemented
+  | 502 -> `Bad_gateway
   | 503 -> `Service_unavailable
-  | 504 -> `Gateway_timeout 
-  | 505 -> `Http_version_not_supported 
+  | 504 -> `Gateway_timeout
+  | 505 -> `Http_version_not_supported
   | c   -> `Code c
 
 let unsafe_of_code c =