Module Nethttpd_plex

module Nethttpd_plex: sig .. end

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 

val std_log_error : Netplex_types.container -> config_log_error

val std_log_access : ?debug:bool -> Netplex_types.container -> config_log_access

val std_error_response : config_error_response

val restrict_file_service_config : Netplex_types.config_file -> Netplex_types.address -> unit

val read_file_service_config : Netplex_types.config_file ->
       Netplex_types.address -> string -> Nethttpd_services.file_service

val restrict_dynamic_service_config : Netplex_types.config_file -> Netplex_types.address -> unit

val read_dynamic_service_config : (string *
        (Netplex_types.config_file ->
         Netplex_types.address ->
         string -> (#Netcgi.cgi_activation as 'a) Nethttpd_services.dynamic_service))
       list ->
       Netplex_types.config_file ->
       Netplex_types.address -> string -> 'a Nethttpd_services.dynamic_service

type encap = [ `Engine | `Reactor ] 

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

type (#Netcgi.cgi_activation
       , [ `Dynamic_service of
             (#Netcgi.cgi_activation as 'a) Nethttpd_services.dynamic_service
         | `File_service of Nethttpd_services.file_service ]) service_factory = (string * 'a Nethttpd_services.dynamic_service) list ->
       Netplex_types.config_file ->
       Netplex_types.address ->
       string ->
       [ `Dynamic_service of 'a Nethttpd_services.dynamic_service
       | `File_service of Nethttpd_services.file_service ]
       Nethttpd_types.http_service 

val default_services : (string *
        (#Netcgi.cgi_activation as 'a,
         [ `Dynamic_service of 'a Nethttpd_services.dynamic_service
         | `File_service of Nethttpd_services.file_service ])
        service_factory)
       list

type httpd_factory = {

val nethttpd_factory : ?name:string ->
       ?hooks:Netplex_types.processor_hooks ->
       ?encap:encap ->
       ?config_cgi:Netcgi.config ->
       ?handlers:(string *
                  (#Netcgi.cgi_activation as 'a) Nethttpd_services.dynamic_service)
                 list ->
       ?services:(string *
                  ('a,
                   [ `Dynamic_service of 'a Nethttpd_services.dynamic_service
                   | `File_service of Nethttpd_services.file_service ])
                  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 ->
       ?tls:(module Netsys_crypto_types.TLS_PROVIDER) ->
       unit -> Netplex_types.processor_factory

Configuration files

The configuration file understood by nethttpd_factory looks 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.

Configuring TLS

First of all, there needs to be a TLS provider. See Tls for more information how to get one.

If the TLS provider is initialized, you can have a tls subsection inside processor, like:

processor {
  ...
  tls {
    x509 {
      trust {
        crt_file = "ca.pem";
      }
      key {
        crt_file = "server.crt";
        key_file = "server.key";
      }
    }
  }
}

All of the files, ca.pem, server.crt and server.key need to be PEM-encoded. You can have several key sub-sections when you want to do name-based virtual hosting. Note, however, that this relies on the SNI extension of the TLS protocol, and not all clients support this extension.

Further parameters inside tls:

• algorithms: This is a string describing the cipher suites and protocol options that are in effect. This string is provider-specific. (GnuTLS calls this string the "priority string".) Example:

  tls {
     ...
     algorithms = "SECURE-128 !ARCFOUR-128";
  }
     

• dh_params: This sub-section may set DH parameters. Example:

  tls {
    ...
    dh_params {
      pkcs3_file = "/path/to/pkcs3_file";
    }
  }
     

• peer_auth: This string parameter may enable client certificates. Set it to "required" to enforce such a certificate.

  tls {
    ...
    peer_auth = "required";
  }