Plasma GitLab Archive
Projects Blog Knowledge

Module Nethttpd_types

module Nethttpd_types: sig .. end

Type definitions for the HTTP daemon

Contents


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.

This web site is published by Informatikbüro Gerd Stolpmann
Powered by Caml