OpenFlax Configuration File Format 1.0 Draft

Please note that this document is a draft. Until such time as it becomes 'final', the configuration file format is subject to change wildly. After such time as it becomes 'final', OpenFlax is obliged to provide a compatibility layer for configuration file format 1.0.

Configuration Files

OpenFlax configuration files are files in file:consult/1 format. The names of these files are given when starting OpenFlax. At least one configuration file is required. More than one may be specified, in which case, settings in files specified later on the command line will override settings in files specified earlier on the command line (with a few exceptions; these are described in detail below.)

Each configuration file consists of several terms, each of which is called a section.

Sections

Each section is a pair (2-tuple) of an atom, giving the section name, and a list of settings for that section. It has the following form:

{section_name(), [setting(), setting(), ... ]}.

Each configuration file must consist of the following sections:

one global section, named openflax, which contains settings applicable the entire webserver;
one or more host sections, each named after the host name it applies to (e.g. www.w3c.org), which contain settings specific to each host (which may override global settings;) and
zero or more handler sections, each named after the handler it applies to (e.g. openflax.mod.ls), which contain settings specific to each handler (which may override global and host settings.)

(Settings may be further overridden by dispatch rules and by handler execution itself; these are described in detail below.)

Each host section indicates a virtual host that this web server will serve. The presence of a host section in a configure file declares that the web server will serve resources for that host. The host section also provides a place to put settings which only apply to a particular host.

Each handler section indicates a handler that will be incorporated into the operation of this web server. The presence of a handler section indicated that the specified handler should be loaded at startup, and that its functionality should be made available to the rest of the web server. If a handler does not have a section in the configuration file, it will not be used, even when other components of the web server (such as dispatch rules or other handlers) refer to it.

Settings

Each setting is a pair of an atom, giving the setting's key, and any valid Erlang term, giving its value. It has the following form:

{key(), value()}.

By convention, each key consists solely of lowercase letters and underscores. Each key is structured with a three-or-four letter class identifier, followed by an underscore and the remainder of the key. The class identifiers currently used by OpenFlax are:

cfg_*

Configuration settings. These settings determine the basic behaviour of the web server. By convention, the next set of letters after the underscore indicate which handler the setting most applies to. For example, a setting used to configure the openflax.mod.ls handler would have a key like cfg_ls_filter, while a setting which applies to the web server itself would have a key like cfg_openflax_port.

arg_*

GET query arguments. For example, a request to the URI /baz?foo=bar would introduce the setting {arg_foo, "bar"}. These are typically not specified directly in a configuration file, but may be to provide default arguments.

form_*

POST query arguments. Analogous to arg_*, except these relate to arguments given by a fill-out form with a method of POST.

req_*

Request headers. All incoming HTTP headers are translated to lowercase atoms with hyphens replaced by underscore, so that e.g. Content-Type becomes req_content_type. In this manner, they can be used to direct the response given by the web server. These settings are typically not specified directly in a configuration file.

sreq_*

Session request headers. These are like req_* variables except they are not header fields sent by the client, but instead derived by OpenFlax. They exist in a seperate namespace so that there are no future conflicts.

res_*

Response headers. All res_* settings are translated directly to mixed-case outgoing HTTP headers, with hyphens instead of underscores, so that e.g. res_content_type becomes Content-Type in the response headers.

sres_*

Session response headers. These are to res_* settings what sreq_* settings are to req_* settings. They are used to generate HTTP response headers, while not actually naming any actual headers.

tpl_*

Template settings. These are used specifically in the generation of templates.

Each value may be any Erlang term. The most common type of value is a string; these are given in a configuration file between double quotes, and any double quote or backslash inside the string must be preceded ("escaped") by a backslash.

Cumulative Settings

As mentioned, settings can be overridden by other settings in numerous ways. Most settings completely override previous settings. However, some settings are said to be cumulative. These settings do not wholly override previous settings; instead, they add to them. The value of a cumulative setting must be a list.

OpenFlax currently supports two cumulative settings; cfg_openflax_dispatch and cfg_openflax_watchers. While the latter will never appear in a configuration file (it is a list of process identifiers, which cannot be known before OpenFlax starts,) the former almost always will.

The `cfg_openflax_dispatch` Setting

cfg_openflax_dispatch is the most important setting, as it contains dispatch rules which determine how each request from the user agent will be handled.

The cfg_openflax_dispatch setting is cumulative. The dispatch rules which apply to the entire web server generically may be given in the openflax section. Dispatch rules specified in host sections will then add to them, allowing each host to have its own special way of responding to requests.

The cfg_openflax_dispatch setting has the following form:

{cfg_openflax_dispatch, [dispatch_rule()]}

and a dispatch_rule() is

{pattern(), pattern(), response()} or
{pattern(), pattern(), response(), [setting()]} or
{pattern(), pattern(), response(), [setting()], [ip()]}

The first dispatch rule where both pattern()s match and where the user agent's IP address is found in the list of ip()s (if any) is selected; when this happens, the additional setting()s are incorporated and override any existing settings, and the given response() is returned to the user agent.

Each of the pattern()s is a string in the form of a sh-style wildcard, for example "*.html". The first pattern is compared to the basic request (the URI without arguments,) and the second pattern is compared to the basic arguments (the arguments, that is everything after the ? if present, without the rest of the URI.)

The meaning of a response() is given in detail in the API documentation. In general, as it appears in a configuration file, it can be:

