{1 Porting [netcgi1] programs to [netcgi2]}
The library [netcgi2] is a revised version of the old [cgi] library
which is now also referred to as [netcgi1].
As any software, [netcgi1] aged, and suffered more and more from
inadequate interfaces. Because of this it became necessary to
improve the interfaces from grounds up. The result is [netcgi2],
a new major version that tries to continue the good parts of
[netcgi1] while replacing its problematic edges.
When this text is written, [netcgi2] is still being developed, and
subject of discussion.
{2 Why porting and when?}
It is not possible to use [netcgi1] and [netcgi2] at the same time in the
same application. This means that one cannot gradually upgrade from
[netcgi1] to [netcgi2] by using more and more of the [netcgi2] features.
Instead of this, it is necessary to {b switch} from [netcgi1] to [netcgi2]
at one point in the lifetime of the web application.
The main benefit is that you have access to the newest [netcgi2]
features. There are already a number of connectors that are not
present in [netcgi1] (newer AJP protocol version, SCGI). Furthermore,
new features will only be added to [netcgi2].
However, if your application is already at or near its end of lifetime,
there is no need to port it to [netcgi2]. The [netcgi1] library will
remain in Ocamlnet 2, and bugs will be fixed.
{2 Module Organization}
The new organization is very simple:
- {!Netcgi} defines all basic types. Previously, this was done in the
two modules [Netcgi_env] and [Netcgi_types]
- For every connector c there is one module [Netcgi_]c implementing
it. Especially the classic CGI connector is now in [Netcgi_cgi].
Previously, the CGI connector was defined in [Netcgi], and there
used to be several modules per connector.
- {!Netcgi_common} defines service functions to define new connectors.
There is also a module {!Netcgi1_compat} trying to ease porting. See
below for a discussion.
{2 Interface Changes}
Most of the types remain the same, or almost the same. A few changes
have been done:
- {b Immutability of arguments:} A {!Netcgi.cgi_argument} is no longer writable.
Furthermore, the list of arguments in a {!Netcgi.cgi_activation} can no longer
be modified. There are some new service functions to modify lists
of arguments in case one needs such a list.
- {b Enhanced cookie API:} Cookie formats newer than the old Netscape
format are supported. Old and new cookie types can be transformed
into each other. See the module {!Netcgi.Cookie}.
- {b Exception Handling:} The {!Netcgi_common.HTTP} exception can be used to exit
from a processor at any time. There is the notion of an exception
handler for web-related exceptions.
- {b Simplified Environments:} The CGI environments
{!Netcgi.cgi_environment} have been simplified.
It is only distinguished between two states: Output headers have been/
have not been sent. Other processing states are hidden by the
implementation.
- {b Improved finalization:} All CGI arguments are finalized at the
end of the request ensuring that temporary files are deleted.
It is also possible to register further finalizers using the
{!Netcgi.cgi_activation.at_exit}
method.
The connectors, however, are now created in very different ways. This
is mainly driven by uniformity: There should be a method of creating
web connectors that works for every kind of connector. Because of this,
the code instantiating connectors in application must always be changed
so it matches the new, uniform conventions. Fortunately, this code is usually
not very extensive.
{2 Porting strategies}
{3 Strategy: Use new API}
In the long term this is the best strategy. In principle, one has to
distinguish between
- program parts that access [netcgi] values, and
- program parts that connect the [netcgi] application with the web
server.
Porting the first parts is fairly simple, because the types of the
[netcgi] values do not change much. For example, the function
[web_page] for [netcgi1]
{[
(* This is [netcgi1] code! *)
let web_page (cgi : Netcgi_types.cgi_activation) =
let webarg = cgi # argument_value "webarg" in
cgi # set_header();
cgi # output # output_string ("The argument is: " ^ webarg)
]}
would read in the version for [netcgi2] as follows:
{[
(* This is [netcgi2] code! *)
let web_page (cgi : Netcgi.cgi_activation) =
let webarg = cgi # argument_value "webarg" in
cgi # set_header();
cgi # output # output_string ("The argument is: " ^ webarg)
]}
The {b only} change is that the type [cgi_activation] is now defined
in the module [Netcgi] and no longer in [Netcgi_types]. It is expected
that this simple way of porting applies to almost all parts of
[netcgi] applications.
By the way, the type [cgi_activation] can now be abbreviated as [cgi],
as this is the type name that needs to be written down most
frequently.
{4 The new CGI connector}
In [netcgi1], the CGI connector is selected by instantiating the class
[Netcgi.std_activation], as in:
{[
(* This is [netcgi1] code! *)
let cgi = new Netcgi.std_activation() in
process cgi
]}
It is assumed that [process] is a function taking a [cgi_activation]
as argument, and processing the request.
The corresponding [netcgi2] call is:
{[
(* This is [netcgi2] code! *)
Netcgi_cgi.run process
]}
As you see, {!Netcgi_cgi.run} is now responsible for calling [process].
{4 The new FastCGI connector}
In [netcgi1] there are several ways of using FastCGI. The most common is
to call [Netcgi_fcgi.serv] as in:
{[
(* This is [netcgi1] code! *)
Netcgi_fcgi.serv process optype
]}
It is assumed that [process] is a function taking a [cgi_activation]
as argument, and processing the request. [optype] is a valid
operating type.
The corresponding [netcgi2] call is:
{[
(* This is [netcgi2] code! *)
let process' cgi = process (cgi :> Netcgi.cgi_activation) in
Netcgi_fcgi.run ~output_type:optype process'
]}
Note that the argument of [process'] is a slightly extended version
of [cgi_activation], so you usually need the coercion to cut off the
additional part of the object interface.
{4 The new AJP connector}
The new connector supports now the AJP version 1.3 - this is the default
version used by Jakarta and mod_jk. In [netcgi1], only version 1.2 of
the AJP protocol was supported. The new protocol version is no big
improvement, however. It uses a slightly more compact representation
of the data. The biggest plus is better support of SSL.
In [netcgi1] there was some special machinery around the AJP connector
to create worker processes. This code has been completely removed
in favor of [netplex], the new general-purpose server framework.
Because of that, porting AJP applications is probably a bit of work,
and we cannot give a receipt here how to do that.
{3 Strategy: Use [Netcgi1_compat]}
If you want to use the new connectors but currently do not have time
to check all your code for changes, there is a special helper module
called [Netcgi1_compat] that provides a [netcgi1]-compatible API
on top of either [netcgi1] or [netcgi2].
Because [Netcgi1_compat] is available in both [netcgi1] and [netcgi2]
you can write code that can be compiled for both versions without
needing to change anything. Note, however, that this module is not
100% identical in both versions - the [netcgi2] version includes some
additional functions that converts values from their [netcgi1]
representation to their [netcgi2] representation and vice versa.
Unfortunately, this makes the two versions of this module
binary-incompatible, so you have to recompile your code for either
[netcgi1] or [netcgi2].
The [Netcgi1_compat] module simply contains the relevant parts of
the [netcgi1] API as submodules. That means you can access
- the [netcgi1] version of the module [Netcgi_types] as
[Netcgi1_compat.Netcgi_types]
- the [netcgi1] version of the module [Netcgi_env] as
[Netcgi1_compat.Netcgi_env]
- the [netcgi1] version of the module [Netcgi] as [Netcgi1_compat.Netcgi]
Other modules of [netcgi1] are not covered by the compatibility API.
In [Netcgi], the [custom_activation] class has been left out.
You can usually port code to using this API by either
- prefixing these module names in source code with [Netcgi1.], e.g.
[new Netcgi.std_activation()] would be turned into
[new Netcgi1_compat.Netcgi.std_activation()]
- opening the module [Netcgi1] at the beginning of each .ml and .mli
file by an [open Netcgi1_compat].
Except [Netcgi.std_activation], the [netcgi1] way of creating a
connector for classic CGI, there are no connectors in the
compatibility API. If you need one, you must take it directly
from either [netcgi1] or [netcgi2]. For example, to connect using
FastCGI:
{[
(* This is code for both [netcgi1] and [netcgi2]! *)
let process (cgi : Netcgi1_compat.Netcgi.cgi_activation) =
...
(* This is [netcgi2] code! *)
let process_netcgi2 cgi2 =
let cgi1 = Netcgi1_compat.Netcgi_types.to_compat_activation cgi2 in
process cgi1
Netcgi_fcgi.run ~output_type process'
]}
