(* netcgi_common.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.
*)
(** Functions to develop new connectors.
*
* The following module is provided as a set of helper functions to
* define new connectors. As a normal user of [Netcgi], {b you should
* not use this module}. *)
(** The goal of this module is to factor out common routines to easily
set up new connectors. Here is the normal flow of operations:
- You start by reading the request environment properties as well
as the input header. Often both are undistinguished and provided
through some sort of meta-variables. The function
{!Netcgi_common.update_props_inheader} helps you to sort them and
to normalize the input header fields. You also need to set up a
{!Netchannels.out_obj_channel} to the output stream of your
connector. Then, {!Netcgi_common.cgi_environment} can create an
environment object for you. If [stderr] output is not appropriate
(e.g. ot is not redirected to the server log), you need to
override [#log_error].
- From the environment object and arguments, {!Netcgi_common.cgi}
creates a CGI object. Often, arguments are read from the
environment [#cgi_query_string] (in case of GET) or from an input
channel (in case of POST). {!Netcgi_common.cgi_with_args} handles
this for you: it requires a {!Netchannels.in_obj_channel} from
which the arguments are read (only used in the case of POST).
- {!Netcgi_common.exn_handler_default} provides a default error
page for uncaught exceptions. It also allows the user to pass his
own exception handler that has precedence on the default one.
To see this schema in use, we recommend you have a look to the
implementation of the CGI connector because it is very simple.
*)
(** {2 Arguments} *)
type representation = [ `Simple of Netmime.mime_body
| `MIME of Netmime.mime_message ]
type store = [`Memory | `File of string]
exception Oversized
(** See {!Netcgi.Argument.Oversized}. *)
(** See {!Netcgi.cgi_argument}. *)
class type cgi_argument =
object
method name : string
method value : string
method open_value_rd : unit -> Netchannels.in_obj_channel
method store : store
method content_type : unit -> string * (string * Mimestring.s_param) list
method charset : string
method filename : string option
method representation : representation
method finalize : unit -> unit
end
(** See {!Netcgi.rw_cgi_argument}.
@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
(** See {!Netcgi.Argument.simple}. We reveal more of the object than
{!Netcgi.Argument.simple} for the backward compatibility layer.
*)
class simple_arg : ?ro:bool -> string -> string -> rw_cgi_argument
(** See {!Netcgi.Argument.mime}. We reveal more of the object than
{!Netcgi.Argument.mime} for the backward compatibility layer. *)
class mime_arg : ?work_around_backslash_bug:bool -> ?name:string ->
Netmime.mime_message -> rw_cgi_argument
(** {2 Cookies} *)
(** Extended interface for {!Netcgi.Cookie} suitable for OCamlNet
developers. *)
module Cookie :
sig
type t
val make :
?max_age:int ->
?domain:string ->
?path:string ->
?secure:bool ->
?comment:string ->
?comment_url:string ->
?ports:int list ->
string -> string -> t
val name : t -> string
val value : t -> string
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 domain : t -> string option
val path : t -> string option
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 ports : t -> int list option
val set_value : t -> string -> unit
val set_max_age : t -> int option -> unit
val set_domain : t -> string option -> unit
val set_path : t -> string option -> unit
val set_secure : t -> bool -> unit
val set_comment : t -> string -> unit
val set_comment_url : t -> string -> unit
val set_ports : t -> int list option -> unit
val set : #Netmime.mime_header -> t list -> unit
(** [set http_header cookies] sets the [cookies] in [http_header]
using version 0 or version 1 depending on whether version 1
fields are used. For better browser compatibility, if
"Set-cookie2" (RFC 2965) is issued, then a "Set-cookie"
precedes (declaring the same cookie with a limited number of
options). *)
val get : #Netmime.mime_header -> t list
(** Decode the cookie header, may they be version 0 or 1. *)
val of_record : Nethttp.cookie -> t
(** Conversion from the deprecated style of cookie. *)
val to_record : t -> Nethttp.cookie
(** Conversion to the deprecated style of cookie (some parameters
are dropped). *)
end
(************************************************************************)
(** {2 Environment} *)
(** See {!Netcgi.config}. *)
type config = {
tmp_directory : string;
tmp_prefix : string;
permitted_http_methods : [`GET | `HEAD | `POST | `DELETE | `PUT] list;
permitted_input_content_types : string list;
input_content_length_limit : int;
workarounds : [ `MSIE_Content_type_bug | `Backslash_bug
| `Work_around_MSIE_Content_type_bug (* @deprecated *)
| `Work_around_backslash_bug (* @deprecated *)
] list;
default_exn_handler : bool;
}
(** See {!Netcgi.output_type}. *)
type output_type =
[ `Direct of string
| `Transactional of config ->
Netchannels.out_obj_channel -> Netchannels.trans_out_obj_channel
]
val fix_MSIE_Content_type_bug : string -> string
(** [fix_MSIE_Content_type_bug ct] transforms the content-type
string [ct] to fix the MSIE Content-Type bug. *)
val is_MSIE : string -> bool
(** [is_MSIE user_agent] tells whether the [user_agent] is Microsoft
Internet Explorer. Useful to know when to apply
{!Netcgi_common.fix_MSIE_Content_type_bug}. *)
(* {b Notes about the header}
The fact that the header is stored in variables of the environment
and not send to the several advantages:
- It is possible to change header fields at every moment before
the commitment happens. For example, it is possible to set the
content-length field which is normally only known just at the
time of the commit operation.
- The [environment] object can process the header; for example
it can fix header fields.
- It is simpler to connect to environments which transport the
header in non-standard ways. Example: Assume that the
environment is the web server process (e.g. we are an Apache
module). Typically the header must be stored in different
structures than the body of the message. *)
(** [new cgi_environment ~config ~properties ~input_header out_obj]
generates a {!Netcgi.cgi_environment} object, from the arguments.
The creation of such an object {i does not} raise any exception.
The method [#out_channel] of the created environment returns
[out_obj].
@param config give the configuration options. Of particular
interest here is [config.workarounds]. If
[`MSIE_Content_type_bug] is present, a fix will be applied to
[input_header].
@param properties CGI-like properties as (name, value) pairs.
Examples: [("REQUEST_METHOD", "POST")], [("SERVER_PROTOCOL",
"HTTP/1.1")]. Note that "CONTENT_TYPE" and "CONTENT_LENGTH" are
part of the input header. It is highly recommended to use
{!Netcgi_common.update_props_inheader} to build this list.
@param input_header is a list of (field, value) pairs of the HTTP
input request. It is ASSUMED that field names in [input_header]
are lowercase in order to apply a fix to the MSIE Content-Type
bug. Also remember that the separator is '-', not '_'. Both
requirements will be stafisfied if you use
{!Netcgi_common.update_props_inheader} to build [input_header].
{b Notes:} The header is kept into variables and
[#send_output_header] sents it directly to [out_obj]. This has
several advantages:
- It is possible to change header fields at every moment before
the commitment happens. For example, it is possible to set the
content-length field which is normally only known just at the
time of the commit operation.
- The [environment] object can process the header; for example
it can fix header fields.
- It is simpler to connect to environments which transport the
header in non-standard ways. Example: Assume that the
environment is the web server process (e.g. we are an Apache
module). Typically the header must be stored in different
structures than the body of the message.
*)
class cgi_environment :
config:config ->
properties:(string * string) list ->
input_header:(string * string) list ->
Netchannels.out_obj_channel ->
