Module Webs_cgi
CGI gateway connector.
This connector serves one request via CGI.
Important. Reconstructing the raw request target from CGI's PATH_INFO
and QUERY_STRING
is not really possible and PATH_INFO
s can easily get confused by requests like "/s1/s2%2Fha/s3"
. To side step this issue this connector relies on the non-standard REQUEST_URI
variable in which the raw url-encoded request target should be passed. nginx
passes that by default with the value of $request_uri
, unfortunately it doesn't seem to be able to chop a prefix from that variable without getting url-decoded results. You can add the REQUEST_TARGET_PREFIX
in the environment whose value will be chopped from REQUEST_URI
.
See the Web service howto manual for instructions.
References.
- D. Robinson et al. The Common Gateway Interface (CGI) Version 1.1. 2004.
Connector
type t
The type for CGI connectors. Serves one request by reading headers from the environment and the body from
Unix
.stdin.
val create : ?log:(Webs.Connector.log_msg -> unit) -> ?max_req_body_byte_size:int -> ?extra_vars:string list -> unit -> t
create ()
is a new CGI connector with parameters:extra_vars
is a list of environment variables whose content is added to the request headers (defaults to[]
). The header name of a variable is made by lowercasing it, mapping'_'
to'-'
and prefixing the result withx-cgi
. For exampleSERVER_SOFTWARE
becomesx-cgi-server-software
.max_req_body_byte_size
is the maximal request body size in bytes. FIXME not enforced, unclear where this is to put the limit on, for streaming bodies, if we cut the line the service might end up being confused (but then it should also cater for that possibility).log
logs connector log messages. It defaultsWebs.Connector.default_log
with trace message disabled.
val serve : t -> Webs.service -> (unit, string) Stdlib.result
serve c s
runs services
with connectorc
. This blocks until the response ofs
for the request has been served. The error is returned in case of connector error, it's a good practice to write the message on stderr and exit with a non-zero exit code if that happend.
Request derivation
The Webs.Req.t
value is constructed from the environment and Unix
.stdin as follows:
Webs.Req.version
is the value of theSERVER_PROTOCOL
variable.Webs.Req.meth
is the value of theREQUEST_METHOD
variable.Webs.Req.request_target
is the value of the (non standard)REQUEST_URI
variable, chopped from the value in theREQUEST_TARGET_PREFIX
variable (if present).Webs.Req.headers
has the following headers defined:Webs.Http.H.content_type
if the variableCONTENT_TYPE
is defined and non empty.Webs.Http.H.content_length
if the variableCONTENT_LENGTH
is defined and non empty.- For any other variable of the form
HTTP_$VAR
there is a corresponding$var
header whose name is made by lowercasing$VAR
and mapping'_'
to'-'
. For exampleHTTP_USER_AGENT
becomesWebs.Http.H.user_agent
. If defined the variablesHTTP_CONTENT_TYPE
andHTTP_CONTENT_LENGTH
are overriden by the previous two definitions. - For any other
$VAR
inextra_vars
given when the connector iscreate
d, a header is added with the value of the variable. The header name of a variable is made by lowercasing it, mapping'_'
to'-'
and prefixing the result withx-cgi
. For exampleSERVER_SOFTWARE
becomesx-cgi-server-software
.
Webs.Req.body_length
is determined from the headers according toWebs.Http.H.request_body_length
.- Request bodies, is the result of reading
Unix
.stdin
If the request derivation fails in some way an 500 is returned and an error should be printed on standard error.