Execution Handler

1.0.0 Configuration
2.0.0 The Relation to URI
3.0.0 Name space of CGI (name space of handler)
4.0.0 Environment variables of CGI (handler)
5.0.0 Handling of POST'ed data
6.0.0 CGI timeout

2002/08/26

Execution handler is a program that processes files of specific path pattern.
User can define relations between path pattern and the handler.
This mechanism is used to define the form of CGI file, SSI (Server Side Include) and
auto-indexing service for specific directories.

Configuration

Relations between path patterns and the handler is defined in /etc/handler in service space.
The following is the content of my configuration (http://plan9.aichi-u.ac.jp).

	# path      mimetype    ramfs    execpath arg ...
	/netlib/*/index.html text/html 0 /bin/ftp2html
	*.http         -         0       $target
	*.html      text/html    1       $target
	*.dx_html   text/html    0       /bin/dx $target

The first field is a path pattern and the 4th field is the handler.
The second and the third indicate how to do that.
Comparison of path pattern and requested path is performed from the top of line. Comparison is stopped if pattern is matched to the requested path.
Arguments of the program may continue after 4th field.

In path pattern, directory separator `/' is not special.
( Therefore this pattern matching is not same as that of shell. )
There is one exception: we have a rule that pattern /*/ matches /
Therefore the pattern

	/netlib/*/index.html

matches to /netlib/index.html as well as /netlib/cmd/backup/index.html for example.

Second field of /etc/handler denote `ContentType' of HTTP header.
If the field is `-', the handler must send all HTTP headers.

The third field is a flag that the program is to be served ramfs or not.

The 4th field is the path to handler. Handler must be a executable.
$target in or after 4th field denotes absolute path to the requested document. Note that $target in 4th field means the requested path is an executable program.

/bin/ftp2html in this example is a program that is used in http://plan9.aichi-u.ac.jp/netlib/ to handle my FTP directories. Other server such as Apache has an option to show directory index if index.html is absent. ftp2html also does this action but does much more: if README file is present then the content is shown, and if INDEX file is present then the content is shown with appropriate action tag to the index label.

/bin/dx is a tool that is designed by the author to be used for SSI.

The Relation to URI

HTTP/1.0 and HTTP/1.1 says that we can write param and query after document path of URI. That is,

	path;params?query
	params = param[;params]

Web server traditionally ignored param and passed query as argument to CGI program.
Pegasus changed this traditional manner and accept param as argument parts that should be passed to CGI. On the other hand, Pegasus does not participate in interpritating query and passes it to CGI as environment variable without translation.

Name space of CGI (name space of handler)

Service space of httpd is configured in:

	/lib/namespace.httpd

and namespace of CGI cannot be extended from this namespace except some directory trees such as document are added to this namespace.
( namespace of CGI can be extended only under the option -m of httpd )

Name space of CGI (handler) can be reconfigured (but not extended) using

	/etc/namespace.cgi   # in service space

The typical contents will be:

	bind -a /etc/bin/$objtype /bin
	bind -a /etc/bin/rc	/bin

If the file is absent or nothing is done even if present, name space of CGI is same as service space.

Environment variables of CGI (handler)

Pegasus has many environment variables. However most of them are only experimental.
Fixed variables are shown in the following:

	GATEWAY_INTERFACE
	SERVER_NAME
	SERVER_PORT
	SERVER_SOFTWARE
	SERVER_PROTOCOL
	REQUEST_METHOD
	REMOTE_ADDR
	QUERY_STRING
	HTTP_HEADER
	HTTP_HOST
	HTTP_REFERER
	HTTP_USER_AGENT
	home		# /doc
	query		# same as QUERY_STRING
	target		# path to the requested document
	name		# base name of target
	cputype		# 386
	objtype		# 386
	date		# date like 'Mon, 04 Mar 2002 07:32:40 GMT'</pre>

Other environment variable may be discarded or renamed in the future.

Handling of POST'ed data

If POST'ed data is once received by the server from the client, Content-Length is consulted by the server in receiving the data.
Then server passes the data to CGI as stdin.

CGI timeout

Timeout is defined to prevent buggy programs waiting data so long time.
The value can be specified in httpd option. The default is 5 second. I think the value is enough because the date is already held by the server.