NAME

       mod_esi - Erlang Server Interface

DESCRIPTION

       This  module  defines the Erlang Server Interface (ESI) API. It is a more efficient way of writing Erlang
       scripts for your Inets web server than writing them as common CGI scripts.

DATA TYPES

       The following data types are used in the functions for mod_esi:

         env() = :
           {EnvKey()::atom(), Value::term()}

           Currently supported key value pairs

           {server_software, string()}:
             Indicates the inets version.

           {server_name, string()}:
             The local hostname.

           {gateway_interface, string()}:
             Legacy string used in CGI, just ignore.

           {server_protocol, string()}:
             HTTP version, currently "HTTP/1.1"

           {server_port, integer()}:
             Servers port number.

           {request_method, "GET | "PUT" | "DELETE" | "POST" | "PATCH"}:
             HTTP request method.

           {remote_adress, inet:ip_address()} :
             The clients ip address.

           {peer_cert, undefined | no_peercert | DER:binary()}:
             For TLS connections  where  client  certificates  are  used  this  will  be  an  ASN.1  DER-encoded
             X509-certificate  as  an  Erlang  binary.  If  client  certificates  are not used the value will be
             no_peercert, and if TLS is not used (HTTP or connection is lost due to network failure)  the  value
             will be undefined.

           {script_name, string()}:
             Request URI

           {http_LowerCaseHTTPHeaderName, string()}:
             example: {http_content_type, "text/html"}

EXPORTS

       deliver(SessionID, Data) -> ok | {error, Reason}

              Types:

                 SessionID = term()
                 Data = string() | io_list() | binary()
                 Reason = term()

              This  function  is  only  intended to be used from functions called by the Erl Scheme interface to
              deliver parts of the content to the user.

              Sends data from an Erl Scheme script back to the client.

          Note:
              If any HTTP header fields are added by the script, they must be in the first  call  to  deliver/2,
              and the data in the call must be a string. Calls after the headers are complete can contain binary
              data  to  reduce  copying  overhead.  Do  not  assume  anything  about the data type of SessionID.
              SessionID must be the value given as input to the ESI callback function that you implemented.

ESI CALLBACK FUNCTIONS

EXPORTS

       Module:Function(SessionID, Env, Input)-> {continue, State} | _

              Types:

                 SessionID = term()
                 Env = env()
                 Input = string() | chunked_data()
                 chunked_data() = {first, Data::binary()} | {continue, Data::binary(), State::term()}  |  {last,
                 Data::binary(), State::term()}
                 State = term()

              Module  must  be  found  in  the  code  path  and  export  Function  with  an  arity  of three. An
              erlScriptAlias must also be set up in the configuration file for the web server.

              mod_esi:deliver/2 shall be used to generate the  response  to  the  client  and  SessionID  is  an
              identifier  that  shall  by  used  when  calling  this  function, do not assume anything about the
              datatype. This function may be called several times to chunk the response data.  Notice  that  the
              first  chunk  of  data  sent  to  the client must at least contain all HTTP header fields that the
              response will generate. If the first chunk does not contain the  end  of  HTTP  header,  that  is,
              "\r\n\r\n", the server assumes that no HTTP header fields will be generated.

              Env environment data of the request see description above.

              Input  is  query  data of a GET request or the body of a PUT or POST request. The default behavior
              (legacy reasons) for delivering the body, is that the whole body is gathered and  converted  to  a
              string. But if the httpd config parameter max_client_body_chunk is set, the body will be delivered
              as binary chunks instead. The maximum size of the chunks is either max_client_body_chunk or decide
              by the client if it uses HTTP chunked encoding to send the body. When using the chunking mechanism
              this  callback  must  return  {continue,  State::term()}  for  all  calls  where  Input is {first,
              Data::binary()} or {continue, Data::binary(), State::term()}. When Input is {last, Data::binary(),
              State::term()} the return value will be ignored.

          Note:
              Note that if the body is small all data may be delivered in only one chunk and then  the  callback
              will  be  called  with  {last,  Data::binary(),  undefined}  without  getting  called with {first,
              Data::binary()}.

              The input State is the last returned State, in it the callback can include any data that it  needs
              to keep track of when handling the chunks.

Ericsson AB                                       inets 8.3.1.2                                    mod_esi(3erl)