# Module Netcgi_env

    module Netcgi_env: sig .. end

Access to the environment for CGI and related protocols

    type input_mode = [ `Standard ]

Determines how to read the request:

- ``Standard`: Only the request body is read from the input channel (CGI standard)
- Not yet implemented: ``Direct`: Both header and body of the request are read from the input channel

    type input_state = [ `Received_body
           | `Received_header
           | `Receiving_body
           | `Receiving_header
           | `Start ]

The input processing state:

- ``Start`: Input data have not yet been received
- ``Receiving_header`: The request header is currently being received
- ``Received_header`: The request header has been completely received, and nothing of the request body has yet been received
- ``Receiving_body`: The request body is currently being received
- ``Received_body`: The request body has been completely received

Transition diagram:

     `Start ->
     `Receiving_header ->
     `Received_header ->
     `Receiving_body ->
     `Received_body

    type output_mode = [ `Standard ]

Determines how to deliver the response:

- ``Standard`: The format of the response header has CGI format, followed by the response body
- Not yet implemented: ``Direct`: The format of the response header has HTTP format, followed by the response body. This is also known as "non-parsed header" format.

    type output_state = [ `End
           | `Sending_body
           | `Sending_header
           | `Sending_part_body
           | `Sending_part_header
           | `Sent_body
           | `Sent_header
           | `Sent_part_body
           | `Sent_part_header
           | `Start ]

The output processing state:

- ``Start`: Output has not yet been sent
- ``Sending_header`: The response header is currently being sent
- ``Sent_header`: The response header has been completely sent, and nothing of the body has yet been sent
- ``Sending_body`: The response body is currently being sent
- ``Sent_body`: The response body has been sent up to a check point
- ``End`: The response has been completely sent

Transition diagram:

                  `Start ->
                  `Sending_header ->
                  `Sent_header ->
              +-> `Sending_body
              |      |
              |      V
              +-- `Sent_body
                     |
                     V
                  `End

The state ``Sent_body` is reached when the output data are committed. It is possible to continue with another transaction, which would mean to go back to ``Sending_body`, or to finish the body completely, by going to ``End`.

Extension for multi-part response messages (e.g. needed for server push, not yet implemented):

- ``Sending_part_header`: The header of a message part is being sent
- ``Sent_part_header`: The header of a message part has been completely sent
- ``Sending_part_body`: The body of a message part is being sent
- ``Sent_part_body`: The body of a message part has been sent up to a check point

    type protocol_version = int * int

A pair of a major and minor version number

    type protocol_attribute = [ `Secure_https ]

    type protocol = [ `Http of protocol_version * protocol_attribute list
           | `Other ]

The base protocol

    type workaround = [ `Work_around_MSIE_Content_type_bug | `Work_around_backslash_bug ]

Indicates special behaviour:

- ``Work_around_MSIE_Content_type_bug`: Versions of the Internet Explorer send illegal content types. This workaround extracts the right data from the malformed data field
- ``Work_around_backslash_bug`: Almost all browsers send illegal backslash sequences when backslashes occur in filenames. This workaround accepts such sequences.

`type ``cgi_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 : `string list`;` | `(*` | `The list of accepted HTTP methods (uppercase letters)` | `*)`
`` | `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` | `*)`
`` | `workarounds : `workaround list`;` | `(*` | `The list of enabled workarounds` | `*)`

}

    val default_config : cgi_config

The default configuration is:

- `tmp_directory`: one of /var/tmp, /tmp, C:\temp, .
- `tmp_prefix`: "netstring"
- `permitted_http_methods`: `"GET"`, `"POST"`
- `permitted_input_content_types`: `"multipart/form-data"`, `"application/x-www-form-urlencoded"`
- `input_content_length_limit`: `maxint`
- `workarounds`: all

To create a custom configuration, it is suggested to use this syntax:

     let custom_config =
        { default_config with tmp_prefix = "my_prefix" }

    class type cgi_environment = object .. end

The class type cgi_environment contains the resources by which the CGI activation is connected to the "outer world".

    exception Std_environment_not_found

Indicates that the process environment does not contain the variables that are typical of CGI

    class std_environment : ?config:cgi_config -> unit -> cgi_environment

An implementation of `cgi_environment`, intended to be used for classical CGI.

    class test_environment : ?config:cgi_config -> unit -> cgi_environment

An implementation of `cgi_environment`, intended to test CGI programs from the command-line.

    class custom_environment : ?config:cgi_config -> unit -> object .. end

This class can be used to set up non-standard environments.