Module Nethttpd_services

module Nethttpd_services: sig .. end

Service Providers for HTTP daemon

This module defines the basic service providers that handle requests and generate responses. The service providers can be used with both the reactive and the event-based daemon encapsulations.

type host = {
   server_pref_name : string option; (*The preferred name of the host. This can be a DNS name or an IP address.*)
   server_pref_port : int option; (*The preferred port of the host*)
   server_names : (string * int) list; (*Names and ports that match this host definition, for name-based virtual hosting. The name "*" matches any name, and the port 0 matches any port.*)
   server_addresses : (Unix.inet_addr * int) list; (*IP addresses and ports that also match this host definition, for IP-based virtual hosting. The address Unix.inet_addr_any matches any address, and the port 0 matches any port.*)
For name- and IP-based virtual hosting this record describes the individual host. An incoming request matches this host if: If server_pref_name is set, the name of the host is set to this string for further processing (esp. cgi_server_name). If not set, the name of the host is set to the name corresponding to the matching entry of server_names or server_addresses, or if this does not succeed, to the real IP address.

If server_pref_port is set, the port of the host is set to this string for further processing (esp. cgi_server_port). If not set, the port of the host is set to the port corresponding to the matching entry of server_names or server_addresses, or if this does not succeed, to the real port number.

type 'a host_distributor = (host * 'a Nethttpd_types.http_service) list 
Describes virtual hosting by pairs (host,service): If host matches the incoming request, the corresponding service is performed to generate the response.
val host_distributor : 'a host_distributor ->
[> `Host_distributor of 'a host_distributor ]
Configures virtual hosting
val default_host : ?pref_name:string -> ?pref_port:int -> unit -> host
Creates a host record that matches any request. pref_name and pref_port can be used to specify preferred names.
val options_service : unit -> [> `Options_service ] Nethttpd_types.http_service
This service responds to "OPTIONS *" requests, and nothing else
type 'a uri_distributor = (string * 'a Nethttpd_types.http_service) list 
Describes that services are bound to URI prefixes. The strings are URI paths (without URI escaping). For an incoming request URI, the longest matching prefix is selected, and the corresponding service is carried out.

If the URI path in the list ends with a slash, it can only be selected if the incoming request URI also includes the slash.

If the URI path in the list does not end with a slash, it can only be selected if the incoming request URI is exactly identical, or continues the path with a slash.

val uri_distributor : 'a uri_distributor ->
[> `Uri_distributor of 'a uri_distributor ]
Configures URI distribution. The incoming request URI is normalized before being matched, and the request is rewritten to the normalized URI.

Normalization includes:

If the path starts with .. after normalization, the request is rejected.
type 'a linear_distributor = ((Nethttpd_types.extended_environment -> bool) *
'a Nethttpd_types.http_service)
Services are selected by calling the selector function. The first service for which the function returns true is selected.
val linear_distributor : 'a linear_distributor ->
[> `Linear_distributor of 'a linear_distributor ]
Configures linear distribution
type method_filter = [ `Limit of string list | `Limit_except of string list ] 
The request is only accepted if listed (for `Limit), or if not listed (for `Limit_except).
type 'a method_distributor = (method_filter * 'a Nethttpd_types.http_service) list 
The first service is selected for which the method filter accepts the request
val method_distributor : 'a method_distributor ->
[> `Method_distributor of 'a method_distributor ]
Configures method distribution
type file_option = [ `Enable_gzip
| `Enable_index_file of string list
| `Enable_listings of
Nethttpd_types.extended_environment ->
Netcgi_types.cgi_activation -> file_service -> unit ]
Add-on features for file services:

type file_service = {
   file_docroot : string; (*The document root for this file service*)
   file_uri : string; (*The URI prefix corresponding to the document root. Escapes are not allowed*)
   file_suffix_types : (string * string) list; (*Maps the file suffixes (after the dot) to media types*)
   file_default_type : string; (*The media type to use if suffix mapping fails*)
   file_options : file_option list; (*Further options for files*)
Describes a file service
val file_service : file_service ->
[> `File_service of file_service ]
Configures a file service
val file_translator : file_service -> string -> string
Translates an URI path to a file name. Raises Not_found if not possible.
val simple_listing : ?hide:string list ->
Nethttpd_types.extended_environment ->
Netcgi_types.cgi_activation -> file_service -> unit
Simple listing generator for `Enable_listings

hide: An optional list of PCRE regular expressions. File names matching one of the regexps are hidden in the listing. Defaults to hiding files starting with a dot, and files ending in a tilde character.

type std_activation_options = {
   stdactv_processing : (string -> Netmime.mime_header -> Netcgi.argument_processing) option;
   stdactv_operating_type : Netcgi.operating_type option;
These are options for `Std_activation. For explanations, see the Netcgi module.
type std_activation = [ `Std_activation of std_activation_options
| `Std_activation_buffered
| `Std_activation_tempfile
| `Std_activation_unbuffered ]
The way the Netcgi_types.cgi_activation object is created. For typical usage, just take: The following option is provided for detailed control:

type #Netcgi_types.cgi_activation dynamic_service = {
   dyn_handler : Nethttpd_types.extended_environment ->
(#Netcgi_types.cgi_activation as 'a) -> unit
(*A dynamic service is carried out by calling this function with the environment and the CGI activation. The function can use all CGI features, including setting the Location handler to redirect responses.*)
   dyn_activation : Nethttpd_types.extended_environment -> 'a; (*The way the Netcgi_types.cgi_activation is created. Look below for std_activation.*)
   dyn_uri : string option; (*The URI prefix corresponding to this service. This is only used to compute cgi_path. Leave it to None if not needed.*)
   dyn_translator : string -> string; (*The function computing cgi_path_translated from cgi_path. Set it to (fun _ -> "") if not needed.*)
   dyn_accept_all_conditionals : bool; (*Whether to pass requests with If-Match and If-Unmodified-Since headers to this service. If set to true, the service can optimize the caching behaviour by interpreting these fields. It is even obliged to interpret them. If false, requests containing these headers are rejected.

The other condition fields If-None-Match, If-Modified-Since, and If-Ranges are not affected by this option. One can safely ignore these headers.

val std_activation : std_activation ->
Nethttpd_types.extended_environment -> Netcgi_types.cgi_activation
Create the function for dyn_activation from a std_activation tag. Example: let dyn_actv = std_activation `Std_activation_unbuffered
val dynamic_service : (#Netcgi_types.cgi_activation as 'a) dynamic_service ->
[> `Dynamic_service of 'a dynamic_service ]
Configures the dynamic service.