Module Netcgi

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.)

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.

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: deprecated, use `This (left for backward compatibility).

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.

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)
        

The output_type implementing transactions with a RAM-based buffer

Deprecated name for buffered_transactional_outtype

The output_type implementing transactions with a tempfile-based buffer

Deprecated name for tempfile_transactional_outtype

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.

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()
        | ...
      

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