FastCGI is a proposed open standard and we expect both free and commercial Web servers to support it. FastCGI is included in Open Market WebServer and Secure WebServer, versions 2.0 and greater.
FastCGI applications are long-lived, and can persist between client calls. The server spawns the FastCGI process once and it continues to run and satisfy client requests until it is explicitly terminated. You can also ask the Web server to start multiple copies of a FastCGI application, if you expect that concurrent processing will improve the application's performance.
Long-lived applications have two important advantages over short-lived applications:
In most cases, these applications rely on customized Web servers. In other words, since most Web servers do not support long-lived applications, a programmer must code this support into a Web server. This approach requires a tremendous amount of work and also ties the application to a particular server.
Another way to get a long-lived application is to write code that calls routines from the Web server's API. This alternative involves a lot of extra coding, ties the application to a particular Web server, and introduces problems of maintainability, scalability, and security.
We believe that FastCGI is the most general and flexible strategy for building long-lived Web applications.
The three roles supported by the WebServer 2.0 are:
With filter applications, the system administrator maps a particular MIME-type to a particular filter FastCGI application. When a client requests a URL with that MIME-type, the Web server invokes the filter application, which processes the file at the specified URL and sends a response (usually HTML text) back to the client.
For example, suppose you write a filter FastCGI application that converts SGML text to HTML, and map the extension .sgml (MIME-type SGML) to your filter FastCGI application. Now, suppose that a user requests the following URL:
/www.aerjug.com/docs/chap1.sgmlGiven this URL, the Web server passes
chap1.sgml
as input to your filter FastCGI application, which processes chap1.sgml
and returns an HTML version of it to the requesting client.
To mark a FastCGI application as having the authorizer role, the system administrator names the application inside the server configuration file, using a directive called
AuthorizeRegion
. (See the Open Market Web Server manual for information on server configuration directives.)When a client requests a URL that meets the
AuthorizeRegion
criteria, the Web server calls your authorizer FastCGI application. If your application grants authorization (by returning a response code of 200), the Web server resumes execution of commands in the AuthorizeRegion
section. If your application denies authorization (by returning any other response code), the Web server stops processing subsequent commands in the AuthorizeRegion
section, and returns the response from your FastCGI application to the client.Authorizer applications can return headers containing environment variables. Other CGI or FastCGI programs accessing this request (including other authorizers) can access these environment variables. The headers must have the following format:
Variable-name: valueFor example, the following header
Variable-AUTH_METHOD: database lookupcauses the environment variable
AUTH_METHOD
to be set to "database lookup"
for this request. Other CGI or FastCGI applications running on this request can access the value of AUTH_METHOD
. Authorizer applications cannot successfully read from standard input. Any attempts to read from standard input result in an immediate EOF.
All data that authorizer applications write to standard error will get written to the traditional server error logs.
In general, the goal of the libraries is to make the job of writing a FastCGI application as much like writing a CGI application as possible. For example, you use the same techniques for query string decoding, HTML output to stdout, use of environment variables, and so on. When you use our libraries, porting CGI applications to FastCGI is mostly a matter of restructuring the code to take advantage of FastCGI features and libraries.
Initialization code Start of response loop body of response loop End of response loopThe initialization code is run exactly once, when the application is initialized. Initialization code usually performs time-consuming operations such as opening databases or calculating values for tables or bitmaps.
The response loop runs continuously, waiting for client requests to arrive. The loop starts with a call to
FCGI_Accept
, a routine in the FastCGI library. The FCGI_Accept
routine blocks program execution until a client requests the FastCGI application. When a client request comes in, FCGI_Accept
unblocks, runs one iteration of the response loop body, and then blocks again waiting for another client request. The loop terminates only when the system administrator or the Web server kills the FastCGI application.
You set the initial environment of a FastCGI process started by the
AppClass
directive using the -initial-env
option. The process would use this environment to configure its options and locate files or databases.In FastCGI processes started by the
AppClass
directive with the -affinity option, the FCGI_PROCESS_ID
variable is set in the initial environment (not in the environment of a request). FCGI_PROCESS_ID
is a decimal number in the range 0 to N - 1 where N is the number of processes (argument to the -processes
option to AppClass
). The process would use FCGI_PROCESS_ID
in conjunction with other variables to locate session-related files or databases during restart.
PATH_INFO
, PATH_TRANSLATED
, and CONTENT_LENGTH
variables.
FILE_LAST_MOD
: The Web server sets FILE_LAST_MOD
to the date and time that filter input file was last modified. The format is the number of seconds since midnight (UTC), January 1, 1970.
FCGI_DATA_LENGTH
: The application reads at most FCGI_DATA_LENGTH
bytes from the data stream before receiving the end-of-stream indication.
FCGI_ROLE
for each request to RESPONDER
, AUTHORIZER
, or FILTER
.
The fcgi_stdio library implements our philosophy of making FastCGI applications similar to CGI applications, and provides full binary compatibility between FastCGI applications and CGI applications: you can run the same C binary as either CGI or FastCGI.
The fcgiapp library is more specific to FastCGI, and doesn't attempt the veneer of CGI.
We recommend that you use the fcgi_stdio library, and this manual describes the routines in that library. The documentation for the fcgiapp library is in the code in the development kit.
Building FastCGI Applications in Tcl
To build FastCGI applications in Tcl, you need a FastCGI-savvy version of Tcl. We build FastCGI-savvy versions of the Tcl interpreter for several common platforms and make them available on our Website. For details and examples, see Chapter 4, "Developing FastCGI Applications in Tcl," on page 19.
Implementation Details
The FastCGI application libraries are designed to shield you from the details of the FastCGI design. This section is designed for the curious reader who would like some low-level understanding. If you are not curious about the implementation, you can happily skip this section.stdin
, stdout
, and stderr
), plus environment variables, to communicate with an HTTP server. Figure 1: Flow of Data in CGI
The fundamental difference between FastCGI and CGI is that FastCGI applications are long-lived, which means that the Web Server needs to rendezvous with a running application, rather than starting the application in order to explicitly communicate with it.
Figure 2: Flow of Data in FastCGI when server and application are on different machines
The fcgi_stdio Library: I/O Compatibility
The implementation for I/O compatibility is that the library fcgi_stdio.h
contains macros to translate the types and procedures defined in stdio.h into the appropriate FastCGI calls. For example, consider a FastCGI program written in C containing the following line of code:
fprintf(stdout, "<H2>Aerobic Juggling</H2>/n");
fcgi_stdio.h
header file contains the macro
#define fprintf FCGI_fprintfSo the preprocessor translates the
fprintf
call into the following call:
FCGI_fprintf(stdout, "<H2>Aerobic Juggling</H2>/n");
FCGI_fprintf
takes the same arguments as fprintf
. The implementation of FCGI_fprintf tests the file to see if it is a normal C stream or a FastCGI stream, and calls the appropriate implementation.
The
fcgi_stdio.h
header file contains macros to translate calls to all ISO stdio.h routines (and all conventional Posix additions, such as fileno
, fdopen
, popen
, and pclose
) into their FastCGI equivalents.
The implementation is in FCGI_Accept: the FCGI_Accept function tests its environment to determine whether the application was invoked as a CGI program or an FastCGI program. If it was invoked as a CGI program, the request loop will satisfy a single client request and then exit, producing CGI behavior.