Module Ocsigen_extensions

module Ocsigen_extensions: sig .. end

Extensions interface for Ocsigen Server


val section : Lwt_log_core.section

use Lwt_log.Section.set_level in order to debug

include Ocsigen_command
exception Ocsigen_http_error of Ocsigen_cookie_map.t * Cohttp.Code.status
exception Bad_config_tag_for_extension of string

Xml tag not recognized by an extension (usually not a real error)

exception Error_in_config_file of string

Error in a <site> tag inside the main ocsigen.conf file

exception Error_in_user_config_file of string

Option incorrect in a userconf file

type file_info = Ocsigen_multipart.file_info = {
   tmp_filename : string;
   filesize : int64;
   raw_original_filename : string;
   file_content_type : ((string * string) * (string * string) list) option;
}
val badconfig : ('a, unit, string, 'b) Stdlib.format4 -> 'a

Convenient function for raising Error_in_config_file exceptions with a sprintf-formatted argument.

type virtual_hosts = (string * Re.Pcre.regexp * int option) list 

Type of the result of parsing the field hostfiler in the configuration file. Inside the list, the first argument is the host itself (which is a glob-like pattern that can contains *), a regexp parsing this pattern, and optionally a port.

val hash_virtual_hosts : virtual_hosts -> int
val equal_virtual_hosts : virtual_hosts -> virtual_hosts -> bool
val host_match : virtual_hosts:virtual_hosts ->
host:string option -> port:int -> bool
type do_not_serve = {
   do_not_serve_regexps : string list;
   do_not_serve_files : string list;
   do_not_serve_extensions : string list;
}

Configuration to hide/forbid local files

val serve_everything : do_not_serve
exception IncorrectRegexpes of do_not_serve
val do_not_serve_to_regexp : do_not_serve -> Re.Pcre.regexp

Compile a do_not_serve structure into a regexp. Raises IncorrectRegexpes if the compilation fails. The result is memoized for subsequent calls with the same argument