an error, such as not_found;
a directive, such as {moved_permanently, "http://new.url/"};
the name of a handler, such as openflax.mod.ls;
or direct content in the form {content, "Hi"}.



(Note that it cannot be a stream_* response, as it is
impossible to specify process identifiers in a configuration file.)

The list of setting()s is merged into the available settings
when this dispatch rule is matched.  This is useful in conjunction with direct
content, as it allows you to specify a Content-Type for the content by
giving a setting local to the dispatch rule such as {res_content_type,
"text/html"}.

The list of ip()s indicates which IP addresses are authorized
to invoke this dispatch rule - requests from all other IP addresses will
never be able to match it.  This will result in a not_found
response if there are no other dispatch rules which apply.  The format of
an ip() is a string like "127.0.0.1".  If no
list of ip()s is given, all IP addresses are allowed access.

Other cfg_openflax_* Settings


cfg_openflax_port integer() 
Specifies the TCP/IP port number that the webserver is to listen on.


cfg_openflax_max_conn integer() 
Specifies the maximum number of simultaneous TCP/IP connections that
are allowed at any given time.


cfg_openflax_log_file filename() 
Specifies the file (if any) to which the log will be written.


cfg_openflax_version string() 
The version of this instance of OpenFlax.


cfg_openflax_http_body_parser module_name() 
A module to call to parse an HTTP request body of a non-trivial type.
The module should export a function parse_body/2 which
parses the body and returns either {ok, conf()} or
{error, Reason}.  If this setting is omitted, advanced body
parsing is not attempted.


cfg_openflax_error_handler module_name() 
The handler to call to generate an error.
The module should export a function serve/1 which
should behave like the handler function of the same name.
If this setting is omitted, internal response generation will provide
a very basic error response page.


cfg_openflax_error_mode boolean() 
Internal (you should not specify this directly in a configuration file.)  Set to
true once an error has occurred.  This is to stop an error handler
which contains an error from going into an infinite loop.


cfg_openflax_watchers [pid()] 
Cumulative.  Internal (you cannot specify this directly in a configuration
file.)  A list of processes which are notified each time a request is dealt
with.  This setting is typically set up by the start/1 callback
of a handler.


cfg_openflax_dispatch [dispatch_rule()] 
Cumulative.  Described above.






sres_* Settings


sres_non_cacheable boolean() 
If true, declares the current response being generated to
be "non cacheable" - the user agent will be instructed not to cache it.
While this is largely internal, it can be placed in a configuration file
to indicate that some (or all) content is not to be cached.


sres_keep_alive boolean() 
If true, declares that persistent connections are to be
preferred - the user agent will be instructed to "stay on the line".
Note that this behaviour is currently experimental.


sres_response_code string() 
Internal (you should not set this yourself; instead you should let
response()s such as not_found handle it for you.)
The response code, such as "404 Not Found", sent to the user agent.

`cfg_openflax_port`	`integer()`	Specifies the TCP/IP port number that the webserver is to listen on.
`cfg_openflax_max_conn`	`integer()`	Specifies the maximum number of simultaneous TCP/IP connections that are allowed at any given time.
`cfg_openflax_log_file`	`filename()`	Specifies the file (if any) to which the log will be written.
`cfg_openflax_version`	`string()`	The version of this instance of OpenFlax.
`cfg_openflax_http_body_parser`	`module_name()`	A module to call to parse an HTTP request body of a non-trivial type. The module should export a function `parse_body/2` which parses the body and returns either `{ok, conf()}` or `{error, Reason}`. If this setting is omitted, advanced body parsing is not attempted.
`cfg_openflax_error_handler`	`module_name()`	The handler to call to generate an error. The module should export a function `serve/1` which should behave like the handler function of the same name. If this setting is omitted, internal response generation will provide a very basic error response page.
`cfg_openflax_error_mode`	`boolean()`	Internal (you should not specify this directly in a configuration file.) Set to `true` once an error has occurred. This is to stop an error handler which contains an error from going into an infinite loop.
`cfg_openflax_watchers`	`[pid()]`	Cumulative. Internal (you cannot specify this directly in a configuration file.) A list of processes which are notified each time a request is dealt with. This setting is typically set up by the `start/1` callback of a handler.
`cfg_openflax_dispatch`	`[dispatch_rule()]`	Cumulative. Described above.

`sres_non_cacheable`	`boolean()`	If `true`, declares the current response being generated to be "non cacheable" - the user agent will be instructed not to cache it. While this is largely internal, it can be placed in a configuration file to indicate that some (or all) content is not to be cached.
`sres_keep_alive`	`boolean()`	If `true`, declares that persistent connections are to be preferred - the user agent will be instructed to "stay on the line". Note that this behaviour is currently experimental.
`sres_response_code`	`string()`	Internal (you should not set this yourself; instead you should let `response()`s such as `not_found` handle it for you.) The response code, such as "404 Not Found", sent to the user agent.

OpenFlax Configuration File Format 1.0 Draft

Configuration Files

Sections

Settings

Cumulative Settings

The `cfg_openflax_dispatch` Setting

Hi"}.

Other `cfg_openflax_*` Settings

`sres_*` Settings

OpenFlax Configuration File Format 1.0 Draft

Configuration Files

Sections

Settings

Cumulative Settings

The cfg_openflax_dispatch Setting

Hi"}.

Other cfg_openflax_* Settings

sres_* Settings

The `cfg_openflax_dispatch` Setting

Other `cfg_openflax_*` Settings

`sres_*` Settings