class http_protocol :#http_protocol_config -> Unix.file_descr ->
object
..end
In fd
one must pass the already connected socket. It must be in non-
blocking mode.
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 req_token
.
One can take values from the front of this queue by calling receive
.
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 cycle
.
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 `Req_body
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 `Broken_pipe
.
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 `Bad_request_error
token.
This token contains a http_response
object that must be filled with a
400 error response.
method hooks : http_protocol_hooks
method cycle : ?block:float -> unit -> unit
req_token
s,
and if possible, new req_token
s 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.
The option 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
processed, receive
will simply return `Timeout
(i.e. when
waiting_for_next_message
is true
). Otherwise, the
fatal error `Timeout
is generated.
method receive : unit -> req_token
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
Recv_queue_empty
when the queue is empty.method recv_queue_len : int
method resp_queue_len : int
http_response
objects that have not yet fully processed)method pipeline_len : int
`Req_end
tokens
minus number of responses in state `Processed
. Note that pipeline_len
can become -1
when bad requests are responded.method recv_queue_byte_size : int
method waiting_for_next_message : bool
false
while the request is being
received.method input_timeout_class : [ `Next_message | `None | `Normal ]
`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 valuemethod shutdown : unit -> unit
TLS: You need to further cycle
until XXX.
method timeout : unit -> unit
cycle
doesmethod abort : fatal_error -> unit
`Fatal_error
and `Eof
.
The response queue is cleared. The cycle
method will return immediately without doing anything.method fd : Unix.file_descr
method do_input : bool
true
iff the protocol engine is interested in new data from the
socket. Returns false
after EOF and after errors.method do_output : bool
true
iff the protocol engine has data to output to the socketmethod resp_queue_filled : bool
do_output
.method need_linger : bool
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 lingering_close
below.method tls_session_props : Nettls_support.tls_session_props option
method config : http_protocol_config
method test_coverage : string list