Plasma GitLab Archive
Projects Blog Knowledge

Netcgi_porting

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.

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 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.

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.

Interface Changes

Most of the types remain the same, or almost the same. A few changes have been done:

  • 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.
  • 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.
  • 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.
  • 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.
  • 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.

Porting strategies

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 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.

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.

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.

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.

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'
This web site is published by Informatikbüro Gerd Stolpmann
Powered by Caml