(* netcgi.mli
Copyright (C) 2005-2006
Christophe Troestler
email: Christophe.Troestler@umh.ac.be
WWW: http://math.umh.ac.be/an/
This library is free software; see the file LICENSE for more information.
This library 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 file
LICENSE for more details.
*)
(** Common data-structures for CGI-like connectors.
*
* This library tries to minimize the use of unsafe practices. It
* cannot be bullet proof however and you should read about
* {{:http://www.w3.org/Security/Faq/wwwsf4.html}security}.
*
* REMARK: It happens frequently that hard to predict random numbers
* are needed in Web applications. The previous version of this
* library used to include some facilities for that (in the
* [Netcgi_jserv] module). They have been dropped in favor of
* {{:http://pauillac.inria.fr/~xleroy/software.html#cryptokit}Cryptokit}.
*)
(** {2 Arguments} *)
(** Represent a key-value pair of data passed to the script (including
file uploads). *)
class type cgi_argument =
object
method name : string
(** The name of the argument. *)
method value : string
(** The value of the argument, after all transfer encodings have
been removed. If the value is stored in a file, the file will
be loaded.
@raise Argument.Oversized if the argument was discarded.
@raise Failure if the object has been finalized. *)
method open_value_rd : unit -> Netchannels.in_obj_channel
(** Open the contents of the value as an input channel. This
works for all kinds of arguments, regardless of their
[#storage] and [#representation].
@raise Argument.Oversized if the argument was discarded.
@raise Failure if the object has been finalized. *)
method store : [`Memory | `File of string]
(** Tells whether the argument is stored in memory (as a string)
or as a file (the argument of [`File] being the filename). *)
method content_type : unit -> string * (string * Netmime_string.s_param) list
(** Returns the content type of the header and its parameters as a
couple [(hdr, params)]. When the header is missing, the
result is [("text/plain", [])]. Below you will find access
method for frequently used parameters. *)
method charset : string
(** The [charset] parameter of the content type of the header, or
[""] when there is no such parameter, or no header. *)
method filename : string option
(** The [filename] parameter found in the header of file uploads.
When present, [Some name] is returned, and [None] otherwise.
(This is not to be confused with the possible local file
holding the data.) *)
method representation : [ `Simple of Netmime.mime_body
| `MIME of Netmime.mime_message ]
(** The representation of the argument.
- [`Simple] the value of the CGI argument is an unstructured
string value.
- [`MIME] The argument has a MIME header in addition to the
value. The MIME message is read-only. *)
method finalize : unit -> unit
(** Arguments stored in temp files must be deleted when the
argument is no longer used. You can call [finalize] to delete
such files. The method does not have any effect when [store =
`Memory]. The method never raises any exceptions. If the
file no longer exists (e.g. because it was moved away) or if
there are any problems deleting the file, the error will be
ignored.
The [finalize] method is not registered in the garbage
collector. You can do that, but it is usually better to call
this method manually. *)
(* FIXME: Should we do that at the end of the request anyway?
Since the request handler is a callback, this is possible. *)
(* FIXME: Reference counting? *)
end
(** Operations on arguments and lists of thereof. *)
module Argument :
sig
exception Oversized
val simple : string -> string -> cgi_argument
(** [simple_arg name value] creates an unstructured CGI argument
called [name] with contents [value]. *)
val mime : ?work_around_backslash_bug:bool ->
?name:string -> Netmime.mime_message -> cgi_argument
(** [mime_arg ?name msg] creates a MIME-structured CGI argument
called [name] with contents [msg]. You can create [msg] by
either {!Netmime.memory_mime_message} or
{!Netmime.file_mime_message}.
@param name set the name of the argument. If it is not given,
the name is extracted from the "Content-Disposition" field of
the [msg] header or it [""] if this field is not found.
@param work_around_backslash_bug Whether to work around a bug
found in almost all browsers regarding the treatment of
backslashes. The browsers do not quote backslashes in file
names. This breaks RFC standards, however. This argument is
[true] by default. *)
(** It is easy to manipulate lists of arguments with the [List]
module. For example, [List.filter (fun a -> a#name <> n) args]
will remove from [args] all occurrences of the argument with
name [n]. The following functions are helpers for operations
specific to arguments. *)
val clone : ?name:string -> ?value:string -> ?msg:Netmime.mime_message ->
cgi_argument -> cgi_argument
val set : cgi_argument list -> cgi_argument list -> cgi_argument list
(** [set new_args args] creates a list of argument from [args]
deleting the arguments whose name appears in [new_args] and
adding the [new_args] arguments. *)
end
(** Old deprecated writable argument type.
@deprecated Arguments are read-only. *)
class type rw_cgi_argument =
object
inherit cgi_argument
method ro : bool
method set_value : string -> unit
method open_value_wr : unit -> Netchannels.out_obj_channel
end
class simple_argument : ?ro:bool -> string -> string -> rw_cgi_argument
(** Old deprecated simple argument class.
@deprecated Use {!Netcgi.Argument.simple} instead. *)
class mime_argument : ?work_around_backslash_bug:bool ->
string -> Netmime.mime_message -> rw_cgi_argument
(** Old deprecated MIME argument class.
@deprecated Use {!Netcgi.Argument.mime} instead. *)
(** {2 Cookies} *)
(** Functions to manipulate cookies.
You should know that besides the [name] and [value] attribute,
user agents will send at most the [path], [domain] and [port] and
usually will not send them at all.
For interoperability, cookies are set using version 0 (by
Netscape) unless version 1 (RFC 2965 and the older RFC 2109)
fields are set. While version 0 is well supported by browsers,
RFC 2109 requires a recent browser and RFC 2965 is usually not
supported. You do not have to worry however, cookies are always
sent in such a way older browsers understand them -- albeit not
all attributes of course -- so your application can be ready for
the time RFC 2965 will be the norm.
N.B. This module appears also as {!Nethttp.Cookie}.
*)
module Cookie :
sig
type t = Nethttp.Cookie.t
(** Mutable cookie type. *)
val make :
?max_age:int ->
?domain:string ->
?path:string ->
?secure:bool ->
?comment:string ->
?comment_url:string ->
?ports:int list ->
string -> string -> t
(** [make ?expires ?domain ?path ?secure name value] creates a new
cookie with name [name] holding [value].
@param max_age see {!Netcgi.Cookie.set_max_age}.
Default: when user agent exits.
@param domain see {!Netcgi.Cookie.set_domain}.
Default: hostname of the server.
@param path see {!Netcgi.Cookie.set_path}.
Default: script name + path_info.
@param secure see {!Netcgi.Cookie.set_secure}. Default: [false].
@param comment see {!Netcgi.Cookie.set_comment}. Default: [""].
@param comment_url see {!Netcgi.Cookie.set_comment_url}.
Default: [""].
@param ports see {!Netcgi.Cookie.set_ports}.
Default: same port the cookie was sent.
*)
val name : t -> string
(** The name of the cookie. *)
val value : t -> string
(** The value of the cookie. *)
val domain : t -> string option
(** The domain of the cookie, if set. *)
val path : t -> string option
(** The path of the cookie, if set. *)
val ports : t -> int list option
(** [port c] the ports to which the cookie may be returned or [[]] if
not set. *)
val max_age : t -> int option
(** The expiration time of the cookie, in seconds. [None] means
that the cookie will be discarded when the browser exits.
This information is not returned by the browser. *)
val secure : t -> bool
(** Tells whether the cookie is secure.
This information is not returned by the browser. *)
val comment : t -> string
(** Returns the comment associated to the cookie or [""] if it
does not exists. This information is not returned by the
browser. *)
val comment_url : t -> string
(** Returns the comment URL associated to the cookie or [""] if it
does not exists. This information is not returned by the
browser. *)
val set_value : t -> string -> unit
(** [set_value c v] sets the value of the cookie [c] to [v]. *)
val set_max_age : t -> int option -> unit
(** [set_max_age c (Some t)] sets the lifetime of the cookie [c]
to [t] seconds. If [t <= 0], it means that the cookie should
be discarded immediately. [set_expires c None] tells the
cookie to be discarded when the user agent exits. (Despite
the fact that the name is borrowed from the version 1 of the
specification, it works transparently with version 0.) *)
val set_domain : t -> string option -> unit
(** Cookies are bound to a certain domain, i.e. the browser sends
them only when web pages of the domain are requested:
- [None]: the domain is the hostname of the server.
- [Some domain]: the domain is [domain]. *)
val set_path : t -> string option -> unit
(** Cookies are also bound to certain path prefixes, i.e. the
browser sends them only when web pages at the path or below are
requested.
- [None]: the path is script name + path_info
- [Some p]: the path is [p]. With [Some "/"] you can disable the
path restriction completely. *)
val set_secure : t -> bool -> unit
(** Cookies are also bound to the type of the web server:
[set_secure false] means servers without SSL, [set_secure
true] means servers with activated SSL ("https"). *)
val set_comment : t -> string -> unit
(** [set_comment c s] sets the comment of the cookie [c] to [s]
which must be UTF-8 encoded (RFC 2279). Because cookies can
store personal information, the comment should describe how
the cookie will be used so the client can decide whether to
allow the cookie or not. To cancel a comment, set it to [""].
Cookie version 1 (RFC 2109). *)
val set_comment_url : t -> string -> unit
(** [set_comment_url c url] same as {!Netcgi.Cookie.set_comment}
except that the cookie comment is available on the page
pointed by [url]. To cancel, set it to [""].
Cookie version 1 (RFC 2965). *)
val set_ports : t -> int list option -> unit
(** [set ports c (Some p)] says that the cookie [c] must only be
returned if the server request comes from one of the listed
ports. If [p = []], the cookie will only be sent to the
request-port it was received from. [set_ports c None] says
that the cookie may be sent to any port.
Cookie version 1 (RFC 2965). *)
val of_netscape_cookie : Nethttp.netscape_cookie -> t
(** Convert a Netscape cookie to the new representation *)
val to_netscape_cookie : t -> Nethttp.netscape_cookie
(** Convert to Netscape cookie (with information loss) *)
end
(** {2 The environment of a request} *)
type http_method =
[`GET | `HEAD | `POST | `DELETE | `PUT]
type config = Netcgi_common.config = {
tmp_directory : string;
(** The directory where to create temporary files. This should be
an absolute path name. *)
tmp_prefix : string;
(** The name prefix for temporary files. This must be a non-empty
string. It must not contain '/'. *)
permitted_http_methods : http_method list;
(** The list of accepted HTTP methods *)
permitted_input_content_types : string list;
(** The list of accepted content types in requests.
Content type parameters (like "charset") are ignored.
If the list is empty, all content types are allowed. *)
input_content_length_limit : int;
(** The maximum size of the request, in bytes. *)
max_arguments : int;
(** The maximum number of CGI arguments *)
workarounds : [ `MSIE_Content_type_bug | `Backslash_bug
| `Work_around_MSIE_Content_type_bug
| `Work_around_backslash_bug ] list;
(** The list of enabled workarounds.
- [`MSIE_Content_type_bug]
- [`Backslash_bug] A common error in MIME implementations is not
to escape backslashes in quoted string and comments. This
workaround mandates that backslashes are handled as normal
characters. This is important for e.g. DOS filenames because,
in the absence of this, the wrongly encoded "C:\dir\file" will
be decoded as "C:dirfile".
Remark: [`Work_around_MSIE_Content_type_bug] and
[`Work_around_backslash_bug] are deprecated versions of,
respectively, [`MSIE_Content_type_bug] and [`Backslash_bug]. *)
default_exn_handler : bool;
(** Whether to catch exceptions raised by the script and display an
error page. This will keep the connector running even if your
program has bugs in some of its components. This will however
also prevent a stack trace to be printed; if you want this turn
this option off. *)
}
val default_config : config
(** The default configuration is:
- [tmp_directory]: {!Netsys_tmp.tmp_directory()}
- [tmp_prefix]: "netcgi"
- [permitted_http_methods]: [`GET], [`HEAD], [`POST].
- [permitted_input_content_types]: ["multipart/form-data"],
["application/x-www-form-urlencoded"].
- [input_content_length_limit]: [maxint] (i.e., no limit).
- [max_arguments = 10000] (for security reasons)
- [workarounds]: all of them.
- [default_exn_handler]: set to [true].
To create a custom configuration, it is recommended to use this syntax:
{[
let custom_config = { default_config with tmp_prefix = "my_prefix" }
]}
(This syntax is also robust w.r.t. the possible addition of new
config flields.) *)
(** The environment of a request consists of the information available
besides the data sent by the user (as key-value pairs). *)
class type cgi_environment =
object
(** {3 CGI properties}
The following properties are standardised by CGI. The methods
return [""] (or [None] in the case of the port number) when the
property is not available. *)
method cgi_gateway_interface : string
method cgi_server_name : string
method cgi_server_port : int option
method cgi_server_protocol : string
method cgi_server_software : string
method cgi_request_method : string
(** We recommend you to use the method {!Netcgi.cgi.request_method}
which is more type-safe and informative. *)
method cgi_script_name : string
method cgi_path_info : string
method cgi_path_translated : string
method cgi_auth_type : string
method cgi_remote_addr : string
method cgi_remote_host : string
method cgi_remote_user : string
method cgi_remote_ident : string
method cgi_query_string : string
(** This is the row query string. The {!Netcgi.cgi} class gives
you an easy access to the arguments through the [#arg...]
methods. *)
method protocol : Nethttp.protocol
(** The server protocol in a decoded form. It can be either
- [`Http((major,minor),attributes)] or
- [`Other]. *)
method cgi_property : ?default:string -> string -> string
(** Returns a (possibly non-standard) CGI environment property.
If the property is not set, [Not_found] is be raised unless
the [default] argument is passed. The [default] argument
determines the result of the function in this case.
The method takes the case-sensitive name and returns the value
of the property. Usually, these properties have uppercase
names.
For example, [cgi_gateway_interface] returns the same as {[
cgi_property ~default:"" "GATEWAY_INTERFACE" ]}
You cannot access the fields coming from the HTTP header. Use
the method [input_header_field] instead. *)
method cgi_properties : (string * string) list
(** Return all properties as an associative list. *)
method cgi_https : bool
(** A well-known extension is the HTTPS property. It indicates
whether a secure connection is used (SSL/TLS). This method
interprets this property and returns true if the connection is
secure. This method fails if there is a HTTPS property with
an unknown value. *)
(** {3 Header of the incoming HTTP request.} *)
method input_header : Netmime.mime_header
(** The whole HTTP header. *)
method input_header_field : ?default:string -> string -> string
(** [#input_header_field ?default f] returns the value of a field
[f] of the HTTP request header. The field name [f] is
case-insensitive; if the name is a compound name, the parts
are separated by "-", e.g. ["content-length"]. If there are
several fields with the same name only the first field will be
returned.
@raise Not_found if the field does not exist, unless the
[default] argument is passed. The [default] argument is the
result of the function in this case. *)
method multiple_input_header_field : string -> string list
(** Returns the values of all fields with the passed name of the
request header. *)
method input_header_fields : (string * string) list
(** Returns the input header as (name,value) pairs. The names may
consist of lowercase or uppercase letters. *)
method cookie : string -> Cookie.t
(** [#cookie cn] returns the cookie with name [cn].
@raise Not_found if such a cookie does not exists. *)
method cookies : Cookie.t list
(** Returns the list of valid cookies found in the request header.
Here "valid" means that the decode function does not raise an
exception. *)
method user_agent : string
(** This is a convenience method that returns the ["User-agent"]
field of the HTTP request header. *)
method input_content_length : int
(** Returns the ["Content-length"] request header field.
@raise Not_found if it is not set. *)
method input_content_type_string : string
(** Returns the ["Content-type"] request header field as a plain
string or [""] if it is not set. *)
method input_content_type :
unit -> string * (string * Netmime_string.s_param) list
(** Returns the parsed ["Content-type"] request header field.
@raise Not_found if it is not set.
See also {!Netmime_string.scan_mime_type_ep}. *)
(** {3 Response header} *)
method output_header : Netmime.mime_header
(** The whole HTTP response header *)
method output_header_field : ?default:string -> string -> string
(** Returns the value of a field of the response header. If the
field does not exist, [Not_found] will be raised unless the
[default] argument is passed. The [default] argument determines
the result of the function in this case.
If there are several fields with the same name only the first
field will be returned.
The anonymous string is the name of the field. The name is
case-insensitive, and it does not matter whether it consists
of lowercase or uppercase letters. If the name is a compound
name, the parts are separated by "-", e.g. ["content-length"].
*)
method multiple_output_header_field : string -> string list
(** Returns the values of all fields with the passed name of the
repsonse header. *)
method output_header_fields : (string * string) list
(** Returns the output header as (name,value) pairs. The names may
consist of lowercase or uppercase letters. *)
method set_output_header_field : string -> string -> unit
(** Sets the value of a field of the response header. The
previous value, if any, is overwritten. If there have been
multiple values, all values will be removed and replaced by
the single new value. *)
method set_multiple_output_header_field : string -> string list -> unit
(** Sets multiple values of a field of the response header. Any
previous values are removed and replaced by the new values.
*)
method set_output_header_fields : (string * string) list -> unit
(** Sets the complete response header at once. *)
method set_status : Nethttp.http_status -> unit
(** Sets the response status. This is by definition the same as
setting the [Status] output header field. *)
method send_output_header : unit -> unit
(** This method will encode and send the output header to the
output channel. Note that of the output_channel is
[`Transactionnal] (as opposed to [`Direct]), no output will
actually take place before you issue [#commit_work()] -- thus
a [#rollback_work()] will also rollback the headers as
expected. *)
(** {3 The output channel transferring the response} *)
method output_ch : Netchannels.out_obj_channel
(** @deprecated Use [#out_channel] instead. *)
method out_channel : Netchannels.out_obj_channel
(** The "raw" output channel. In general you should use instead
{!Netcgi.cgi}[#out_channnel] which supports transactions (if you
choose to). Access to the "raw" channel is useful however,
for example for sending images or download of files (for which
transactions are not interesting but merely more work). *)
(** {3 Logging} *)
method log_error : string -> unit
(** [#log_error msg] appends [msg] to the webserver log. *)
(** {3 Miscellaneous} *)
method config : config
(** The configuration of the request. *)
end
(** {2 CGI object} *)
type other_url_spec = [ `Env | `This of string | `None ]
(** Determines how an URL part is generated:
- [`Env]: Take the value from the environment.
- [`This v]: Use this value [v]. It must already be URL-encoded.
- [`None]: Do not include this part into the URL.
*)
type query_string_spec = [ `Env | `This of cgi_argument list | `None
| `Args of rw_cgi_argument list ]
(** Determines how the query part of URLs is generated:
- [`Env]: The query string of the current request.
- [`This l]: The query string is created from the specified
argument list [l].
- [`None]: The query string is omitted.
- [`Args]: {i deprecated}, use [`This]
(left for backward compatibility).
*)
type cache_control = [ `No_cache | `Max_age of int | `Unspecified ]
(** This is only a small subset of the HTTP 1.1 cache control
features, but they are usually sufficient, and they work for
HTTP/1.0 as well. The directives mean:
- [`No_cache]: Caches are disabled. The following headers are
sent: [Cache-control: no-cache], [Pragma: no-cache], [Expires:]
(now - 1 second). Note that many versions of Internet Explorer
have problems to process non-cached contents when TLS/SSL is
used to transfer the file. Use [`Max_age] in such cases (see
http://support.microsoft.com/kb/316431).
- [`Max_age n]: Caches are allowed to store a copy of the
response for [n] seconds. After that, the response must be
revalidated. The following headers are sent: [Cache-control:
max-age n], [Cache-control: must-revalidate], [Expires:] (now +
[n] seconds)
- [`Unspecified]: No cache control header is added to the
response.
Notes:
- Cache control directives only apply to GET requests; POST
requests are never cached.
- Not only proxies are considered as cache, but also the local
disk cache of the browser.
- HTTP/1.0 did not specify cache behaviour as strictly as
HTTP/1.1 does. Because of this the [Pragma] and [Expires]
headers are sent, too. These fields are not interpreted by
HTTP/1.1 clients because [Cache-control] has higher precedence.
*)
(** Object symbolizing a CGI-like request/response cycle.
This is the minimal set of services a connector must provide.
Additional methods may be defined for specific connectors. *)
class type cgi =
object
(** {3 Arguments -- data sent to the script} *)
method argument : string -> cgi_argument
(** [#argument name] returns the value of the argument named [name].
If the argument appears several times, only one of its
instances is used.
@raise Not_found if no such argument exists. *)
method argument_value : ?default:string -> string -> string
(** [#argument_value] returns the value of the argument as a
string. If the argument does not exist, the [default] is
returned. @param default defaults to [""]. *)
method argument_exists : string -> bool
(** [#argument_exists] returns [false] if the named parameter is
missing and [true] otherwise. *)
method multiple_argument : string -> cgi_argument list
(** [#multiple_argument name] returns all the values of the
argument named [name]. *)
method arguments : cgi_argument list
(** The complete list of arguments. *)
method environment : cgi_environment
(** The environment object. This object is the "outer layer" of the
activation object that connects it with real I/O channels. *)
method request_method : [ `GET | `HEAD | `POST | `DELETE
| `PUT of cgi_argument]
(** The HTTP method used to make the request. *)
method finalize : unit -> unit
(** This method calls [#finalize] for every CGI argument
(including the possible one of PUT) to ensure that all files
are deleted. It also executes all functions registered with
[#at_exit]. It does not close the in/out channels, however.
This method is not registered in the garbage collector, and it
is a bad idea to do so. However, all connectors offered in
Netcgi automatically call [#finalize] at the end of the
request cycle (even when its terminated by an uncaught exception
when [#config.default_exn_handler] is true) so you do not have
to worry much about calling it yourself. *)
(** {3 Self-referencing URL} *)
method url : ?protocol:Nethttp.protocol ->
?with_authority:other_url_spec -> (* default: `Env *)
?with_script_name:other_url_spec -> (* default: `Env *)
?with_path_info:other_url_spec -> (* default: `Env *)
?with_query_string:query_string_spec -> (* default: `None *)
unit -> string
(** Returns the URL of the current CGI-like script. (Note that it
may differ from the actual URL that requested the script if,
for example, rewriting rules were specified in the web server
configuration.)
@param protocol The URL scheme. By default, the URL scheme is
used that is described in the environment
@param with_authority Whether to include authority part
(e.g. http or https) of the URL, and if yes, from which
source. Default: [`Env].
@param with_script_name Whether to include the part of the URL
path identifying the CGI script, and if yes, from which
source. Default: [`Env].
@param with_path_info Whether to include the rest of the URL
path exceeding the script name, and if yes, from which source.
Default: [`Env].
@param with_query_string Whether to include a query string,
and if yes, which one. Only arguments with [#store] being
[`Memory] will be added. Default: [`None], i.e. no query
string. *)
(** {3 Outputting} *)
method set_header :
?status:Nethttp.http_status ->
?content_type:string ->
?content_length:int ->
?set_cookie:Nethttp.cookie list ->
?set_cookies:Cookie.t list ->
?cache:cache_control ->
?filename:string ->
?language:string ->
?script_type:string ->
?style_type:string ->
?fields:(string * string list) list ->
unit -> unit
(** Sets the header (removing any previous one). When the output
channel supports transactions, it is possible to set the
header (possibly several times) until the [#out_channel] is
commited for the first time or [#env#send_output_header()] is
called. When there is no support for transactions, the header
must be set before the first byte of output is written.
If [#set_header] is called a second time, it will overwrite
{i all} the header fields.
@param status Sets the HTTP status of the reply according to
{{:http://www.w3.org/Protocols/rfc2616}RFC 2616}. Defaults to
"no status", but the server normally complements an [`Ok]
status in this case.
@param content_type Sets the content type.
Defaults to ["text/html"].
@param content_length Sets the content length (in bytes).
Default: No such field.
@param set_cookie Deprecated, use [set_cookies].
@param set_cookies Sets a number of cookies. Default: [[]].
Remember that the browser may not support more than 20 cookies
per web server. You can query the cookies using [env#cookies]
and [env#cookie]. If you set cookies, you want to think about
an appropriate [cache] setting. You may also want to add a
{{:http://www.w3.org/P3P/}P3P} header (Platform for Privacy
Preferences) -- otherwise your cookies may be discarded by
some browsers.
@param cache Sets the cache behavior for replies to GET
requests. The default is [`Unspecified]. {b It is strongly
recommended to specify the caching behaviour!!!} You are on
the safe side with [`No_cache], forcing every page to be
regenerated. If your data do not change frequently, [`Max_age
n] tells the caches to store the data at most [n] seconds.
@param filename Sets the filename associated with the page.
This filename is taken for the "save as..." dialog. Default:
[""], i.e. no filename. Note: It is bad practice if the
filename contains problematic characters (backslash, double
quote, space), or the names of directories. It is recommended
that you set [content_type] to "application/octet-stream" for
this feture to work with most browsers and, if possible, to
set [content_length] because that usually improves the
download dialog.)
@param script_type Sets the language of the script tag (for
HTML replies). It is recommended to use this field if there
are [ONXXX] attributes containing scripts before the first
[<SCRIPT>] element, because you cannot specify the script
language for the [ONXXX] attributes otherwise. [script_type]
must be a media type, e.g. "text/javascript". Default: no
language is specified.
@param style_type Sets the language of the style tag (for
HTML replies). It is recommended to use this field if there
are [STYLE] attributes containing scripts before the first
[<STYLE>] element, because you cannot specify the style
language for the [STYLE] attributes otherwise. [style_type]
must be a media type, e.g. "text/css". Default: no language
is specified.
@param fields Sets additional fields of the header. Default: [[]].
*)
method set_redirection_header :
?set_cookies:Cookie.t list ->
?fields:(string * string list) list ->
string -> unit
(** Sets the header such that a redirection to the specified URL
is performed. If the URL begins with "http:" the redirection
directive is passed back to the client, and the client will
repeat the request for the new location (with a GET method).
If the URL begins with "/", the server performs the
redirection, and it is invisible for the client. *)
method output : Netchannels.trans_out_obj_channel
(** @deprecated Use [#out_channel] instead. *)
method out_channel : Netchannels.trans_out_obj_channel
(** The output channel to which the generated content is intended
to be written. The header is not stored in this channel, so
[#pos_out] returns the size of the DATA in bytes (useful to
set Content-Length). Note that HEAD requests must not send
back a message body so, in this case, all data sent to this
channel is discarded. This allows your scripts to work
unmodified for GET, POST and HEAD requests.
The output channel may have transactional semantics, and
because of this, it is an [trans_out_obj_channel].
Implementations are free to support transactions or not.
After all data have been written, the method [#commit_work()]
{b must} be called, even if there is no support for
transactions.
Simple Example:
{[
cgi # out_channel # output_string "Hello world!\n";
cgi # out_channel # commit_work()
]}
Example for an error handler and a transaction buffer: If an
error happens, it is possible to roll the channel back, and to
write the error message.
{[
try
cgi # set_header ... ();
cgi # out_channel # output_string "Hello World!"; ...
cgi # out_channel # commit_work();
with err ->
cgi # out_channel # rollback_work();
cgi # set_header ... ();
cgi # out_channel # output_string "Software error!"; ...
cgi # out_channel # commit_work();
]}
*)
(* later:
method send_mime_message : mime_message -> unit
method begin_multipart_message : XXX -> unit
method end_multipart_message : XXX -> unit
*)
method at_exit : (unit -> unit) -> unit
(** [#at_exit f] registers the function [f] to be executed when
[#finalize] is called (which is done automatically when the
request finishes). The functions are executed in the reverse
order in which they were registered. *)
end
class type cgi_activation = cgi
(** Alternate, more descriptive name for [cgi] *)
(** {2 Connectors} *)
type output_type =
[ `Direct of string
| `Transactional of config ->
Netchannels.out_obj_channel -> Netchannels.trans_out_obj_channel
]
(** The ouput type determines how generated data is buffered.
- [`Direct sep]: Data written to the output channel of the
activation object is not collected in a transaction buffer, but
directly sent to the browser (the normal I/O buffering is still
active, however, so call [#flush] to ensure that data is really
sent). The method [#commit_work] of the output channel is the
same as [#flush]. The method [#rollback_work] causes that the
string [sep] is sent, meant as a separator between the already
generated output, and the now following error message.
- [`Transactional f]: A transactional channel [tc] is created
from the real output channel [ch] by calling [f cfg ch] (here,
[cfg] is the CGI configuration). The channel [tc] is propagated
as the output channel of the activation object. This means that
the methods [commit_work] and [rollback_work] are implemented by
[tc], and the intended behaviour is that data is buffered in a
special transaction buffer until [commit_work] is called. This
invocation forces the buffered data to be sent to the
browser. If, however, [rollback_work] is called, the buffer is
cleared.
Two important examples for [`Transactional] are:
- The transaction buffer is implemented in memory:
{[
let buffered _ ch = new Netchannels.buffered_trans_channel ch in
`Transactional buffered
]}
- The transaction buffer is implemented as an external file:
{[
`Transactional(fun _ ch -> new Netchannels.tempfile_output_channel ch)
]}
*)
val buffered_transactional_outtype : output_type
(** The [output_type] implementing transactions with a RAM-based buffer *)
val buffered_transactional_optype : output_type
(** {b Deprecated} name for [buffered_transactional_outtype] *)
val tempfile_transactional_outtype : output_type
(** The [output_type] implementing transactions with a tempfile-based
buffer
*)
val tempfile_transactional_optype : output_type
(** {b Deprecated} name for [tempfile_transactional_outtype] *)
type arg_store = cgi_environment -> string -> Netmime.mime_header_ro ->
[ `Memory | `File | `Automatic | `Discard
| `Memory_max of float | `File_max of float | `Automatic_max of float]
(** This is the type of functions [arg_store] so that [arg_store env
name header] tells whether to [`Discard] the argument or to
store it into a [`File] or in [`Memory]. The parameters passed
to [arg_store] are as follows:
- [env] is the CGI environment. Thus, for example, you can have
different policies for different [cgi_path_info].
- [name] is the name of the argument.
- [header] is the MIME header of the argument (if any).
Any exception raised by [arg_store] will be treated like if it
returned [`Discard]. Note that the [`File] will be treated
like [`Memory] except for [`POST] "multipart/form-data" and
[`PUT] queries.
[`Automatic] means to store it into a file if the header
contains a file name and otherwise in memory (strictly
speaking [`Automatic] is not necessary since [arg_store] can
check the header but is provided for your convenience).
[`Memory_max] (resp. [`File_max], resp. [`Automatic_max]) is
the same as [`Memory] (resp. [`File], resp. [`Automatic])
except that the parameter indicates the maximum size in kB of
the argument value. If the size is bigger, the
{!Netcgi.cgi_argument} methods [#value] and [#open_value_rd]
methods will raise {!Netcgi.Argument.Oversized}.
Remark: this allows for fine grained size constraints while
{!Netcgi.config}[.input_content_length_limit] option is a
limit on the size of the entire request. *)
type exn_handler = cgi_environment -> (unit -> unit) -> unit
(** A function of type [exn_handler] allows to define a custom
handler of uncaught exceptions raised by the [unit -> unit]
parameter. A typical example of [exn_handler] is as follows:
{[
let exn_handler env f =
try f()
with
| Exn1 -> (* generate error page *)
env#set_output_header_fields [...];
env#send_output_header();
env#out_channel#output_string "...";
env#out_channel#close_out()
| ...
]} *)
type connection_directive =
[ `Conn_close | `Conn_close_linger | `Conn_keep_alive
| `Conn_error of exn
]
(** Directive how to go on with the current connection:
* - [`Conn_close]: Just shut down and close descriptor
* - [`Conn_close_linger]: Linger, shut down, and close descriptor
* - [`Conn_keep_alive]: Check for another request on the same connection
* - [`Conn_error e]: Shut down and close descriptor, and handle the
* exception [e]
*)
(** Specific connectors can be found in separate modules. For example:
- {!Netcgi_cgi}: classical CGI.
- {!Netcgi_fcgi}: FastCGI protocol.
- {!Netcgi_ajp}: AJP 1.3 connector (JSERV protocol).
- {!Netcgi_mod}: connector binding to Apache API.
- {!Netcgi_scgi}: SCGI connector.
- {!Netcgi_test}: special "connector" to test your code.
A typical use is as follows:
{[
open Netcgi
let main (cgi:cgi) =
let arg = cgi#argument_value "name" in
...
cgi#out_channel#commit_work()
let () =
let buffered _ ch = new Netchannels.buffered_trans_channel ch in
Netcgi_cgi.run ~output_type:(`Transactional buffered) main
]}
*)
(*
Local Variables:
mode: outline-minor
outline-regexp: " *\\(val\\|module\\|class\\|type\\) "
End:
*)
