libnethttpd-ocaml-dev 3.7.3-4 / usr / lib / ocaml / nethttpd / nethttpd_plex.mli

(* $Id: nethttpd_plex.mli 1488 2010-09-30 22:10:06Z gerd $ *)

(** {1 Netplex support} *)

(** The important function is [nethttpd_factory], see below. The
    other functions are only needed for special effects.

    An example is explained here: {!Netplex_intro.webserver}
 *)

type config_log_error = Nethttpd_types.request_info -> string -> unit
type config_log_access = Nethttpd_types.full_info -> unit
type config_error_response = Nethttpd_types.error_response_params -> string
  (** Three type abbreviations for logging functions *)

val std_log_error : Netplex_types.container -> config_log_error 
  (** Returns a function that logs errors using the [log_subch] method of
      the passed container
   *)

val std_log_access : ?debug:bool -> 
                     Netplex_types.container -> config_log_access
  (** Returns a function that logs accesses using the [log_subch] method of
      the passed container

      If [debug] is set, additional debug log messages are printed that
      dump the whole access (incl. header and all available information)
   *)

val std_error_response : config_error_response
  (** A sample error response function *)

val restrict_file_service_config : Netplex_types.config_file ->
                                   Netplex_types.address ->  unit
  (** Restricts the subsections and paremeters in the [service]
      configuration section of type "file" to the allowed ones.
   *)


val read_file_service_config : Netplex_types.config_file ->
                               Netplex_types.address -> 
                               string ->
                                 Nethttpd_services.file_service
  (** [read_file_service_config cfg addr uri_path]: Reads the
      [service] configuration section of type "file" from config file
      [cfg] at address [addr].  [uri_path] is the default value put
      into the [file_uri] component of the returned record if no "uri"
      configuration parameter exists. (In other words, this is the
      path of the enclosing "uri" section, or "/" if there is only
      a "host" section.) All other parameters are only
      taken from the configuration section. 

      See below at [nethttpd_factory] how a file service needs to
      be configured.
   *)

val restrict_dynamic_service_config : Netplex_types.config_file ->
                                      Netplex_types.address ->  unit
  (** Restricts the subsections and paremeters in the [service]
      configuration section of type "dynamic" to the allowed ones.
   *)

val read_dynamic_service_config : 
      (string * (Netplex_types.config_file ->
                 Netplex_types.address -> 
                 string ->
                   'a Nethttpd_services.dynamic_service
                ) ) list ->
      Netplex_types.config_file ->
      Netplex_types.address -> 
      string ->
        'a Nethttpd_services.dynamic_service
  (** [read_dynamic_service_config handlers cfg addr uri_path]:
      Reads the [service] configuration section of type "dynamic" from config 
      file [cfg] at address [addr]. The alist [handlers] defines the
      available handlers. Every handler [h] is called like
      [h cfg addr uri_path]. [uri_path] is like in [read_file_service_config],
      i.e. the path of the enclosing "uri" section, or "/" by default.

      The [h] function has to return the dynamic service to use, which
      is also returned by [read_dynamic_service_config].

      See below at [nethttpd_factory] how a dynamic service needs to
      be configured.
   *)


type encap = [ `Reactor | `Engine ]