val join_do_not_serve : do_not_serve ->
do_not_serve -> do_not_serve
type config_info = {
   default_hostname : string;
   default_httpport : int;
   default_httpsport : int;
   default_protocol_is_https : bool;
   mime_assoc : Ocsigen_charset_mime.mime_assoc;
   charset_assoc : Ocsigen_charset_mime.charset_assoc;
   default_directory_index : string list; (*

Default name to use as index file when a directory is requested. Use None if no index should be tried. The various indexes are tried in the given order. If no index is specified, or the index does not exists, the content of the directory might be listed, according to list_directory_content

*)
   list_directory_content : bool; (*

Should the list of files in a directory be displayed if there is no index in this directory ?

*)
   follow_symlinks : [ `Always | `No | `Owner_match ]; (*

Should symlinks be followed when accessing a local file?

*)
   do_not_serve_404 : do_not_serve;
   do_not_serve_403 : do_not_serve;
   uploaddir : string option;
   maxuploadfilesize : int64 option;
}

Configuration options, passed to (and modified by) extensions

val default_config_info : unit -> config_info
type request = {
   request_info : Ocsigen_request.t;
   request_config : config_info;
}
exception Ocsigen_is_dir of (Ocsigen_request.t -> Uri.t)
type answer = 
| Ext_do_nothing (*

I don't want to do anything

*)
| Ext_found of (unit -> Ocsigen_response.t Lwt.t) (*

"OK stop! I will take the page. You can start the following request of the same pipelined connection. Here is the function to generate the page". The extension must return Ext_found as soon as possible when it is sure it is safe to start next request. Usually immediately. But in some case, for example proxies, you don't want the request of one connection to be handled in different order. (for example revproxy.ml starts its requests to another server before returning Ext_found, to ensure that all requests are done in same order).

*)
| Ext_found_stop of (unit -> Ocsigen_response.t Lwt.t) (*

Found but do not try next extensions

*)
| Ext_next of Cohttp.Code.status (*

Page not found. Try next extension. The status is usually `Not_found, but may be for example `Forbidden (403) if you want to try another extension afterwards. Same as Ext_continue_with but does not change the request.

*)
| Ext_stop_site of (Ocsigen_cookie_map.t * Cohttp.Code.status) (*

Error. Do not try next extension, but try next site.

*)
| Ext_stop_host of (Ocsigen_cookie_map.t * Cohttp.Code.status) (*

Error. Do not try next extension, do not try next site, but try next host.

*)
| Ext_stop_all of (Ocsigen_cookie_map.t * Cohttp.Code.status) (*

Error. Do not try next extension, do not try next site, do not try next host.

*)
| Ext_continue_with of (request * Ocsigen_cookie_map.t * Cohttp.Code.status) (*

Used to modify the request before giving it to next extension. The extension returns the request (possibly modified) and a set of cookies if it wants to set or cookies (Ocsigen_cookie_map.empty for no cookies). You must add these cookies yourself in request if you want them to be seen by subsequent extensions, for example using Ocsigen_http_frame.compute_new_ri_cookies. The status is usually equal to the one received from preceding extension (but you may want to modify it).

*)
| Ext_retry_with of request * Ocsigen_cookie_map.t (*

Used to retry all the extensions with a new request. The extension returns the request (possibly modified) and a set of cookies if it wants to set or cookies (Ocsigen_cookie_map.empty for no cookies). You must add these cookies yourself in request if you want them to be seen by subsequent extensions, for example using Ocsigen_http_frame.compute_new_ri_cookies.

*)
| Ext_sub_result of extension_composite (*

Used if your extension want to define option that may contain other options from other extensions. In that case, while parsing the configuration file, call the parsing function (of type parse_fun), that will return something of type extension_composite.

*)
| Ext_found_continue_with of (unit -> (Ocsigen_response.t * request) Lwt.t) (*

Same as Ext_found but may modify the request.

*)
| Ext_found_continue_with' of (Ocsigen_response.t * request) (*

Same as Ext_found_continue_with but does not allow to delay the computation of the page. You should probably not use it, but for output filters.

*)
type request_state = 
| Req_not_found of (Cohttp.Code.status * request)
| Req_found of (request * Ocsigen_response.t)
type extension_composite = Ocsigen_cookie_map.t ->
request_state ->
(answer * Ocsigen_cookie_map.t) Lwt.t
type extension = request_state -> answer Lwt.t 

For each <site> tag in the configuration file, you can set the extensions you want. Each extension is implemented as a function, taking the charset found in configuration file, the current state of the request, and returning an answer. If no page has been generated so far (Req_not_found), it receive the error code given by the previous extension (default 404), and the request information. If a page has been generated by previous extensions (case Req_found), the extension may want to modify the result (filters).

type parse_fun = Xml.xml list -> extension_composite 
type parse_host 

Type of the functions parsing the content of a <host> tag

type userconf_info = {
   localfiles_root : string;
}

Information received by extensions accepting userconf files.

The parameter localfiles_root is an absolute path to the directory that the user is allowed to serve. This is used by staticmod, to disallow the user from allowing access to outside of this directory

type parse_config = userconf_info option ->
virtual_hosts ->
config_info -> parse_config_aux

parse_config is the type of the functions parsing a <site> tag (and returning an extension). Those are functions taking

that will be called for each <host>, and that will generate a function taking:

that will be called for each <site>, and that will generate a function taking:

that will be called on each tag inside <site> and:

parse_config_user is the type of functions parsing a site tag inside an userconf file. They take one more parameter, of type userconf_info

type parse_config_aux = Ocsigen_lib.Url.path ->
parse_host ->
parse_fun -> Xml.xml -> extension
val register : name:string ->
?fun_site:parse_config ->
?end_init:(unit -> unit) ->
?init_fun:(Xml.xml list -> unit) ->
?exn_handler:(exn -> string) -> ?respect_pipeline:bool -> unit -> unit

For each extension generating pages, we register its name and six functions:

Moreover, if the optional parameter ?respect_pipeline is true, the extension will ask the server to respect the order of the pipeline. That means that it will wait to be sure that the previous request from the same connection has been taken by an extension before giving a request to an extension. Use this to write proxies extensions, when you want to be able to pipeline the requests you to another server. It is false by default.

module Configuration: sig .. end

This modules contains types and constructor for the description of XML configurations and the accordingly parsing.

val get_hostname : request -> string

Returns the hostname to be used for absolute links or redirections. It is either the Host header or the hostname set in the configuration file.

val get_port : request -> int

Returns the port to be used for absolute links or redirections. It is either:

val new_url_of_directory_request : request -> Ocsigen_request.t -> Uri.t

new_url_of_directory_request create a redirection and generating a new url for the client (depending on the server configuration and request)

User directories

Exception raised when an non-existing user is found

exception NoSuchUser
type ud_string 

The type for string that may contain a $u(...)

val parse_user_dir : string -> ud_string
val replace_user_dir : Re.Pcre.regexp -> ud_string -> string -> string

raises Not_found is the directory does not exist

exception Not_concerned

Regular expressions for redirections

val find_redirection : Re.Pcre.regexp -> bool -> string -> Ocsigen_request.t -> string