libnethttpd-ocaml-dev 4.1.2-3 / usr / lib / ocaml / nethttpd / nethttpd_services.mli

(* $Id$
 *
 *)

(*
 * Copyright 2005 Baretta s.r.l. and Gerd Stolpmann
 *
 * This file is part of Nethttpd.
 *
 * Nethttpd is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * Nethttpd is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Nethttpd; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *)

(** {1 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.
 *)

(* Predefined service providers: *)

open Nethttpd_types

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:
    * - The [Host] header is mentioned in [server_names], or if
    * - The request has been accepted on the port contained in [server_addresses]
    *
    * 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 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 ] http_service
  (** 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 ] http_service
  (** This service responds to "OPTIONS *" requests, and nothing else *)

type 'a uri_distributor =
    ( string * 'a 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 ] http_service
  (** Configures URI distribution. The incoming request URI is normalized before
    * being matched, and the request is rewritten to the normalized URI.
    *
    * Normalization includes:
    * - Removal of [.] path components
    * - Resolution of [..] path components
    * 
    * If the path starts with [..] after normalization, the request is rejected.
   *)

type 'a linear_distributor =
    ( (extended_environment -> bool) * 'a http_service ) list
  (** 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 ] http_service
  (** 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 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 ] http_service
  (** Configures method distribution *)

type file_option =
    [ `Enable_gzip
    | `Enable_cooked_compression
    | `Override_compression_suffixes of (string * string) list
    | `Enable_index_file of string list
    | `Enable_listings of 
	extended_environment -> Netcgi.cgi_activation -> file_service -> unit
    ]
  (** Add-on features for file services:
    * - [`Enable_gzip]: Deprecated. Same as [`Enable_cooked_compression].
    * - [`Enable_cooked_compression]: Modifies the way compressed files
    *   are handled. Normally it is required that one accesses the compressed
    *   file (with suffix such as "gz") directly to get it in compressed form.
    *   If this option is enabled, though, the server also compresses
    *   the base file (without suffix such as "gz"), but only if the
    *   base file is accompanied by a compressed version (with suffix).
    *   E.g. if there is "foo" and "foo.gz", this enables that the accesses
    *   to "foo" can make use of compression.
    * - [`Enable_index_file]: If enabled, accesses to directories are redirected
    *   to index files. The possible file names are given in the string list.
    *   E.g. [`Enable_index_file ["index.html"; "index.htm"]]. It is redirected to
    *   these files, so these can be handled by different services if neccessary.
    * - [`Enable_listings]: If enabled, directory listings are generated by calling
    *   the argument function. The [PATH_TRANSLATED] property of the environment
    *   contains the absolute name of the directory to list. The [PATH_INFO] property
    *   is the corresponding URI path. [SCRIPT_NAME] is meaningless.
    * - [`Override_compression_suffixes l]: Tags the file suffixes in
    *   [l] as compression schemes. A pair [(suffix,ce)] sets that the
    *   [suffix] means the content encoding [ce]. Knowing this is important
    *   for determining the media type of the file.
   *)

and 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 ] http_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. It is not checked whether the resulting file exists.

      This function removes a trailing slash of the translated path, if any,
      and if resulting from appending the path info component.
      Trailing slashes must not be used to deduce that directories are
      accessed.
   *)

val simple_listing : ?hide:string list -> 
             extended_environment -> Netcgi.cgi_activation -> file_service -> unit
  (** Simple listing generator for [`Enable_listings] 
    *
    * [hide]: An optional list of Str 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. (Changed in Ocamlnet-3.3:
    * [hide] uses now Str regexps, and no longer PCRE regexps.)
   *)

type std_activation_options =
   { stdactv_processing : Netcgi.arg_store option;
     stdactv_operating_type : Netcgi.output_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_unbuffered          (* Shortcut for common case *)
  | `Std_activation_buffered            (* Shortcut for common case *)
  | `Std_activation_tempfile            (* Shortcut for common case *)
  ]
  (** The way the [Netcgi_types.cgi_activation] object is created. For typical
    * usage, just take:
    * - [`Std_activation_unbuffered]: Creates a [Netcgi.std_activation] without
    *   output buffer (type [`Direct ""]) and memory-based argument processing
    * - [`Std_activation_buffered]:  Creates a [Netcgi.std_activation]
    *   with a transactions buffer in memory, and memory-based argument processing
    * - [`Std_activation_tempfile]: Creates a [Netcgi.std_activation]
    *   with a file as transactions buffer, and memory-based argument processing
    *
    * The following option is provided for detailed control:
    * - [`Std_activation opt]: Creates a [Netcgi.std_activation] with the given
    *   options
   *)

type 'a dynamic_service =
    { dyn_handler : extended_environment -> '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 : 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.
          *)
    } constraint 'a = # Netcgi.cgi_activation ;;

val std_activation : std_activation -> extended_environment -> Netcgi.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 : 
       'a dynamic_service -> [> `Dynamic_service of 'a dynamic_service ] http_service
  (** Configures the dynamic service. *)

type ac_by_host_rule =
    [ `Allow of string list
    | `Deny of string list
    ]
  (** Access control by host: 
    * - [`Allow]: Only the listed hosts are allowed; all other are denied
    * - [`Deny]: The listed hosts are denied; all other are allowed
   *)

type 'a ac_by_host = ac_by_host_rule * 'a http_service
  (** The service is protected by the access control rule *)

val ac_by_host : 'a ac_by_host -> [> `Ac_by_host of 'a ac_by_host ] http_service
  (** Configures host-based access control *)

val read_media_types_file : string -> (string * string) list
  (** Reads a text file with two columns where the left column is the
    * media type and the right column the corresponding suffix.
    * Returns the contents as pairs [ (suffix, type) ].
   *)


module Debug : sig
  val enable : bool ref
end