An arbitrary "filter" can be assigned to any file to be served. A filter
is a program which reads the file and has the program output served
rather than the content of the file. One common use of this feature is
for on-the-fly decompression. For, example a file can be stored in its
compressed form and assigned a filter like the UNIX zcat(1)
utility which uncompresses it. Then the client is served the
uncompressed file but only the compressed version is stored on disk. As
another example, you might use "nroff -man" as a filter to
process UNIX man(1)
utility for formatting man pages before serving. There are many other
interesting uses of filters. Be creative!
A filter is assigned to a file by use of the "Filter=" directive in the
file's record in its index.cache file. For example, the
lines:
File=foo.gz
Content-type=text/plain
Filter=/usr/local/bin/zcat
Content-encoding=none
cause the compressed file foo.gz to be uncompressed on the
fly and served to the client as a text/plain document.
Notice that it is necessary to have the content-encoding line to override
the default action of wndex which is to infer
from the ".gz" suffix that the content-encoding is
x-gzip. If the compressed file were named simply
"foo" then the content-encoding line would be unnecessary.
The "Filter="
directive takes the value of a path to a file in three different forms.
If the path begins with a '/' then it is relative to the
system root. If it begins with '~/' then it is relative to
the WN hierarchy root, and otherwise it is relative to the
directory containing the index.wn file.
If a file has a filter only that file will be filtered, not any wrappers or includes.
The ability to filter files can be restricted in several ways. If
WN is invoked with the -e option then no includes,
filters, or CGI/1.1
programs will be executed.
The -E option in
conjunction with the -t
or -T option restricts
the use of filters to those listed in index.cache files
owned by trusted users or groups. The -u option allows only the
use of filters owned by the owner of the index.cache file
which lists them.
The directory directive:
Default-Filter=/path2/filter
specifies that files in this directory should all be treated as if the
"Filter=" file
directive had been set to /path2/filter. To override this
setting and specify no filter use the "Filter=<none>"
directive.
The filter mechanism built into WN has most of the functionality of the Common Gateway Interface (CGI) standard and has some features CGI/1.1 does not. Filters are also in some ways more secure. This makes them a good choice for applications where compatibility with the CGI/1.1 standard is not required.
The first thing to note is that there is no requirement that the filter program actually make use of the file being filtered. This file must exist though.
Thus if an empty file "foo" is created and has an index.wn file entry like:
File=foo
Content-type=text/html
Filter=someprogram
Attributes=parse,cgi
then the output of the program "someprogram" will be served.
A program used in this way differs somewhat from a CGI/1.1 program in that no
headers should be supplied by the program as WN will
automatically provide them. For example, while a CGI/1.1 program typically
starts with printing "Content-type: text/html" followed by a
blank line, this should not be done for "someprogram" in the
index.wn entry above, because WN will automatically
provide the appropriate HTTP/1.1 headers based on the
"Content-type=text/html"
line in the index.wn file.
An important difference between filters and CGI/1.1 programs is that the
output of filters can be parsed while CGI/1.1 output cannot. The
fact that you want the output parsed must be signalled by the use of an
"Attributes=parse"
line in the directory's index.wn file.
If you wish to have all the standard CGI/1.1 environment variables made available to the filter program you can do so by adding the line:
Attributes=cgi
to the file record. A list of these environment variables can be found
in appendix "CGI and other Environment Variables
for the WN Server" in this guide. Also see the sample CGI program which is located in the
file /docs/examples/sample.cgi which accompanies the
WN distribution.
One difference between CGI/1.1 programs and filters
is that with filters there is no way to have a non-empty PATH_INFO
environment variable since anything appended to the path part of the URL
will be interpreted as a path to an actual file. Of course the "query"
part of a URL (everything after a '?') will work for filters
as well as CGI/1.1
programs and its contents will be put in the QUERY_STRING
environment variable.
Another difference between CGI/1.1 and filter programs
is in the handling of POST or PUT data. A CGI/1.1 program reads the
data provided by the client on its UNIX stdin(3)
stream. This is not possible for a filter since its stdin(3)
is attached to the file it is supposedly filtering. To use the
PUT or POST method with a filtered file, the
"Attributes=post"
directive must be used since otherwise the server will not permit a
POST or PUT. It is then possible to read the
POSTed data by opening and reading the temporary file
containing this data. The name of this file changes with each request,
but if "Attributes=cgi" is
used then the name is given in the WN specific CGI environment
variable HTTP_POST_FILE
or HTTP_PUT_FILE
depending on the method used to submit the data.
One advantage of using a filter instead of a CGI/1.1 program is that it
may have slightly better security. With a filter the name of the
executed program is never visible outside the server. It is not in any
URL and it is not in any served file. Perhaps a more important feature
is that no arguments can be supplied to a filter except those listed in
the index.wn file filter
entry. Unlike CGI/1.1
programs, it is not possible for a remote user to supply any arguments
whatsoever to the program.