# Module Netcgi_types

    module Netcgi_types: sig .. end

Basic types for CGI and related protocols

    exception Resources_exceeded

Raised when the CGI input is longer than the configured maximum

    class type simple_message = Netmime.mime_body

A `simple_message` stores the value of the CGI argument as an unstructured string value.

    type store = [ `File of string | `Memory ]

Determines where the data of the CGI argument are actually stored.

- ``Memory`: In an O'Caml string
- ``File name`: In the file `name`. The file contains the value of the argument after all transfer-related encodings have been removed (i.e. URL-encoding, and MIME transfer encodings).

    type representation = [ `MIME of Netmime.mime_message | `Simple of simple_message ]

Representations of CGI arguments:

- ``Simple msg`: The argument is unstructured
- ``MIME msg`: The argument has a MIME header in addition to the value

    class type cgi_argument = object .. end

The interface of CGI argument objects
`type ``cgi_cookie = {`

`` | `cookie_name : `string`;` | `(*` | `The name of the cookie` | `*)`
`` | `cookie_value : `string`;` | `(*` | `The value of the cookie. There are no restrictions on the value of the cookie` | `*)`

``

`cookie_expires : `float option`;`

`(*`

`Expiration:

- `None`: the cookie expires when the browser session ends.
- `Some t`: the cookie expires at the time `t` (seconds since the epoch)

`

`*)`

``

`cookie_domain : `string option`;`

`(*`

`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`

`

`*)`

``

`cookie_path : `string option`;`

`(*`

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

`

`*)`

`` | `cookie_secure : `bool`;` | `(*` | `Cookies are also bound to the type of the web server: `false` means servers without SSL, `true` means servers with activated SSL ("https").` | `*)`

}

    type status = [ `Accepted
           | `Bad_gateway
           | `Bad_request
           | `Conflict
           | `Created
           | `Expectation_failed
           | `Forbidden
           | `Found
           | `Gateway_timeout
           | `Gone
           | `Http_version_not_supported
           | `Internal_server_error
           | `Length_required
           | `Method_not_allowed
           | `Moved_permanently
           | `Multiple_choices
           | `No_content
           | `Non_authoritative
           | `Not_acceptable
           | `Not_found
           | `Not_implemented
           | `Not_modified
           | `Ok
           | `Partial_content
           | `Payment_required
           | `Precondition_failed
           | `Proxy_auth_required
           | `Request_entity_too_large
           | `Request_timeout
           | `Request_uri_too_long
           | `Requested_range_not_satisfiable
           | `Reset_content
           | `See_other
           | `Service_unavailable
           | `Temporary_redirect
           | `Unauthorized
           | `Unsupported_media_type
           | `Use_proxy ]

HTTP response status:

Successful (2xx):

- ``Ok`
- ``Created`
- ``Accepted`
- ``Non_authoritative`
- ``No_content`
- ``Reset_content`
- ``Partial_content`

Redirection (3xx):

- ``Multiple_choices`
- ``Moved_permanently`
- ``Found`
- ``See_other`
- ``Not_modified`
- ``Use_proxy`
- ``Temporary_redirect`

Client error (4xx):

- ``Bad_request`
- ``Unauthorized`
- ``Payment_required`
- ``Forbidden`
- ``Not_found`
- ``Method_not_allowed`
- ``Not_acceptable`
- ``Proxy_auth_required`
- ``Request_timeout`
- ``Conflict`
- ``Gone`
- ``Length_required`
- ``Precondition_failed`
- ``Request_entity_too_large`
- ``Request_uri_too_long`
- ``Unsupported_media_type`
- ``Request_range_not_satisfiable`
- ``Expectation_failed`

Server Error (5xx):

- ``Internal_server_error`
- ``Not_implemented`
- ``Bad_gateway`
- ``Service_unavailable`
- ``Gateway_timeout`
- ``Http_version_not_supported`

    type request_method = [ `DELETE | `GET | `HEAD | `POST | `PUT of cgi_argument ]

The supported request methods:

- ``GET`: Side effect-free request of a web resource
- ``POST`: Request with side effects
- ``HEAD`: Only the header of the corresponding ``GET` are requested
- ``DELETE`: Request to delete the web resource
- ``PUT arg`: Request to upload the web resource

    type cache_control = [ `Max_age of int | `No_cache | `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)
- ``Max_age n`: Caches are allowed to store a copy of the response for `n` seconds. After that, the response must be revalidated. `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.

    type query_string_spec = [ `Args of cgi_argument list | `Current | `Initial | `None ]

Determines how the query part of URLs is generated:

- ``Initial`: The query string is created from the initial CGI arguments
- ``Current`: The query string is created from the current CGI arguments
- ``Args l`: The query string is created from the specified argument list
- ``None`: The query string is omitted

    type other_url_spec = [ `Env | `None | `This of string ]

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

    class type cgi_activation = object .. end

The common interface of CGI activation objects