1mod_esi(3)                 Erlang Module Definition                 mod_esi(3)
2
3
4

NAME

6       mod_esi - Erlang Server Interface
7

DESCRIPTION

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

DATA TYPES

14       The following data types are used in the functions for mod_esi:
15
16         env() = :
17           {EnvKey()::atom(), Value::term()}
18
19           Currently supported key value pairs
20
21           {server_software, string()}:
22             Indicates the inets version.
23
24           {server_name, string()}:
25             The local hostname.
26
27           {gateway_interface, string()}:
28             Legacy string used in CGI, just ignore.
29
30           {server_protocol, string()}:
31             HTTP version, currently "HTTP/1.1"
32
33           {server_port, integer()}:
34             Servers port number.
35
36           {request_method, "GET | "PUT" | "DELETE" | "POST" | "PATCH"}:
37             HTTP request method.
38
39           {remote_adress, inet:ip_address()} :
40             The clients ip address.
41
42           {peer_cert, undefined | no_peercert | DER:binary()}:
43             For  TLS connections where client certificates are used this will
44             be an ASN.1 DER-encoded X509-certificate as an Erlang binary.  If
45             client  certificates  are not used the value will be no_peercert,
46             and if TLS is not used (HTTP or connection is lost due to network
47             failure) the value will be undefined.
48
49           {script_name, string()}:
50             Request URI
51
52           {http_LowerCaseHTTPHeaderName, string()}:
53             example: {http_content_type, "text/html"}
54

EXPORTS

56       deliver(SessionID, Data) -> ok | {error, Reason}
57
58              Types:
59
60                 SessionID = term()
61                 Data = string() | io_list() | binary()
62                 Reason = term()
63
64              This  function is only intended to be used from functions called
65              by the Erl Scheme interface to deliver parts of the  content  to
66              the user.
67
68              Sends data from an Erl Scheme script back to the client.
69
70          Note:
71              If  any HTTP header fields are added by the script, they must be
72              in the first call to deliver/2, and the data in the call must be
73              a  string.  Calls after the headers are complete can contain bi‐
74              nary data to reduce copying overhead.  Do  not  assume  anything
75              about  the  data  type of SessionID. SessionID must be the value
76              given as input to the ESI  callback  function  that  you  imple‐
77              mented.
78
79

ESI CALLBACK FUNCTIONS

EXPORTS

82       Module:Function(SessionID, Env, Input)-> {continue, State} | _
83
84              Types:
85
86                 SessionID = term()
87                 Env = env()
88                 Input = string() | chunked_data()
89                 chunked_data()   =   {first,   Data::binary()}  |  {continue,
90                 Data::binary(),  State::term()}  |   {last,   Data::binary(),
91                 State::term()}
92                 State = term()
93
94              Module  must  be found in the code path and export Function with
95              an arity of three. An erlScriptAlias must also be set up in  the
96              configuration file for the web server.
97
98              mod_esi:deliver/2  shall be used to generate the response to the
99              client and SessionID is an identifier that shall  by  used  when
100              calling   this  function,  do  not  assume  anything  about  the
101              datatype. This function may be called several times to chunk the
102              response  data.  Notice that the first chunk of data sent to the
103              client must at least contain all HTTP header fields that the re‐
104              sponse  will  generate.  If the first chunk does not contain the
105              end of HTTP header, that is, "\r\n\r\n", the server assumes that
106              no HTTP header fields will be generated.
107
108              Env environment data of the request see description above.
109
110              Input  is  query  data  of a GET request or the body of a PUT or
111              POST request. The default behavior (legacy reasons) for deliver‐
112              ing  the  body, is that the whole body is gathered and converted
113              to   a   string.   But   if   the   httpd    config    parameter
114              max_client_body_chunk  is set, the body will be delivered as bi‐
115              nary chunks instead. The maximum size of the  chunks  is  either
116              max_client_body_chunk  or  decide  by the client if it uses HTTP
117              chunked encoding to send the body. When using the chunking mech‐
118              anism  this  callback  must return {continue, State::term()} for
119              all calls where Input is {first, Data::binary()}  or  {continue,
120              Data::binary(),  State::term()}.  When Input is {last, Data::bi‐
121              nary(), State::term()} the return value will be ignored.
122
123          Note:
124              Note that if the body is small all data may be delivered in only
125              one  chunk  and  then  the  callback  will be called with {last,
126              Data::binary(), undefined} without getting called  with  {first,
127              Data::binary()}.
128
129
130              The  input  State is the last returned State, in it the callback
131              can include any data that it needs to keep track  of  when  han‐
132              dling the chunks.
133
134
135
136Ericsson AB                      inets 8.3.1.2                      mod_esi(3)