val nethttpd_processor : 
  ?hooks:Netplex_types.processor_hooks ->
  ?encap:encap ->
  (Netplex_types.container -> #Nethttpd_reactor.http_reactor_config) ->
  'a Nethttpd_types.http_service ->
  Netplex_types.processor
    (** [netplex_processor mk_config http_service]: Creates a Netplex processor
    * for Nethttpd.
    *
    * [mk_config] determines the nethttpd config for a container.
    * This is especially useful for setting the logging functions.
    *
    * The resulting processor must be turned into a full Netplex service
    * by [Netplex_sockserv.create_socket_service] which can then be added
    * by calling the controller's method [add_service].
    *
    * [hooks]: One can pass a Netplex hook object to set the hooks of the
    * processor.
    *
    * [encap]: Selects the encapsulation, [`Reactor] or [`Engine]. 
    * The default is [`Reactor]. Each encapsulation has specific strengths
    * and weaknesses:
    * - [`Reactor] is simpler code. Also, the request and response bodies
    *   need not to be buffered up, and are directly connected with the 
    *   underlying socket (low memory requirement). The disadvantage is
    *   that a reactor processes TCP connections serially (important to know
    *   when there is only a single Unix process)
    * - [`Engine]: The request body needs to be completely buffered up.
    *   If pipelining is enabled, the response bodies are also buffered
    *   (FIXME).
    *   The advantage of this encapsulation is that the engine can
    *   process multiple TCP connections simultaneously, even in a 
    *   single process/thread.
     *)

type ('a,'b) service_factory =
    (string * 'a Nethttpd_services.dynamic_service) list ->
    Netplex_types.config_file ->
    Netplex_types.address -> 
    string ->
      'b Nethttpd_types.http_service
    constraint 'b = [ `Dynamic_service of 'a Nethttpd_services.dynamic_service
                    | `File_service of Nethttpd_services.file_service 
		    ]
  (** The service factory function is called when a [service] configuration
      section of a certain type needs to be read. The function has args
      [handlers], [cfg], [addr], and [uri_path]. It needs to return the
      [http_service].

      Such a function is usually [read_file_service_config], or
      [read_dynamic_service_config], or a derivative, whose return
      value is turned into a [http_service]. This can be done with
      {!Nethttpd_services.file_service} and
      {!Nethttpd_services.dynamic_service}.
   *)

val default_services : (string * ('a,'b) service_factory) list
  (** The default services *)

type httpd_factory =
    { httpd_factory :
	'a . 
	  (Netplex_types.container -> Nethttpd_reactor.http_reactor_config) ->
	    'a Nethttpd_types.http_service ->
	      Netplex_types.processor
    }
  (** The type of the [nethttpd_processor] function *)


val nethttpd_factory :
      ?name:string ->
      ?hooks:Netplex_types.processor_hooks ->
      ?encap:encap ->
      ?config_cgi:Netcgi.config -> 
      ?handlers:(string * 'a Nethttpd_services.dynamic_service) list ->
      ?services:(string * ('a,'b) service_factory) list ->
      ?log_error:(Netplex_types.container -> config_log_error) ->
      ?log_access:(?debug:bool -> Netplex_types.container -> config_log_access) ->
      ?error_response:config_error_response -> 
      ?processor_factory:httpd_factory ->
      unit ->
        Netplex_types.processor_factory
  (** Factory for a web server component.
    *
    * {b Configuration file.} Reads a configuration section like
    * {[
    *    processor {
    *      type = "nethttpd";          (* or what is passed as "name" arg *)
    *      timeout = 300.0;
    *      timeout_next_request = 15.0;
    *      access_log = "enabled";
    *      suppress_broken_pipe = true;
    *      host {
    *        pref_name = "myhost";     (* optional *)
    *        pref_port = 80;           (* optional *)
    *        names = "myhost:80 yourhost:81";  (* use *:0 for any name *)
    *        uri {
    *          path = "/the/path";
    *          method {
    *            allow = "GET POST";
    *            (* or: deny = "..." *)
    *            service {
    *              type = "...";
    *              ...
    *            }
    *          }
    *        }
    *        uri {
    *          ...
    *        }
    *      }
    *      host {
    *        ...
    *      }
    *    }
    * ]}
    *
    * The [access_log] parameter can be set to [off], [enabled], or [debug].
    * The default is [off]. Access messages go to the "access" subchannel
    * of the component logger. If [enabled], one line is printed with the
    * most important data. If [debug] is set, all access data are printed.
    *
    * If [suppress_broken_pipe] the error "Broken pipe" is not logged
    * in the error log. This error occurs frequently, and may be regarded
    * as a normal condition.
    *
    * The sections [host], [uri] and [method] can be nested to any depth.
    * However, on every nesting level only one of these section types must be
    * used. For example, if a [host] section already contains [uri]
    * subsections, it is not allowed to add [method] subsections.
    * Furthermore, the outermost section must be [host].
    *
    * The [service] section may be one of (at least if the [services]
    * parameter is not overridden):
    *
    * {[
    *    service {
    *      type = "file";
    *      docroot = "/a/path/in/the/filesystem";
    *      uri = "/the/uri/prefix/corresponding/to/docroot";
    *      media_types_file = "/etc/mime.types";
    *      media_type {
    *        type = "application/foo";
    *        suffix = "foo"
    *      }
    *      default_media_type = "text/plain";
    *      enable_gzip = true;   (* see doc in nethttpd_services.mli *)
    *      index_files = "index.html";
    *      enable_listings = true;
    *      hide_from_listings = "README";   (* list of PCRE regexps *)
    *    }
    * ]}
    *
    * Note that [uri] is taken from the surrounding [uri] section (or
    * assumed to be "/" if there is none) if omitted.
    *
    * {[
    *    service {
    *      type = "dynamic";
    *      handler = "name_of_handler";
    *    }
    * ]}
    *
    * Binds the passed handler here.
    *
    * Any of [host], [uri], and [method] sections may contain one or several
    * [access] sections (which are AND-connected):
    *
    * {[
    *    access {
    *      type = "host";
    *      allow = "host1 host2 ...";
    *      (* or deny = "host1 host2 ..."; *)
    *    }
    * ]}
    *
    * Other access control methods are not yet available.
    *
    * The [services] optional argument can be used to change the service
    * types understood. If not passed, it defaults to [default_services].
    * The default includes "file" and "dynamic".
    *
    * {b Arguments.}
    *
    * - [name]: The processor name. Defaults to "nethttpd". This name can
    *   be referenced by the "type" parameters in the [processor] section
    *   of the config file.
    * - [hooks]: One can pass a Netplex hook object to set the hooks of the
    *   processor. (This argument is ignored if a [processor_factory] is
    *   passed to this function.)
    * - [encap]: See {!Nethttpd_plex.nethttpd_processor}. (This argument is
    *   ignored if a [processor_factory] is
    *   passed to this function.)
    * - [config_cgi]: The CGI configuration to use
    * - [handlers]: a list of handler function. These functions can be
    *   referenced from a [service] section in the config file where
    *   [type="dynamic"] (see example above). Defaults to the empty list.
    * - [services]: A list of service handlers that can be used 
    *   by [service] sections in the config files. Defaults to
    *   {!Nethttpd_plex.default_services} which defines "file" and "dynamic".
    * - [log_error]: The error logger. Defaults to
    *   {!Nethttpd_plex.std_log_error}.
    * - [log_access]: The access logger. Defaults to
    *   {!Nethttpd_plex.std_log_access}.
    * - [error_response]: a handler which is invoked to generate error
    *   responses. Defaults to {!Nethttpd_plex.std_error_response}.
    * - [processor_factory]: the function creating the processor.
    *   Default is [nethttpd_processor].
   *)