Writing an extension for Ocsigen server

This page describes how to extend Ocsigen's server. This can be used to create new ways to generate pages (like Apache modules), to filter and change the requests (for example, rewriting of URLS), to extend the syntax of the configuration file.

Filtering the requests or writing a module to generate pages

You can take as example the files staticmod.ml or accesscontrol.ml from Ocsigen Server's distribution.

The type of request is Ocsigen_extensions.request_info (have a look at it in the interface of module Ocsigen_extensions).

Each extensions loaded in the configuration file tries to handle the request and returns something of type Extensions.answer. If the page is not found by the extension (Ext_not_found), the following one will try to handle the request. If the page is found, the answer is Ext_found r. An extension can also modify the request before giving it to the next one (answer Ext_continue_with of Extensions.request_info), etc.

Filtering the outputs

It is also possible to create extensions that will filter the output of the server (for example to compress it). It is very similar to the previous one. Have a look at the file deflatemod.ml for an example.

Extending the configuration file

Extending the configuration file for an extension

The parsing of Ocsigen's configuration file is using a very basic xml parser (package xml-light). The function to be registered by the Extensions.register_extension function takes two parameters: the path of the web site and the xml subtree.

let parse_config path = function
    Xml.Element ("tag", attr, content) -> ...
      (* Do what you want here *)
  | Xml.Element _ ->
      raise (Extensions.Bad_config_tag_for_extension t)
  | _ -> raise (Extensions.Error_in_config_file "(my extension)")

The module Parseconfig defines functions to parse strings or sizes (in bytes, GB etc).

Giving parameters to an extension

Extensions may take parameters in the configuration file. During the loading of the extension, the function Extensions.get_config () returns the xml tree between <extension> and </extension> (or <library> and </library>). Write a parser for that tree.

Catching the request before it is fully read

For some extensions of the Web server, it is necessary to catch the request before it has been fully read (especially before the body of the request has been read). For example it is the case if you want to write a (reverse) proxy.

Adding new commands for the server

If you want to add your own commands for the server command pipe, do something like:

let () =
  Ocsigen_extensions.register_command_function ~prefix:"yourextensionname"
    (fun s c -> match c with
       | ["mycommand"] -> ...
       | _ -> raise Ocsigen_extensions.Unknown_command)