class http_protocol :
#http_protocol_config -> Unix.file_descr ->
The core event loop of the HTTP daemon
fd one must pass the already connected socket. It must be in non-
How to use this class: Basically, one invokes
cycle until the whole
message exchange on
fd is processed.
cycle receives data from the
socket and sends data to the socket. There are two internal queues:
The receive queue stores parts of received requests as
One can take values from the front of this queue by calling
The response queue stores
http_response objects. Each of the objects
corresponds to a request that was received before. This queue is handled
fully automatically, but one can watch its length to see whether all responses
are actually transmitted over the wire.
The basic algorithm to process messages is:
let rec next_token () = if proto # recv_queue_len = 0 then ( proto # cycle (); next_token() ) else proto # receive() let cur_token = ref (next_token()) in while !cur_token <> `Eof do (* Process first token of next request: *) match !cur_token with | `Req_header(req_line, header, resp) -> (* Depending on [req_line], read further tokens until [`Req_end] *) ... (* Switch to the first token of the next message: *) cur_token := next_token() | `Timeout -> ... | `Bad_request_error(e,resp) -> (* Generate 400 error, send it to [resp] *) ... (* Switch to the first token of the next message: *) cur_token := next_token() | `Fatal_error e -> failwith "Crash" | _ -> assert false done; while proto # resp_queue_len > 0 do proto # cycle (); done; proto # shutdown()
See the file
tests/easy_daemon.ml for a complete implementation of this.
As one can see, it is essential to watch the lengths of the queues in order
to figure out what has happened during
When the body of the request is empty,
`Req_body tokens are omitted.
Note that for requests like
GET that always have an empty body, it is
still possible that an errorneous client sends a body, and that
tokens arrive. One must accept and ignore these tokens.
Error handling: For serious errors, the connection is immediately aborted.
In this case,
receive returns a
`Fatal_error token. Note that the
queued responses cannot be sent! An example of this is
There is a large class of non-serious errors, esp. format errors
in the header and body. It is typical of these errors that one cannot determine
the end of the request properly. For this reason, the daemon stops reading
further data from the request, but the response queue is still delivered.
For these errors,
receive returns a
This token contains a
http_response object that must be filled with a
400 error response.
method hooks :
method cycle :
?block:float -> unit -> unit
Looks at the file descriptor. If there is data to read from the descriptor,
and there is free space in the input buffer, additional data is read into
the buffer. It is also tried to interpret the new data as
and if possible, new
req_tokens are appended to the receive queue.
If the response queue has objects, and there is really data one can send, and if the socket allows one to send data, it is tried to send as much data as possible.
block (default: 0) can be set to wait until data
can be exchanged with the socket. This avoids busy waiting. The number
is the duration in seconds to wait until the connection times out
(0 means not to wait at all, -1 means to wait infinitely). When a timeout
happens, and there is nothing to send, and the last request was fully
receive will simply return
`Timeout (i.e. when
true). Otherwise, the
`Timeout is generated.
method receive :
unit -> req_token
Returns the first
req_token from the receive queue. Raises
Recv_queue_empty when the queue is empty (= has no new data)
method peek_recv :
unit -> req_token
Peeks the first token, but leaves it in the queue.
Recv_queue_empty when the queue is empty.
method recv_queue_len :
Returns the length of the receive queue (number of tokens)
method resp_queue_len :
Returns the length of the internal response queue (number of
objects that have not yet fully processed)
method pipeline_len :
Returns the number of unanswered requests = Number of received
minus number of responses in state
`Processed. Note that
-1 when bad requests are responded.
method recv_queue_byte_size :
Returns the (estimated) size of the input queue in bytes
method waiting_for_next_message :
Whether the kernel is currently waiting for the beginning of a new
arriving HTTP request. This is
false while the request is being
method input_timeout_class :
[ `Next_message | `None | `Normal ]
Suggests the calculation of a timeout value for input:
`Normal: The normal timeout value applies
`Next_message: The timeout value applies while waiting for the next message
`None: The connection is output-driven, no input timeout value
method shutdown :
unit -> unit
Shuts the socket down. Note: the descriptor is not closed.
TLS: You need to further
cycle until XXX.
method timeout :
unit -> unit
Process a timeout condition as
method abort :
fatal_error -> unit
Stops the transmission of data. The receive queue is cleared and filled
with the two tokens
The response queue is cleared. The
method will return immediately without doing anything.
method fd :
Just returns the socket
method do_input :
true iff the protocol engine is interested in new data from the
false after EOF and after errors.
method do_output :
true iff the protocol engine has data to output to the socket
method resp_queue_filled :
Whether there is data to send in the internal output queue. If
TLS is enabled, this is not always the same as
method need_linger :
true when a lingering close operation is needed to reliably shut
down the socket. In many cases, this expensive operation is not necessary.
See the class
method tls_session_props :
If TLS is enabled, this returns the session properties. These are first available after the TLS handshake.
method config :
Just returns the configuration
method test_coverage :
For testing: returns a list of tokens indicating into which cases the program ran.