Ocamlnet 4 Reference Manual : Nethttpd_types

# Module Nethttpd_types

    module Nethttpd_types: sig .. end

Type definitions for the HTTP daemon

Contents

- Exceptions
- Environment
- Service Providers
- Helpers

Many types can also be found in the `Nethttp` module (part of netstring). Furthermore, `Netcgi_env` and `Netcgi_types` are of interest (part of cgi).

# Exceptions

    exception Standard_response of Nethttp.http_status * Nethttp.http_header option * string option

Some HTTP containers allow you to raise this exception. The standard response corresponding to `http_status` is sent back to the client. If the third argument exists, an entry into the error log is written.

# Environment

    type output_state = [ `End | `Sending | `Start ]

    val string_of_output_state : output_state -> string

Debugging

    class type virtual v_extended_environment = object .. end

An extension of `cgi_environment` for use with the daemon.

    class type extended_environment = object .. end

Same as `v_extended_environment`, but no virtual methods

## Construction of environments

    class virtual empty_environment : object .. end

This class implements an environment with defined internal containers.

    class redirected_environment : ?in_header:Nethttp.http_header -> ?properties:(string * string) list -> ?in_channel:Netchannels.in_obj_channel -> extended_environment -> extended_environment

This class overlays the input-side containers of an existing environment.

## Auxiliary Functions for Environments

    val output_static_response : #extended_environment ->
           Nethttp.http_status -> Nethttp.http_header option -> string -> unit

Outputs the string argument as response body, together with the given status and the header (optional). Response header fields are set as follows:

- The `Content-Length` is set to the length of the string.
- The `Content-Type` is set to "text/html" unless given by the header.

If the header is not passed, the header of the environment is taken. If the header argument exists, however, it overrides the header of the environment.

    val output_file_response : #extended_environment ->
           Nethttp.http_status ->
           Nethttp.http_header option -> string -> int64 -> int64 -> unit

Outputs the contents of a file as response body, together with the given status and the header (optional). The string is the file name. The first int64 number is the position in the file where to start, and the second number is the length of the body. Response header fields are set as follows:

- The `Content-Length` is set to the length of the string.
- The `Content-Type` is set to "text/html" unless given by the header.

Note that `Content-Range` is not set automatically, even if the file is only partially transferred.

If the header is not passed, the header of the environment is taken. If the header argument exists, however, it overrides the header of the environment.

The function raises `Sys_error` when the file cannot be read.

# Generating error responses, logging

    class type request_info = object .. end

    class type full_info = object .. end

    class create_full_info : response_status_code:int -> request_body_rejected:bool -> output_header:Nethttp.http_header -> output_body_size:int64 -> request_info -> full_info

Creates a `full_info` object by adding to a `request_info` object

    class type error_response_params = object .. end

    class type min_config = object .. end

Minimal configuration needed for `output_std_response`

    val output_std_response : #min_config ->
           #extended_environment ->
           Nethttp.http_status -> Nethttp.http_header option -> string option -> unit

Outputs a "standard response" for the `http_status`. The string argument is an optional entry into the error log.

If the header is not passed, an empty header is taken. If the header argument exists, this header is taken. The header of the environment is never taken.

# Service Providers

Service providers are defined using the three class types:

- `http_service`: The service provider as such. When a HTTP header has been received, and the service provider is invoked, it returns an object fitting to the next class type, `http_service_receiver`. This object is tagged with ``Accept_body`; at this point there are also alternate ways of processing, see below.
- `http_service_receiver`: The task of this object is to receive the request body. When the body has been completely received, the object is notified, and returns a third object of type `http_service_generator`.
- `http_service_generator`: The task of this object is to generate the response.

An implementor is free to define only one class that satisfies all three class types at once. However, this is only an option.

The three objects reflect three stages of HTTP processing. The stages have made explicit to allow the implementor of services to intercept the points in time when the processing of the next stage begins. Furthermore, in multi-threaded environments it is allowed that the stages are performed in the contexts of different threads.

In addition to the three-stage model there also several faster paths of processing:

- ``Reject_body` can be used to refuse the acceptance of the request body when it is already clear that an error response is sent back. This path skips the stage `http_service_receiver`.
- ``Static` can be used to send a constant string back (only to be used when the string needs not to be computed)
- ``File` can be used to send the contents of a file back (only to be used when the file already exists)

    exception Redirect_request of string * Nethttp.http_header

The "early" redirect is only allowed in stage 1 of HTTP processing. The string argument is the new URI path of the request. The header can also be exchanged except the fields that are needed to decode the request body. It is not possible to change the method.

    exception Redirect_response of string * Nethttp.http_header

The "late" redirect is only allowed in stage 3 of HTTP processing. The string argument is the new URI path of the request. The header can also be exchanged except the fields that are needed to decode the request body. The method is always changed to `GET`.

    class type http_service_generator = object .. end

    class type http_service_receiver = object .. end

    type http_service_reaction = [ `Accept_body of http_service_receiver
           | `File of
               Nethttp.http_status * Nethttp.http_header option * string * int64 * int64
           | `Reject_body of http_service_generator
           | `Static of Nethttp.http_status * Nethttp.http_header option * string
           | `Std_response of
               Nethttp.http_status * Nethttp.http_header option * string option ]

Indicates the immediate reaction upon an arriving HTTP header:

- ``Accept_body` is the regular way of processing requests. If necessary, the client is told to continue sending the rest of the request.
- ``Reject_body` can be used when the body of the request is not needed, and the response will be negative.
- ``Static` means to send the header and a constant string back as response. The header is taken from the environment if not explicitly passed, Note: The `Content-Length` header is automatically added. The `Content-Type` defaults to "text/html".
- ``File` is similar to this, but the data come from a file. The file is specified by an absolute pathname. The range of the file is given by the start position and the length of the range. The header is taken from the environment if not explicitly passed, Note: The `Content-Length` header is automatically added. The `Content-Type` defaults to "text/html".
- ``Std_response` is similar to ``Static`, however the body is the standard text for the status code. If the header is omitted, it is taken as empty. The third argument is an optional entry into the error log. Note: The `Content-Length` header is automatically added. The `Content-Type` defaults to "text/html".

    class type ['a] http_service = object .. end

# Helpers

    val update_alist : ('a * 'b) list -> ('a * 'b) list -> ('a * 'b) list

`update_alist updl l`: Returns the alist with all elements of `updl` and all elements of `l` that are not member of `updl`.