mod_esi

MODULE

mod_esi

MODULE SUMMARY

Efficient Erlang Scripting.

DESCRIPTION

The Erlang Scripting Interface (ESI) provides a tight and efficient interface to the execution of Erlang functions. Erlang functions can be executed with two alternative schemes, eval and erl. Both of these schemes can utilize the functionality in an Erlang node efficiently.

Even though the server supports CGI-1.1 the use of the Erlang Scripting Interface (ESI) is encouraged for reasons of efficiency. CGI is resource intensive because of its design. CGI requires the server to fork a new OS process for each executable it needs to start.

An Erlang function can be written and executed as a CGI script by using erl_call(3) in the erl_interface library, for example. The cost is a forked OS process, as described above. This is a waste of resources, at least when the Web server itself is written in Erlang (as in this case).

The following config directives are described:

• ErlScripAlias
• EvalScriptAlias

ERL SCHEME

The erl scheme is designed to mimic plain CGI, but without the extra overhead. An URL which calls an Erlang erl function has the following syntax (regular expression):

http://your.server.org/***/Mod[:/]Func(?QueryString|/PathInfo)
    

The module (Mod) referred to must be found in the code path, and it must define a function (Func) with an arity of two, i.e. Func(Env,Input). Env contains information about the connecting client (see below), and Input the QueryString or PathInfo as defined in the CGI specification. *** above depends on how the ErlScriptAlias config directive has been used. Data returned from the function must furthermore take the form as specified in the CGI specification.

Take a look at httpd_example.erl in the code release (UNIX: $INETS/src, Windows: %INETS\src) for a clarifying example. Start an example server as described in httpd:start/0 and test the following from a browser (The server name for your example server will differ!):

http://your.server.org:8888/cgi-bin/erl/httpd_example/get

and a call will be made to httpd_example:get/2 and two input fields and a Submit button will promptly be shown in the browser. Enter text into the input fields and click on the Submit button. Something like this will promptly be shown in the browser:


Environment: [{query_string,"input1=blaha&input2=blaha"},
              {server_software,"eddie/2.2"},
              {server_name,"localhost"},
              {gateway_interface,"CGI/1.1"},
              {server_protocol,"HTTP/1.0"},
              {server_port,8080},
              {request_method,"GET"},
              {remote_addr,"127.0.0.1"},
              {script_name,"/cgi-bin/erl/httpd_example:get?input1=blaha&input2=blaha"},
              {http_accept_charset,"iso-8859-1,*,utf-8"},
              {http_accept_language,"en"},
              {http_accept,"image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*"},
              {http_host,"localhost:8080"},
              {http_user_agent,"Mozilla/4.03 [en] (X11; I; Linux 2.0.30 i586)"},
              {http_connection,"Keep-Alive"}, {http_referer,"http://localhost:8080/cgi-bin/erl/httpd_example/get"}]
Input: input1=blaha&input2=blaha
Parsed Input: [{"input1","blaha"},{"input2","blaha"}] 
        

http://your.server.org:8888/cgi-bin/erl/httpd_example:post

A call will be made to httpd_example:post/2. The same thing will happen as in the example above but the HTTP POST method will be used instead of the HTTP GET method.


http://your.server.org:8888/cgi-bin/erl/httpd_example:yahoo

A call will be made to to httpd_example:yahoo/2 and the Yahoo! site will promptly be shown in your browser.


httpd:parse_query/1 is used to generate the Parsed Input: ... data in the example above. If a client closes the connection prematurely a message will be sent to the function, that is either {tcp_closed,_} or {_,{socket_closed,_}}.

EVAL SCHEME

The eval scheme can seriously threaten the integrity of the Erlang node housing a Web server, for example: http://your.server.org/eval?httpd_example:print(atom_to_list(apply(erlang,halt,[]))) which effectively will close down the Erlang node, that is use the erl scheme instead until this security breach has been fixed.

The eval scheme is straight-forward and does not mimic the behavior of plain CGI. An URL which calls an Erlang eval function has the following syntax:

http://your.server.org/***/Mod:Func(Arg1,...,ArgN)
    

The module (Mod) referred to must be found in the code path, and data returned by the function (Func) is passed back to the client. *** depends on how the EvalScriptAlias config directive has been used. Data returned from the function must furthermore take the form as specified in the CGI specification.

Take a look at httpd_example.erl in the code release (UNIX: $INETS/src, Windows: %INETS\src) for an example. Start an example server as described in httpd:start/0 and test the following from a browser (The server name for your example server will differ!):

http://your.server.org:8888/eval?httpd_example:print("Hi!")

and a call will be made to httpd_example:print/1 and "Hi!" will promptly be shown in your browser.

DIRECTIVE: "ErlScriptAlias"

Syntax: ErlScriptAlias url-path allowed-module allowed-module ...
Default: - None -
Module: mod_esi(3)

ErlScriptAlias marks all URLs matching url-path as erl scheme scripts. A matching URL is mapped into a specific module and function. The module must be one of the allowed-module:s. For example:

ErlScriptAlias /cgi-bin/hit_me httpd_example md4
    

and a request to http://your.server.org/cgi-bin/hit_me/httpd_example:yahoo would refer to httpd_example:yahoo/2. Refer to the Erl Scheme description above.

DIRECTIVE: "EvalScriptAlias"

Syntax: EvalScriptAlias url-path allowed-module allowed-module ...
Default: - None -
Module: mod_esi(3)

EvalScriptAlias marks all URLs matching url-path as eval scheme scripts. A matching URL is mapped into a specific module and function. The module must be one of the allowed-module:s. For example:

EvalScriptAlias /cgi-bin/hit_me_to httpd_example md5
    

and a request to http://your.server.org/cgi-bin/hit_me_to/httpd_example:print("Hi!") would refer to httpd_example:print/1. Refer to the Eval Scheme description above.

EWSAPI MODULE INTERACTION

Uses the following EWSAPI interaction data, if available:

{remote_user,RemoteUser}

as defined in mod_auth(3) and mod_auth_mnesia(3)

Exports the following EWSAPI interaction data, if possible:

{mime_type,MimeType}

The file suffix of the incoming URL mapped into a MimeType as defined in the Mime Type Settings section of httpd_core(3).

Uses the following EWSAPI functions:

• mod_alias:real_name/3
• mod_cgi:status_code/1

SEE ALSO

httpd(3), mod_alias(3), mod_auth(3), mod_auth_mnesia(3), mod_cgi(3)

AUTHORS

Joakim Grebenö - jocke@erix.ericsson.se