Ocamlnet 4 Reference Manual : Nethttpd_kernel.http_protocol

# Class Nethttpd_kernel.http_protocol

    class http_protocol : #http_protocol_config -> Unix.file_descr -> object .. end

The core event loop of the HTTP daemon

## Exchange of HTTP messages

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

Set 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 `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

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. Raises `Recv_queue_empty` when the queue is empty.

    method recv_queue_len : int

Returns the length of the receive queue (number of tokens)

    method resp_queue_len : int

Returns the length of the internal response queue (number of `http_response` objects that have not yet fully processed)

    method pipeline_len : int

Returns the number of unanswered requests = Number of received ``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

Returns the (estimated) size of the input queue in bytes

    method waiting_for_next_message : bool

Whether the kernel is currently waiting for the beginning of a new arriving HTTP request. This is `false` while the request is being received.

    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 `cycle` does

    method abort : fatal_error -> unit

Stops the transmission of data. The receive queue is cleared and filled with the two tokens ``Fatal_error` and ``Eof`. The response queue is cleared. The `cycle` method will return immediately without doing anything.

    method fd : Unix.file_descr

Just returns the socket

    method do_input : bool

Returns `true` iff the protocol engine is interested in new data from the socket. Returns `false` after EOF and after errors.

    method do_output : bool

Returns `true` iff the protocol engine has data to output to the socket

    method resp_queue_filled : bool

Whether there is data to send in the internal output queue. If TLS is enabled, this is not always the same as `do_output`.

    method need_linger : bool

Returns `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

If TLS is enabled, this returns the session properties. These are first available after the TLS handshake.

    method config : http_protocol_config

Just returns the configuration

    method test_coverage : string list

For testing: returns a list of tokens indicating into which cases the program ran.