libfcgi-2.4.0.orig/ 0042775 0001750 0001750 00000000000 07702447537 012602 5 ustar sugi sugi libfcgi-2.4.0.orig/doc/ 0042775 0001750 0001750 00000000000 07612557347 013350 5 ustar sugi sugi libfcgi-2.4.0.orig/doc/fcgi-perf.htm 0100664 0001750 0001750 00000054665 07436304223 015722 0 ustar sugi sugi
10 June 1996
Just how fast is FastCGI? How does the performance of a FastCGI application compare with the performance of the same application implemented using a Web server API?
Of course, the answer is that it depends upon the application. A more complete answer is that FastCGI often wins by a significant margin, and seldom loses by very much.
Papers on computer system performance can be laden with complex graphs showing how this varies with that. Seldom do the graphs shed much light on why one system is faster than another. Advertising copy is often even less informative. An ad from one large Web server vendor says that its server "executes web applications up to five times faster than all other servers," but the ad gives little clue where the number "five" came from.
This paper is meant to convey an understanding of the primary factors that influence the performance of Web server applications and to show that architectural differences between FastCGI and server APIs often give an "unfair" performance advantage to FastCGI applications. We run a test that shows a FastCGI application running three times faster than the corresponding Web server API application. Under different conditions this factor might be larger or smaller. We show you what you'd need to measure to figure that out for the situation you face, rather than just saying "we're three times faster" and moving on.
This paper makes no attempt to prove that FastCGI is better than Web server APIs for every application. Web server APIs enable lightweight protocol extensions, such as Open Market's SecureLink extension, to be added to Web servers, as well as allowing other forms of server customization. But APIs are not well matched to mainstream applications such as personalized content or access to corporate databases, because of API drawbacks including high complexity, low security, and limited scalability. FastCGI shines when used for the vast majority of Web applications.
Since this paper is about performance we need to be clear on what "performance" is.
The standard way to measure performance in a request-response system like the Web is to measure peak request throughput subject to a response time constriaint. For instance, a Web server application might be capable of performing 20 requests per second while responding to 90% of the requests in less than 2 seconds.
Response time is a thorny thing to measure on the Web because client communications links to the Internet have widely varying bandwidth. If the client is slow to read the server's response, response time at both the client and the server will go up, and there's nothing the server can do about it. For the purposes of making repeatable measurements the client should have a high-bandwidth communications link to the server.
[Footnote: When designing a Web server application that will be accessed over slow (e.g. 14.4 or even 28.8 kilobit/second modem) channels, pay attention to the simultaneous connections bottleneck. Some servers are limited by design to only 100 or 200 simultaneous connections. If your application sends 50 kilobytes of data to a typical client that can read 2 kilobytes per second, then a request takes 25 seconds to complete. If your server is limited to 100 simultaneous connections, throughput is limited to just 4 requests per second.]
Response time is seldom an issue when load is light, but response times rise quickly as the system approaches a bottleneck on some limited resource. The three resources that typical systems run out of are network I/O, disk I/O, and processor time. If short response time is a goal, it is a good idea to stay at or below 50% load on each of these resources. For instance, if your disk subsystem is capable of delivering 200 I/Os per second, then try to run your application at 100 I/Os per second to avoid having the disk subsystem contribute to slow response times. Through careful management it is possible to succeed in running closer to the edge, but careful management is both difficult and expensive so few systems get it.
If a Web server application is local to the Web server machine, then its internal design has no impact on network I/O. Application design can have a big impact on usage of disk I/O and processor time.
It is a rare Web server application that doesn't run fast when all the information it needs is available in its memory. And if the application doesn't run fast under those conditions, the possible solutions are evident: Tune the processor-hungry parts of the application, install a faster processor, or change the application's functional specification so it doesn't need to do so much work.
The way to make information available in memory is by caching. A cache is an in-memory data structure that contains information that's been read from its permanent home on disk. When the application needs information, it consults the cache, and uses the information if it is there. Otherwise is reads the information from disk and places a copy in the cache. If the cache is full, the application discards some old information before adding the new. When the application needs to change cached information, it changes both the cache entry and the information on disk. That way, if the application crashes, no information is lost; the application just runs more slowly for awhile after restarting, because the cache doesn't improve performance when it is empty.
Caching can reduce both disk I/O and processor time, because reading information from disk uses more processor time than reading it from the cache. Because caching addresses both of the potential bottlenecks, it is the focal point of high-performance Web server application design. CGI applications couldn't perform in-memory caching, because they exited after processing just one request. Web server APIs promised to solve this problem. But how effective is the solution?
Today's most widely deployed Web server APIs are based on a pool-of-processes server model. The Web server consists of a parent process and a pool of child processes. Processes do not share memory. An incoming request is assigned to an idle child at random. The child runs the request to completion before accepting a new request. A typical server has 32 child processes, a large server has 100 or 200.
In-memory caching works very poorly in this server model because processes do not share memory and incoming requests are assigned to processes at random. For instance, to keep a frequently-used file available in memory the server must keep a file copy per child, which wastes memory. When the file is modified all the children need to be notified, which is complex (the APIs don't provide a way to do it).
FastCGI is designed to allow effective in-memory caching. Requests are routed from any child process to a FastCGI application server. The FastCGI application process maintains an in-memory cache.
In some cases a single FastCGI application server won't provide enough performance. FastCGI provides two solutions: session affinity and multi-threading.
With session affinity you run a pool of application processes and the Web server routes requests to individual processes based on any information contained in the request. For instance, the server can route according to the area of content that's been requested, or according to the user. The user might be identified by an application-specific session identifier, by the user ID contained in an Open Market Secure Link ticket, by the Basic Authentication user name, or whatever. Each process maintains its own cache, and session affinity ensures that each incoming request has access to the cache that will speed up processing the most.
With multi-threading you run an application process that is designed to handle several requests at the same time. The threads handling concurrent requests share process memory, so they all have access to the same cache. Multi-threaded programming is complex -- concurrency makes programs difficult to test and debug -- but with FastCGI you can write single threaded or multithreaded applications.
Many Web server applications perform database access. Existing databases contain a lot of valuable information; Web server applications allow companies to give wider access to the information.
Access to database management systems, even within a single machine, is via connection-oriented protocols. An application "logs in" to a database, creating a connection, then performs one or more accesses. Frequently, the cost of creating the database connection is several times the cost of accessing data over an established connection.
To a first approximation database connections are just another type of state to be cached in memory by an application, so the discussion of caching above applies to caching database connections.
But database connections are special in one respect: They are often the basis for database licensing. You pay the database vendor according to the number of concurrent connections the database system can sustain. A 100-connection license costs much more than a 5-connection license. It follows that caching a database connection per Web server child process is not just wasteful of system's hardware resources, it could break your software budget.
We designed a test application to illustrate performance issues. The application represents a class of applications that deliver personalized content. The test application is quite a bit simpler than any real application would be, but still illustrates the main performance issues. We implemented the application using both FastCGI and a current Web server API, and measured the performance of each.
The application is based on a user database and a set of content files. When a user requests a content file, the application performs substitutions in the file using information from the user database. The application then returns the modified content to the user.
Each request accomplishes the following:
Of course, it is fair game to perform caching to shortcut any of these steps.
Each user's database record (including password and attribute values) is approximately 100 bytes long. Each content file is 3,000 bytes long. Both database and content files are stored on disks attached to the server platform.
A typical user makes 10 file accesses with realistic think times (30-60 seconds) between accesses, then disappears for a long time.
The FastCGI application maintains a cache of recently-accessed attribute values from the database. When the cache misses the application reads from the database. Because only a small number of FastCGI application processes are needed, each process opens a database connection on startup and keeps it open.
The FastCGI application is configured as multiple application processes. This is desirable in order to get concurrent application processing during database reads and file reads. Requests are routed to these application processes using FastCGI session affinity keyed on the user id. This way all a user's requests after the first hit in the application's cache.
The API application does not maintain a cache; the API application has no way to share the cache among its processes, so the cache hit rate would be too low to make caching pay. The API application opens and closes a database connection on every request; keeping database connections open between requests would result in an unrealistically large number of database connections open at the same time, and very low utilization of each connection.
The test load is generated by 10 HTTP client processes. The processes represent disjoint sets of users. A process makes a request for a user, then a request for a different user, and so on until it is time for the first user to make another request.
For simplicity the 10 client processes run on the same machine as the Web server. This avoids the possibility that a network bottleneck will obscure the test results. The database system also runs on this machine, as specified in the application scenario.
Response time is not an issue under the test conditions. We just measure throughput.
The API Web server is in these tests is Netscape 1.1.
Here are the test results:
FastCGI 12.0 msec per request = 83 requests per second API 36.6 msec per request = 27 requests per second
Given the big architectural advantage that the FastCGI application enjoys over the API application, it is not surprising that the FastCGI application runs a lot faster. To gain a deeper understanding of these results we measured two more conditions:
API 16.0 msec per request = 61 requests per secondAnswer: Still not as fast as the FastCGI application.
FastCGI 20.1 msec per request = 50 requests per secondAnswer: A very substantial benefit, even though the database access is quite simple.
What these two extra experiments show is that if the API and FastCGI applications are implemented in exactly the same way -- caching database connections but not caching user profile data -- the API application is slightly faster. This is what you'd expect, since the FastCGI application has to pay the cost of inter-process communication not present in the API application.
In the real world the two applications would not be implemented in the same way. FastCGI's architectural advantage results in much higher performance -- a factor of 3 in this test. With a remote database or more expensive database access the factor would be higher. With more substantial processing of the content files the factor would be smaller.
Web servers with a multi-threaded internal structure (and APIs to match) are now starting to become more common. These servers don't have all of the disadvantages described in Section 3. Does this mean that FastCGI's performance advantages will disappear?
A superficial analysis says yes. An API-based application in a single-process, multi-threaded server can maintain caches and database connections the same way a FastCGI application can. The API-based application does not pay for inter-process communication, so the API-based application will be slightly faster than the FastCGI application.
A deeper analysis says no. Multi-threaded programming is complex, because concurrency makes programs much more difficult to test and debug. In the case of multi-threaded programming to Web server APIs, the normal problems with multi-threading are compounded by the lack of isolation between different applications and between the applications and the Web server. With FastCGI you can write programs in the familiar single-threaded style, get all the reliability and maintainability of process isolation, and still get very high performance. If you truly need multi-threading, you can write multi-threaded FastCGI and still isolate your multi-threaded application from other applications and from the server. In short, multi-threading makes Web server APIs unusable for practially all applications, reducing the choice to FastCGI versus CGI. The performance winner in that contest is obviously FastCGI.
Just how fast is FastCGI? The answer: very fast indeed. Not because it has some specially-greased path through the operating system, but because its design is well matched to the needs of most applications. We invite you to make FastCGI the fast, open foundation for your Web server applications.
Perl (Practical Extraction and Report Language) is a scripting language that is often used for CGI programming. Perl is freely available.
FastCGI support is available for Perl via the FCGI.pm Perl module. FCGI.pm no longer requires SFIO or a specially-built Perl. FCGI.pm is available via CPAN as well as in the perl directory of this kit.
Please see the FCGI.pm documentation for examples and details.
libfcgi-2.4.0.orig/doc/fcgi-tcl.htm 0100664 0001750 0001750 00000036155 07436304223 015542 0 ustar sugi sugi
Michael S. Shanzer
Open Market, Inc.
19 January 1995
Tcl (tool command language) is an embeddable scripting language that's often used for CGI programming. Tcl is freely available as a source kit.
We've built a Tcl interpreter that runs as a FastCGI application. Our purpose in doing so was twofold:
We've succeeded on both counts. We now have a platform for migrating our Tcl-based CGI applications to FastCGI. And the integration required a very small effort. The only source code change to the Tcl interpreter was the routine addition of a handful of new commands: FCGI_Accept, FCGI_Finish, FCGI_SetExitStatus, and FCGI_StartFilterData.
The FastCGI-integrated Tcl interpreter works as usual when run from a shell or as a CGI program. You don't need two Tcls, one for FastCGI and one for other uses.
The remainder of this document gives a recipe you can follow to build FastCGI into Tcl, explains what's happening in the recipe, and illustrates the use of FastCGI Tcl with an example program.
Here are the assumptions embedded in the following recipe:
If those are valid assumptions, follow these steps:
Unpack the tar file in the parent directory of the FastCGI kit directory you used in the previous step, so that the directories tcl7.4 and fcgi-devel-kit are siblings. After unpacking the tar file, follow the directions in the README to apply the patches.
The Sun Labs Tcl/Tk Project Page contains a wealth of information on Tcl, including up to date information on the latest kits.
> cd tcl7.4 > mv tclAppInit.c tclAppInit.c.orig > mv Makefile.in.orig Makefile.in.orig.orig > mv Makefile.in Makefile.in.orig > mv configure.in configure.in.orig > cp ../fcgi-devel-kit/tcl/tcl7.4/* . > cp ../fcgi-devel-kit/tcl/common/* .
> autoconf
> ./configure > makeThe make creates the Tcl interpreter tclsh and library archive libtcl.a (for embedding Tcl in your own C applications). The Tcl README file explains how you can experiment with tclsh without installing it in a standard place.
The recipe alone is fine if you are using Tcl 7.4p3, you have gcc version 2.7, and you have GNU autoconf. In case one or more of these assumptions doesn't hold for you, and to illuminate how little work was involved in integrating FastCGI, here's an explanation of how and why you would modify the files tclAppInit.c, Makefile.in, and configure.in from the Tcl kit.
if (FCGI_Init(interp) == TCL_ERROR) { return TCL_ERROR; }This registers four Tcl commands (FCGI_Accept, FCGI_Finish, FCGI_SetExitStatus, and FCGI_StartFilterData), implemented in tclFCGI.c, with the Tcl interpreter.
This builds the FastCGI Tcl commands and links them into the Tcl interpreter.
This includes fcgi_stdio.h when compiling C code for the Tcl interpreter, overriding the normal stdio types, variables, and functions.
This links the implementation of fcgi_stdio.h into the Tcl interpreter, for use by the FCGI_accept command and any code that uses stdio variables or calls stdio functions.
The last two edits will vary if you use a compiler other than gcc or install the tcl7.4 directory somewhere else in relation to the fcgi-devel-kit directory.
AC_C_CROSS CC=${CC-cc}with the lines
AC_PROG_CC AC_C_CROSSThis selects gcc in preference to other C compilers.
AC_CHECK_LIB(socket, main, [LIBS="$LIBS -lsocket"]) AC_CHECK_LIB(nsl, main, [LIBS="$LIBS -lnsl"]) AC_SUBST(LIBS)This ensures that the socket libraries used by FastCGI are linked into the Tcl interpreter.
> SETENV CC gccbefore running configure.
The Tcl program tcl/tiny-tcl-fcgi performs the same function as the C program examples/tiny-fcgi.c that's used as an example in the FastCGI Developer's Kit document. Here's what the Tcl version looks like:
#!./tclsh set count 0 while {[FCGI_Accept] >= 0 } { incr count puts -nonewline "Content-type: text/html\r\n\r\n" puts "<title>FastCGI Hello! (Tcl)</title>" puts "<h1>FastCGI Hello! (Tcl)</h1>" puts "Request number $count running on host <i>$env(SERVER_NAME)</i>" }
If you've built Tcl according to the recipe and you have a Web server set up to run FastCGI applications, load the FastCGI Developer's Kit Index Page in that server and run this Tcl application now.
The script invokes Tcl indirectly via the symbolic link examples/tclsh. It does this because HP-UX has a limit of 32 characters for the first line of a command-interpreter file such as examples/tiny-tcl-fcgi. If you run on HP-UX you won't want to sprinkle symbolic links to tclsh everywhere, so you should install tclsh with a shorter pathname than /usr/local/tcl7.4-fcgi/bin/tclsh7.4.
The Tcl command FCGI_Accept treats the initial environment differently than the C function FCGI_Accept. The first call to the C function FCGI_Accept replaces the initial environment with the environment of the first request. The first call to the Tcl command FCGI_Accept adds the variable bindings of the first request to the bindings present in the initial environment. So when the first call to FCGI_Accept returns, bindings from the initial environment are still there (unless, due to naming conflicts, some of them have been overwritten by the first request). The next call to FCGI_Accept removes the bindings made on the previous call before adding a new set for the request just accepted, again preserving the initial environment.
The FastCGI-integrated tclsh also includes commands FCGI_Finish, FCGI_SetExitStatus, and FCGI_StartFilterData that correspond to C functions in fcgi_stdio.h; see the manpages for full information.
Converting a Tcl CGI application to FastCGI is not fundamentally different from converting a C CGI application. You separate the portion of the application that performs one-time initialization from the portion that performs per-request processing. You put the per-request processing into a loop controlled by FCGI_Accept.
Mark R. Brown
Open Market, Inc.
2 May 1996
FastCGI is a fast, open, and secure Web server interface that solves the performance problems inherent in CGI without introducing any of the new problems associated with writing applications to lower-level Web server APIs. Modules to support FastCGI can be plugged into Web server APIs such as Apache API, NSAPI, and ISAPI. Key considerations in designing FastCGI included minimizing the cost of migrating CGI applications (including applications written in popular scripting languages such as Perl), supporting both single-threaded and multi-threaded application programming, supporting distributed configurations for scaling and high availability, and generalizing the roles that gateway applications can play beyond CGI's "responder" role.
For more information on FastCGI, including an interface specification and a module for the Apache server, visit the www.fastcgi.com Web site.
The surge in the use of the Web by business has created great demand for applications that create dynamic content. These applications allow businesses to deliver products, services, and messages whose shape and content are influenced by interaction with and knowledge of users.
This move towards dynamic Web content has highlighted the performance limits of CGI (Common Gateway Interface). In response there has been a proliferation of Web server APIs. These APIs address some (though not all) of the performance problems with CGI, but are not designed to meet the need of business applications. When applied to business applications, Web server APIs suffer from these problems:
Web server APIs are suitable for applications that require an intimate connection to the core Web server, such as security protocols. But using a Web server API for a Web business application would be much like using an old-fashioned TP monitor, which required linking applications right into the monitor, for a modern business transaction processing application. The old-fashioned solution suffers a huge development and maintenance cost penalty because it ignores 30 years of progress in computing technology, and may end up providing inferior performance to boot. Nobody uses the old technology unless they are already locked into it.
FastCGI is best viewed as a new implementation of CGI, designed to overcome CGI's performance problems. The major implementation differences are:
FastCGI communicates the exact same information as CGI in a different way. Because FastCGI is CGI, and like CGI runs applications in separate processes, it suffers none of the server API problems listed above.
Open Market has developed a FastCGI application library that implements the FastCGI protocol, hiding the protocol details from the developer. This library, which is freely available, makes writing FastCGI programs as easy as writing CGI applications.
The application library provides replacements for the C language standard I/O (stdio) routines such as printf() and gets(). The library converts references to environment variables, standard input, standard output, and standard error to the FastCGI protocol. References to other files "fall through" to the underlying operating system standard I/O routines. This approach has several benefits:
Here's a simple FastCGI application:
#include <fcgi_stdio.h> void main(void) { int count = 0; while(FCGI_Accept() >= 0) { printf("Content-type: text/html\r\n"); printf("\r\n"); printf("Hello world!<br>\r\n"); printf("Request number %d.", count++); } exit(0); }
This application returns a "Hello world" HTML response to the client. It also keeps a counter of the number of times it has been accessed, displaying the value of the counter at each request. The fcgi_stdio.h header file provides the FastCGI replacement routines for the C standard I/O library. The FCGI_Accept() routine accepts a new request from the Web server.
The application library was designed to make migration of existing CGI programs as simple as possible. Many applications can be converted by adding a loop around the main request processing code and recompiling with the FastCGI application library. To ease migration to FastCGI, executables built with the application library can run as either CGI or FastCGI programs, depending on how they are invoked. The library detects the execution environment and automatically selects FastCGI or regular I/O routines, as appropriate.
Applications written in Perl, Tcl, and other scripting languages can be migrated by using a language interpreter built with the application library. FastCGI-integrated Tcl and Perl interpreters for popular Unix platforms are available from the www.fastcgi.com Web site. The interpreters are backward-compatible: They can run standard Tcl and Perl applications.
FastCGI gives developers a free choice of whether to develop applications in a single-threaded or multi-threaded style. The FastCGI interface supports multi-threading in two ways:
Multi-threaded programming is complex -- concurrency makes programs difficult to test and debug -- so many developers will prefer to program in the familiar single-threaded style. By having several concurrent processes running the same application it is often possible to achieve high performance with single-threaded programming.
The FastCGI interface allows Web servers to implement session affinity, a feature that allows applications to maintain caches of user-related data. With session affinity, when several concurrent processes are running the same application, the Web server routes all requests from a particular user to the same application process. Web server APIs don't provide this functionality to single-threaded applications, so the performance of an API-based application is often inferior to the performance of the corresponding FastCGI application.
Because FastCGI can communicate over TCP/IP connections, it supports configurations in which applications run remotely from the Web server. This can provide scaling, load balancing, high availability, and connections to systems that don't have Web servers.
Distributed FastCGI can also provide security advantages. A Web server outside a corporate firewall can communicate through the firewall to internal databases. For instance, an application might need to authenticate incoming users as customers in order to give access to certain documents on the external Web site. With FastCGI this authentication can be done without replicating data and without compromising security.
A problem with CGI is its limited functionality: CGI programs can only provide responses to requests. FastCGI provides expanded functionality with support for three different application "roles":
Other roles will be defined in the future. For instance, a "logger" role would be useful, where the FastCGI program would receive the server's log entries for real-time processing and analysis.
Today's Web business applications need a platform that's fast, open, maintainable, straightforward, stable, and secure. FastCGI's design meets these requirements, and provides a logical migration path from the proven and widely deployed CGI technology. This allows developers to take advantage of FastCGI's benefits without losing their existing investment in CGI applications.
For more information about FastCGI, visit the www.fastcgi.com Web site.
libfcgi-2.4.0.orig/doc/fcgi-devel-kit.htm 0100664 0001750 0001750 00000100612 07436304223 016632 0 ustar sugi sugi
Mark R. Brown
Open Market, Inc.
Document Version: 1.08
11 June 1996
FastCGI is an open extension to CGI that provides high performance for all Internet applications without the penalties of Web server APIs.
FastCGI is designed to be layered on top of existing Web server APIs. For instance, the mod_fastcgi Apache module adds FastCGI support to the Apache server. FastCGI can also be used, with reduced functionality and reduced performance, on any Web server that supports CGI.
This FastCGI Developer's Kit is designed to make developing FastCGI applications easy. The kit currently supports FastCGI applications written in C/C++, Perl, Tcl, and Java.
This document:
The kit includes a technical white paper, doc/fastcgi-whitepaper/fastcgi.htm. You should read at least the first three sections of the technical white paper before starting to write FastCGI applications. The performance paper will help you understand how application design affects performance with FastCGI.
The FastCGI Specification, doc/fcgi-spec.html, defines the interface between a FastCGI application and a Web server that supports FastCGI. The software in the kit implements the specification. You don't need to read the specification in order to write applications.
Additional information is provided in the FAQ document, which contains frequently asked questions about application development using FastCGI, as well as some general information.
Experience with CGI programming will be extremely valuable in writing FastCGI applications. If you don't have enough experience with CGI programming, you should read one of the popular books on the topic or study the NCSA CGI page. For a more formal treatment of CGI/1.1 see the Internet Draft CGI 1.1 Specification.
The kit is a compressed tar (tar.Z) file, distributed via the fastcgi.com Web page. Unpacking the tar file creates a new directory fcgi-devel-kit.
Open the kit's index page, fcgi-devel-kit/index.html, using the "Open File" command in your Web browser. The index page gives you an overview of the kit structure and helps you navigate the kit. The index page also contains links that run some example applications, but the applications won't work when index.html is opened using the "Open File" command because they aren't aren't being accessed through a Web server.
In order to use the kit in earnest you'll need a Web server that you control, a Web server running with your user ID. The Web server will be starting FastCGI applications that you will need to debug; this will be a lot more convenient for you if these processes run with your user ID. It is best to have a Web server that supports FastCGI. Section 4 discusses Web server issues.
If you can, keep the kit on a file system accessible from your personal workstation, do your builds on your workstation, and run your Web server on your workstation. If that's not possible, arrange a configuration such that the kit is accessible from the machine that's going to run your Web server, and build the kit and your applications on a machine that's configured exactly the same way (same processor architecture, operating system, etc.) as the machine that's going to run your Web server.
To build the kit you execute this sequence of commands in the fcgi-devel-kit directory:
% ./configure % make
We've built and exercised the kit on these platforms (listed in alphabetical order):
Once you've built the kit, follow the directions in Section 4 to bring up your Web server and run the example applications.
The fcgi_stdio library provides the easiest transition for C CGI programs and C CGI programmers to FastCGI. Using this library your application can run using either CGI or FastCGI, with the same binary for both situations.
To introduce the fcgi_stdio library we give a pair of examples: a tiny CGI program and the translation of this program to FastCGI. These two example programs are included in the kit.
The CGI program is examples/tiny-cgi.c:
#include <stdio.h> #include <stdlib.h> void main(void) { int count = 0; printf("Content-type: text/html\r\n" "\r\n" "<title>CGI Hello!</title>" "<h1>CGI Hello!</h1>" "Request number %d running on host <i>%s</i>\n", ++count, getenv("SERVER_NAME")); }
The key features of this tiny CGI program are:
The count variable is degenerate in this example; the CGI program runs a single request, so the request number is always one. This variable will be more interesting in the FastCGI example.
The corresponding FastCGI program is examples/tiny-fcgi.c:
#include "fcgi_stdio.h" #include <stdlib.h> void main(void) { int count = 0; while(FCGI_Accept() >= 0) printf("Content-type: text/html\r\n" "\r\n" "<title>FastCGI Hello!</title>" "<h1>FastCGI Hello!</h1>" "Request number %d running on host <i>%s</i>\n", ++count, getenv("SERVER_NAME")); }
The key features of this tiny FastCGI program are:
The count variable increments each time through the loop, so the program displays a new request number each time. You can use the reload button in your browser to demonstrate this, once you've got the program built and running.
If you can build examples/tiny-cgi.c, it will be straightforward for you to build examples/tiny-fcgi.c. You need to:
See examples/Makefile (created by configure) for a Makefile that builds both programs. Autoconf handles the platform-dependent linking issues; to see how, examine configure.in and examples/Makefile.in.
Section 4 is all about how to run FastCGI applications.
You can use CGI to run application binaries built with the fcgi_stdio library. The FCGI_Accept function tests its environment to determine how the application was invoked. If it was invoked as a CGI program, the first call to FCGI_Accept is essentially a no-op and the second call returns -1. In effect, the request loop disappears.
Of course, when a FastCGI application is run using CGI it does not get the benefits of FastCGI. For instance, the application exits after servicing a single request, so it cannot maintain cached information.
fcgi_stdio.h works by first including stdio.h, then defining macros to replace essentially all of the types and procedures defined in stdio.h. (stdio.h defines a few procedures that have nothing to do with FILE *, such as sprintf and sscanf; fcgi_stdio.h doesn't replace these.) For instance, FILE becomes FCGI_FILE and printf becomes FCGI_printf. You'll only see these new names if you read fcgi_stdio.h or examine your C source code after preprocessing.
Here are some consequences of this implementation technique:
#ifndef _STDIO_H #define _STDIO_H
The specific symbol used for multiple-include protection, _STDIO_H in this example, varies from platform to platform. As long as your platform protects stdio.h against multiple includes, you can forget about this issue.
gcc -include /usr/local/include/fcgi_stdio.h wonderlib.c
causes gcc to include fcgi_stdio.h before it even begins to read the module wonderlib.c.
FILE *myStream = fopen(path, "r"); answer = MungeStream(FCGI_ToFile(myStream));
Here MungeStream is a library function that you can't recompile and FCGI_ToFile is a macro that converts from FCGI_FILE * to FILE *. The macro FCGI_ToFile is defined in fcgi_stdio.h.
The main task in converting a CGI program into a FastCGI program is separating the code that needs to execute once, initializing the program, from the code that needs to run for each request. In our tiny example, initializing the count variable is outside the loop, while incrementing the count variable goes inside.
Retained application state may be an issue. You must ensure that any application state created in processing one request has no unintended effects on later requests. FastCGI offers the possibility of significant application performance improvements, through caching; it is up to you to make the caches work correctly.
Storage leaks may be an issue. Many CGI programs don't worry about storage leaks because the programs don't run for long enough for bloating to be a problem. When converting to FastCGI, you can either use a tool such as Purify from Pure Software to discover and fix storage leaks, or you can run a C garbage collector such as Great Circle from Geodesic Systems.
Currently there are some limits to the compatibility provided by the fcgi_stdio library:
FILE *myStream = fopen(path, "r"); count = fscanf(FCGI_ToFile(myStream), format, ...);
The FCGI_Accept manpage, doc/FCGI_Accept.3, describes the function in the traditional format.
The FCGI_Finish (doc/FCGI_Finish.3), FCGI_SetExitStatus (doc/FCGI_SetExitStatus.3), and FCGI_StartFilterData (doc/FCGI_StartFilterData.3) manpages document capabilities of the fcgi-stdio library that are not illustrated above.
The fcgiapp library is a second C library for FastCGI. It does not provide the high degree of source code compatibility provided by fcgi_stdio; in return, it does not make such heavy use of #define. fcgi_stdio is implemented as a thin layer on top of fcgiapp.
Applications built using the fcgiapp library cannot run as CGI programs; that feature is provided at the fcgi_stdio level.
Functions defined in fcgiapp are named using the prefix FCGX_ rather than FCGI_. For instance, FCGX_Accept is the fcgiapp version of FCGI_Accept.
Documentation of the fcgiapp library takes the form of extensive comments in the header file include/fcgiapp.h. The sample programs examples/tiny-fcgi2.c and examples/echo2.c illustrate how to use fcgiapp.
A major advantage of the FastCGI approach to high-performance Web applications is its language-neutrality. CGI scripts written in popular languages such as Perl and Tcl can be evolved into high-performance FastCGI applications.
We have produced FastCGI-integrated Perl and Tcl interpreters. Doing so was easy, since Perl and Tcl are conventional C applications and fcgi_stdio was designed for converting conventional C applications. Essentially no source code changes were required in these programs; a small amount of code was added in order to make FCGI_Accept and other FastCGI primitives available in these languages. And because these interpreters were developed using fcgi_stdio, they run standard Perl and Tcl applications (e.g. CGI scripts) as well as FastCGI applications.
See the fastcgi.com Web page for more information about the Perl and Tcl libraries.
Here are the Perl and Tcl versions of tiny-fcgi:
#!./perl use FCGI; $count = 0; while(FCGI::accept() >= 0) { print("Content-type: text/html\r\n\r\n", "<title>FastCGI Hello! (Perl)</title>\n", "<h1>FastCGI Hello! (Perl)</h1>\n"; "Request number ", ++$count, " running on host <i>";$env(SERVER_NAME)</i>"); }
#!./tclsh set count 0 while {[FCGI_Accept] >= 0 } { incr count puts -nonewline "Content-type: text/html\r\n\r\n" puts "<title>FastCGI Hello! (Tcl)</title>" puts "<h1>FastCGI Hello! (Tcl)</h1>" puts "Request number $count running on host <i>$env(SERVER_NAME)</i>" }
Converting a Perl or Tcl CGI application to FastCGI is not fundamentally different from converting a C CGI application to FastCGI. You separate the portion of the application that performs one-time initialization from the portion that performs per-request processing. You put the per-request processing into a loop controlled by FCGI::accept (Perl) or FCGI_Accept (Tcl).
Java is not just for browser-based applets. It is already suitable for writing some Web server applications, and its range of applicability will only grow as Java compilers and other Java tools improve. Java's modules, garbage collection, and threads are especially valuable for writing long-lived application servers.
The FCGIInterface class provides facilities for Java applications analogous to what fcgi_stdio provides for C applications. Using this library your Java application can run using either CGI or FastCGI.
The kit includes separate companion document on using FastCGI with Java. The source code for FastCGI classes is contained in directory java/src and the compiled code in java/classes.
Here is the Java version of tiny-fcgi:
import FCGIInterface; class TinyFCGI { public static void main (String args[]) { int count = 0; while(new FCGIInterface().FCGIaccept()>= 0) { count ++; System.out.println("Content-type: text/html\r\n\r\n"); System.out.println( "<title>FastCGI Hello! (Java)</title>"); System.out.println("<h1>FastCGI Hello! (Java)</h1>"); System.out.println( "request number " + count + " running on host <i>" + System.getProperty("SERVER_NAME") + "</i>"); } } }
For a current listing of Web servers that support FastCGI, see the fastcgi.com Web page.
Some of the Web servers that support FastCGI perform management of FastCGI applications. You don't need to start and stop FastCGI applications; the Web server takes care of this. If an application process should crash, the Web server restarts it.
Web servers support FastCGI via new configuration directives. Since these directives are server-specific, get more information from the documentation that accompanies each server.
The program cgi-fcgi allows you to run FastCGI applications using any Web server that supports CGI.
Here is how cgi-fcgi works. cgi-fcgi is a standard CGI program that uses Unix domain or TCP/IP sockets to communicate with a FastCGI application. cgi-fcgi takes the path name or host/port name of a listening socket as a parameter and connects to the FastCGI application listening on that socket. cgi-fcgi then forwards the CGI environment variables and stdin data to the FastCGI application, and forwards the stdout and stderr data from the FastCGI application to the Web server. When the FastCGI application signals the end of its response, cgi-fcgi flushes its buffers and exits.
Obviously, having cgi-fcgi is not as good as having a server with integrated FastCGI support:
But cgi-fcgi does allow you to develop applications that retain state in memory between connections, which often provides a major performance boost over normal CGI. And all the applications you develop using cgi-fcgi will work with Web servers that have integrated support for FastCGI.
The file examples/tiny-fcgi.cgi demonstrates a way to use cgi-fcgi to run a typical application, in this case the examples/tiny-fcgi application:
#!../cgi-fcgi/cgi-fcgi -f -connect sockets/tiny-fcgi tiny-fcgi
On most Unix platforms, executing this command-interpreter file runs cgi-fcgi with arguments -f and examples/tiny-fcgi.cgi. (Beware: On some Unix platforms, including HP-UX, the first line of a command-interpreter file cannot contain more than 32 characters, including the newline; you may need to install the cgi-fcgi application in a standard place like /usr/local/bin or create a symbolic link to the cgi-fcgi application in the directory containing your application.) The cgi-fcgi program reads the command-interpreter file and connects to the FastCGI application whose listening socket is examples/sockets/tiny-fcgi.
Continuing the example, if cgi-fcgi's connection attempt fails, it creates a new process running the program examples/tiny-fcgi and listening on socket examples/sockets/tiny-fcgi. Then cgi-fcgi retries the connection attempt, which now should succeed.
The cgi-fcgi program has two other modes of operation. In one mode it connects to applications but does not start them; in the other it starts applications but does not connect to them. These modes are required when using TCP/IP. The cgi-fcgi manpage, doc/cgi-fcgi.1, tells the full story.
To run the example applications using cgi-fcgi, start your Web server and give it the directory fcgi-devel-kit as the root of its URL space. If the machine running your server is called bowser and your server is running on port 8888, you'd then open the URL http://bowser:8888/index.html to reach the kit's index page. Now the links on the index page that run example applications via cgi-fcgi should be active.
On Digital UNIX 3.0 there's a problem with Unix domain listening sockets on NFS file systems. The symptom when using cgi-fcgi is an exit status of 38 (ENOTSOCK: socket operation on non-socket), but cgi-fcgi may dump core in this case when compiled optimized. Work-around: Store your Unix domain listening sockets on a non NFS file system, upgrade to Digital UNIX 3.2, or use TCP sockets.
On AIX there's a problem with shared listening sockets. The symptoms can include application core dumps and kernel panic. Work-around: Run a single FastCGI application server per listening socket.
The mailing list fastcgi-developers is used for discussions of issues in developing FastCGI applications. Topics include announcement of FastCGI-capable Web servers or changes to such servers, announcement of new application libraries or changes to such libraries, announcement of known bugs, discussion of design trade-offs in FastCGI application programming, and discussion of development plans and experiences. To join the list, see http://fastcgi.com/fastcgi-developers.
A link to a mail archive can be found on the FastCGI home page, http://www.fastcgi.com
Document Version: 1.0
29 April 1996
FastCGI is an open extension to CGI that provides high performance for all Internet applications without the penalties of Web server APIs.
This specification has narrow goal: to specify, from an application perspective, the interface between a FastCGI application and a Web server that supports FastCGI. Many Web server features related to FastCGI, e.g. application management facilities, have nothing to do with the application to Web server interface, and are not described here.
This specification is for Unix (more precisely, for POSIX systems that support Berkeley Sockets). The bulk of the specification is a simple communications protocol that is independent of byte ordering and will extend to other systems.
We'll introduce FastCGI by comparing it with conventional Unix implementations of CGI/1.1. FastCGI is designed to support long-lived application processes, i.e. application servers. That's a major difference compared with conventional Unix implementations of CGI/1.1, which construct an application process, use it respond to one request, and have it exit.
The initial state of a FastCGI process is more spartan than the initial state of a CGI/1.1 process, because the FastCGI process doesn't begin life connected to anything. It doesn't have the conventional open files stdin, stdout, and stderr, and it doesn't receive much information through environment variables. The key piece of initial state in a FastCGI process is a listening socket, through which it accepts connections from a Web server.
After a FastCGI process accepts a connection on its listening socket, the process executes a simple protocol to receive and send data. The protocol serves two purposes. First, the protocol multiplexes a single transport connection between several independent FastCGI requests. This supports applications that are able to process concurrent requests using event-driven or multi-threaded programming techniques. Second, within each request the protocol provides several independent data streams in each direction. This way, for instance, both stdout and stderr data pass over a single transport connection from the application to the Web server, rather than requiring separate pipes as with CGI/1.1.
A FastCGI application plays one of several well-defined roles. The most familiar is the Responder role, in which the application receives all the information associated with an HTTP request and generates an HTTP response; that's the role CGI/1.1 programs play. A second role is Authorizer, in which the application receives all the information associated with an HTTP request and generates an authorized/unauthorized decision. A third role is Filter, in which the application receives all the information associated with an HTTP request, plus an extra stream of data from a file stored on the Web server, and generates a "filtered" version of the data stream as an HTTP response. The framework is extensible so that more FastCGI can be defined later.
In the remainder of this specification the terms "FastCGI application," "application process," or "application server" are abbreviated to "application" whenever that won't cause confusion.
By default the Web server creates an argument list containing a single element, the name of the application, taken to be the last component of the executable's path name. The Web server may provide a way to specify a different application name, or a more elaborate argument list.
Note that the file executed by the Web server might be an interpreter file (a text file that starts with the characters #!), in which case the application's argument list is constructed as described in the execve manpage.
The Web server leaves a single file descriptor, FCGI_LISTENSOCK_FILENO, open when the application begins execution. This descriptor refers to a listening socket created by the Web server.
FCGI_LISTENSOCK_FILENO equals STDIN_FILENO. The standard descriptors STDOUT_FILENO and STDERR_FILENO are closed when the application begins execution. A reliable method for an application to determine whether it was invoked using CGI or FastCGI is to call getpeername(FCGI_LISTENSOCK_FILENO), which returns -1 with errno set to ENOTCONN for a FastCGI application.
The Web server's choice of reliable transport, Unix stream pipes (AF_UNIX) or TCP/IP (AF_INET), is implicit in the internal state of the FCGI_LISTENSOCK_FILENO socket.
The Web server may use environment variables to pass parameters to the application. This specification defines one such variable, FCGI_WEB_SERVER_ADDRS; we expect more to be defined as the specification evolves. The Web server may provide a way to bind other environment variables, such as the PATH variable.
The Web server may provide a way to specify other components of an application's initial process state, such as the priority, user ID, group ID, root directory, and working directory of the process.
We use C language notation to define protocol message formats. All structure elements are defined in terms of the unsigned char type, and are arranged so that an ISO C compiler lays them out in the obvious manner, with no padding. The first byte defined in the structure is transmitted first, the second byte second, etc.
We use two conventions to abbreviate our definitions.
First, when two adjacent structure components are named identically except for the suffixes "B1" and "B0," it means that the two components may be viewed as a single number, computed as B1<<8 + B0. The name of this single number is the name of the components, minus the suffixes. This convention generalizes in an obvious way to handle numbers represented in more than two bytes.
Second, we extend C structs to allow the form
struct { unsigned char mumbleLengthB1; unsigned char mumbleLengthB0; ... /* other stuff */ unsigned char mumbleData[mumbleLength]; };
meaning a structure of varying length, where the length of a component is determined by the values of the indicated earlier component or components.
A FastCGI application calls accept() on the socket referred to by file descriptor FCGI_LISTENSOCK_FILENO to accept a new transport connection. If the accept() succeeds, and the FCGI_WEB_SERVER_ADDRS environment variable is bound, the application application immediately performs the following special processing:
If FCGI_WEB_SERVER_ADDRS was bound, the application checks the peer IP address of the new connection for membership in the list. If the check fails (including the possibility that the connection didn't use TCP/IP transport), the application responds by closing the connection.
FCGI_WEB_SERVER_ADDRS is expressed as a comma-separated list of IP addresses. Each IP address is written as four decimal numbers in the range [0..255] separated by decimal points. So one legal binding for this variable is FCGI_WEB_SERVER_ADDRS=199.170.183.28,199.170.183.71.
An application may accept several concurrent transport connections, but it need not do so.
Applications execute requests from a Web server using a simple protocol. Details of the protocol depend upon the application's role, but roughly speaking the Web server first sends parameters and other data to the application, then the application sends result data to the Web server, and finally the application sends the Web server an indication that the request is complete.
All data that flows over the transport connection is carried in FastCGI records. FastCGI records accomplish two things. First, records multiplex the transport connection between several independent FastCGI requests. This multiplexing supports applications that are able to process concurrent requests using event-driven or multi-threaded programming techniques. Second, records provide several independent data streams in each direction within a single request. This way, for instance, both stdout and stderr data can pass over a single transport connection from the application to the Web server, rather than requiring separate connections.
typedef struct { unsigned char version; unsigned char type; unsigned char requestIdB1; unsigned char requestIdB0; unsigned char contentLengthB1; unsigned char contentLengthB0; unsigned char paddingLength; unsigned char reserved; unsigned char contentData[contentLength]; unsigned char paddingData[paddingLength]; } FCGI_Record;
A FastCGI record consists of a fixed-length prefix followed by a variable number of content and padding bytes. A record contains seven components:
We use a relaxed C struct initializer syntax to specify constant FastCGI records. We omit the version component, ignore padding, and treat requestId as a number. Thus {FCGI_END_REQUEST, 1, {FCGI_REQUEST_COMPLETE,0}} is a record with type == FCGI_END_REQUEST, requestId == 1, and contentData == {FCGI_REQUEST_COMPLETE,0}.
The protocol allows senders to pad the records they send, and requires receivers to interpret the paddingLength and skip the paddingData. Padding allows senders to keep data aligned for more efficient processing. Experience with the X window system protocols shows the performance benefit of such alignment.
We recommend that records be placed on boundaries that are multiples of eight bytes. The fixed-length portion of a FCGI_Record is eight bytes.
The Web server re-uses FastCGI request IDs; the application keeps track of the current state of each request ID on a given transport connection. A request ID R becomes active when the application receives a record {FCGI_BEGIN_REQUEST, R, ...} and becomes inactive when the application sends a record {FCGI_END_REQUEST, R, ...} to the Web server.
While a request ID R is inactive, the application ignores records with requestId == R, except for FCGI_BEGIN_REQUEST records as just described.
The Web server attempts to keep FastCGI request IDs small. That way the application can keep track of request ID states using a short array rather than a long array or a hash table. An application also has the option of accepting only one request at a time. In this case the application simply checks incoming requestId values against the current request ID.
There are two useful ways of classifying FastCGI record types.
The first distinction is between management records and application records. A management record contains information that is not specific to any Web server request, such as information about the protocol capabilities of the application. An application record contains information about a particular request, identified by the requestId component.
Management records have a requestId value of zero, also called the null request ID. Application records have a nonzero requestId.
The second distinction is between discrete and stream records. A discrete record contains a meaningful unit of data all by itself. A stream record is part of a stream, i.e. a series of zero or more non-empty records (length != 0) of the stream type, followed by an empty record (length == 0) of the stream type. The contentData components of a stream's records, when concatenated, form a byte sequence; this byte sequence is the value of the stream. Therefore the value of a stream is independent of how many records it contains or how its bytes are divided among the non-empty records.
These two classifications are independent. Among the record types defined in this version of the FastCGI protocol, all management record types are also discrete record types, and nearly all application record types are stream record types. But three application record types are discrete, and nothing prevents defining a management record type that's a stream in some later version of the protocol.
In many of their roles, FastCGI applications need to read and write varying numbers of variable-length values. So it is useful to adopt a standard format for encoding a name-value pair.
FastCGI transmits a name-value pair as the length of the name, followed by the length of the value, followed by the name, followed by the value. Lengths of 127 bytes and less can be encoded in one byte, while longer lengths are always encoded in four bytes:
typedef struct { unsigned char nameLengthB0; /* nameLengthB0 >> 7 == 0 */ unsigned char valueLengthB0; /* valueLengthB0 >> 7 == 0 */ unsigned char nameData[nameLength]; unsigned char valueData[valueLength]; } FCGI_NameValuePair11; typedef struct { unsigned char nameLengthB0; /* nameLengthB0 >> 7 == 0 */ unsigned char valueLengthB3; /* valueLengthB3 >> 7 == 1 */ unsigned char valueLengthB2; unsigned char valueLengthB1; unsigned char valueLengthB0; unsigned char nameData[nameLength]; unsigned char valueData[valueLength ((B3 & 0x7f) << 24) + (B2 << 16) + (B1 << 8) + B0]; } FCGI_NameValuePair14; typedef struct { unsigned char nameLengthB3; /* nameLengthB3 >> 7 == 1 */ unsigned char nameLengthB2; unsigned char nameLengthB1; unsigned char nameLengthB0; unsigned char valueLengthB0; /* valueLengthB0 >> 7 == 0 */ unsigned char nameData[nameLength ((B3 & 0x7f) << 24) + (B2 << 16) + (B1 << 8) + B0]; unsigned char valueData[valueLength]; } FCGI_NameValuePair41; typedef struct { unsigned char nameLengthB3; /* nameLengthB3 >> 7 == 1 */ unsigned char nameLengthB2; unsigned char nameLengthB1; unsigned char nameLengthB0; unsigned char valueLengthB3; /* valueLengthB3 >> 7 == 1 */ unsigned char valueLengthB2; unsigned char valueLengthB1; unsigned char valueLengthB0; unsigned char nameData[nameLength ((B3 & 0x7f) << 24) + (B2 << 16) + (B1 << 8) + B0]; unsigned char valueData[valueLength ((B3 & 0x7f) << 24) + (B2 << 16) + (B1 << 8) + B0]; } FCGI_NameValuePair44;
The high-order bit of the first byte of a length indicates the length's encoding. A high-order zero implies a one-byte encoding, a one a four-byte encoding.
This name-value pair format allows the sender to transmit binary values without additional encoding, and enables the receiver to allocate the correct amount of storage immediately even for large values.
The Web server controls the lifetime of transport connections. The Web server can close a connection when no requests are active. Or the Web server can delegate close authority to the application (see FCGI_BEGIN_REQUEST). In this case the application closes the connection at the end of a specified request.
This flexibility accommodates a variety of application styles. Simple applications will process one request at a time and accept a new transport connection for each request. More complex applications will process concurrent requests, over one or multiple transport connections, and will keep transport connections open for long periods of time.
A simple application gets a significant performance boost by closing the transport connection when it has finished writing its response. The Web server needs to control the connection lifetime for long-lived connections.
When an application closes a connection or finds that a connection has closed, the application initiates a new connection.
The Web server can query specific variables within the application. The server will typically perform a query on application startup in order to to automate certain aspects of system configuration.
The application receives a query as a record {FCGI_GET_VALUES, 0, ...}. The contentData portion of a FCGI_GET_VALUES record contains a sequence of name-value pairs with empty values.
The application responds by sending a record {FCGI_GET_VALUES_RESULT, 0, ...} with the values supplied. If the application doesn't understand a variable name that was included in the query, it omits that name from the response.
FCGI_GET_VALUES is designed to allow an open-ended set of variables. The initial set provides information to help the server perform application and connection management:
An application may receive a FCGI_GET_VALUES record at any time. The application's response should not involve the application proper but only the FastCGI library.
The set of management record types is likely to grow in future versions of this protocol. To provide for this evolution, the protocol includes the FCGI_UNKNOWN_TYPE management record. When an application receives a management record whose type T it does not understand, the application responds with {FCGI_UNKNOWN_TYPE, 0, {T}}.
The contentData component of a FCGI_UNKNOWN_TYPE record has the form:
typedef struct { unsigned char type; unsigned char reserved[7]; } FCGI_UnknownTypeBody;
The type component is the type of the unrecognized management record.
The Web server sends a FCGI_BEGIN_REQUEST record to start a request.
The contentData component of a FCGI_BEGIN_REQUEST record has the form:
typedef struct { unsigned char roleB1; unsigned char roleB0; unsigned char flags; unsigned char reserved[5]; } FCGI_BeginRequestBody;
The role component sets the role the Web server expects the application to play. The currently-defined roles are:
Roles are described in more detail in Section 6 below.
The flags component contains a bit that controls connection shutdown:
is a stream record type used in sending name-value pairs from the Web server to the application. The name-value pairs are sent down the stream one after the other, in no specified order.
is a stream record type used in sending arbitrary data from the Web server to the application. FCGI_DATA is a second stream record type used to send additional data to the application.
FCGI_STDOUT and FCGI_STDERR are stream record types for sending arbitrary data and error data respectively from the application to the Web server.
The Web server sends a FCGI_ABORT_REQUEST record to abort a request. After receiving {FCGI_ABORT_REQUEST, R}, the application responds as soon as possible with {FCGI_END_REQUEST, R, {FCGI_REQUEST_COMPLETE, appStatus}}. This is truly a response from the application, not a low-level acknowledgement from the FastCGI library.
A Web server aborts a FastCGI request when an HTTP client closes its transport connection while the FastCGI request is running on behalf of that client. The situation may seem unlikely; most FastCGI requests will have short response times, with the Web server providing output buffering if the client is slow. But the FastCGI application may be delayed communicating with another system, or performing a server push.
When a Web server is not multiplexing requests over a transport connection, the Web server can abort a request by closing the request's transport connection. But with multiplexed requests, closing the transport connection has the unfortunate effect of aborting all the requests on the connection.
The application sends a FCGI_END_REQUEST record to terminate a request, either because the application has processed the request or because the application has rejected the request.
The contentData component of a FCGI_END_REQUEST record has the form:
typedef struct { unsigned char appStatusB3; unsigned char appStatusB2; unsigned char appStatusB1; unsigned char appStatusB0; unsigned char protocolStatus; unsigned char reserved[3]; } FCGI_EndRequestBody;
The appStatus component is an application-level status code. Each role documents its usage of appStatus.
The protocolStatus component is a protocol-level status code; the possible protocolStatus values are:
Role protocols only include records with application record types. They transfer essentially all data using streams.
To make the protocols reliable and to simplify application programming, role protocols are designed to use nearly sequential marshalling. In a protocol with strictly sequential marshalling, the application receives its first input, then its second, etc. until it has received them all. Similarly, the application sends its first output, then its second, etc. until it has sent them all. Inputs are not interleaved with each other, and outputs are not interleaved with each other.
The sequential marshalling rule is too restrictive for some FastCGI roles, because CGI programs can write to both stdout and stderr without timing restrictions. So role protocols that use both FCGI_STDOUT and FCGI_STDERR allow these two streams to be interleaved.
All role protocols use the FCGI_STDERR stream just the way stderr is used in conventional applications programming: to report application-level errors in an intelligible way. Use of the FCGI_STDERR stream is always optional. If an application has no errors to report, it sends either no FCGI_STDERR records or one zero-length FCGI_STDERR record.
When a role protocol calls for transmitting a stream other than FCGI_STDERR, at least one record of the stream type is always transmitted, even if the stream is empty.
Again in the interests of reliable protocols and simplified application programming, role protocols are designed to be nearly request-response. In a truly request-response protocol, the application receives all of its input records before sending its first output record. Request-response protocols don't allow pipelining.
The request-response rule is too restrictive for some FastCGI roles; after all, CGI programs aren't restricted to read all of stdin before starting to write stdout. So some role protocols allow that specific possibility. First the application receives all of its inputs except for a final stream input. As the application begins to receive the final stream input, it can begin writing its output.
When a role protocol uses FCGI_PARAMS to transmit textual values, such as the values that CGI programs obtain from environment variables, the length of the value does not include the terminating null byte, and the value itself does not include a null byte. An application that needs to provide environ(7) format name-value pairs must insert an equal sign between the name and value and append a null byte after the value.
Role protocols do not support the non-parsed header feature of CGI. FastCGI applications set response status using the Status and Location CGI headers.
A Responder FastCGI application has the same purpose as a CGI/1.1 program: It receives all the information associated with an HTTP request and generates an HTTP response.
It suffices to explain how each element of CGI/1.1 is emulated by a Responder:
A Responder performing an update, e.g. implementing a POST method, should compare the number of bytes received on FCGI_STDIN with CONTENT_LENGTH and abort the update if the two numbers are not equal.
An Authorizer FastCGI application receives all the information associated with an HTTP request and generates an authorized/unauthorized decision. In case of an authorized decision the Authorizer can also associate name-value pairs with the HTTP request; when giving an unauthorized decision the Authorizer sends a complete response to the HTTP client.
Since CGI/1.1 defines a perfectly good way to represent the information associated with an HTTP request, Authorizers use the same representation:
An Authorizer application's 200 response may include headers whose names are prefixed with Variable-. These headers communicate name-value pairs from the application to the Web server. For instance, the response header
Variable-AUTH_METHOD: database lookuptransmits the value "database lookup" with name AUTH-METHOD. The server associates such name-value pairs with the HTTP request and includes them in subsequent CGI or FastCGI requests performed in processing the HTTP request. When the application gives a 200 response, the server ignores response headers whose names aren't prefixed with Variable- prefix, and ignores any response content.
For Authorizer response status values other than "200" (OK), the Web server denies access and sends the response status, headers, and content back to the HTTP client.
A Filter FastCGI application receives all the information associated with an HTTP request, plus an extra stream of data from a file stored on the Web server, and generates a "filtered" version of the data stream as an HTTP response.
A Filter is similar in functionality to a Responder that takes a data file as a parameter. The difference is that with a Filter, both the data file and the Filter itself can be access controlled using the Web server's access control mechanisms, while a Responder that takes the name of a data file as a parameter must perform its own access control checks on the data file.
The steps taken by a Filter are similar to those of a Responder. The server presents the Filter with environment variables first, then standard input (normally form POST data), finally the data file input:
A Filter should compare the number of bytes received on FCGI_STDIN with CONTENT_LENGTH and on FCGI_DATA with FCGI_DATA_LENGTH. If the numbers don't match and the Filter is a query, the Filter response should provide an indication that data is missing. If the numbers don't match and the Filter is an update, the Filter should abort the update.
A FastCGI application exits with zero status to indicate that it terminated on purpose, e.g. in order to perform a crude form of garbage collection. A FastCGI application that exits with nonzero status is assumed to have crashed. How a Web server or other application manager responds to applications that exit with zero or nonzero status is outside the scope of this specification.
A Web server can request that a FastCGI application exit by sending it SIGTERM. If the application ignores SIGTERM the Web server can resort to SIGKILL.
FastCGI applications report application-level errors with the FCGI_STDERR stream and the appStatus component of the FCGI_END_REQUEST record. In many cases an error will be reported directly to the user via the FCGI_STDOUT stream.
On Unix, applications report lower-level errors, including FastCGI protocol errors and syntax errors in FastCGI environment variables, to syslog. Depending upon the severity of the error, the application may either continue or exit with nonzero status.
/* * Listening socket file number */ #define FCGI_LISTENSOCK_FILENO 0 typedef struct { unsigned char version; unsigned char type; unsigned char requestIdB1; unsigned char requestIdB0; unsigned char contentLengthB1; unsigned char contentLengthB0; unsigned char paddingLength; unsigned char reserved; } FCGI_Header; /* * Number of bytes in a FCGI_Header. Future versions of the protocol * will not reduce this number. */ #define FCGI_HEADER_LEN 8 /* * Value for version component of FCGI_Header */ #define FCGI_VERSION_1 1 /* * Values for type component of FCGI_Header */ #define FCGI_BEGIN_REQUEST 1 #define FCGI_ABORT_REQUEST 2 #define FCGI_END_REQUEST 3 #define FCGI_PARAMS 4 #define FCGI_STDIN 5 #define FCGI_STDOUT 6 #define FCGI_STDERR 7 #define FCGI_DATA 8 #define FCGI_GET_VALUES 9 #define FCGI_GET_VALUES_RESULT 10 #define FCGI_UNKNOWN_TYPE 11 #define FCGI_MAXTYPE (FCGI_UNKNOWN_TYPE) /* * Value for requestId component of FCGI_Header */ #define FCGI_NULL_REQUEST_ID 0 typedef struct { unsigned char roleB1; unsigned char roleB0; unsigned char flags; unsigned char reserved[5]; } FCGI_BeginRequestBody; typedef struct { FCGI_Header header; FCGI_BeginRequestBody body; } FCGI_BeginRequestRecord; /* * Mask for flags component of FCGI_BeginRequestBody */ #define FCGI_KEEP_CONN 1 /* * Values for role component of FCGI_BeginRequestBody */ #define FCGI_RESPONDER 1 #define FCGI_AUTHORIZER 2 #define FCGI_FILTER 3 typedef struct { unsigned char appStatusB3; unsigned char appStatusB2; unsigned char appStatusB1; unsigned char appStatusB0; unsigned char protocolStatus; unsigned char reserved[3]; } FCGI_EndRequestBody; typedef struct { FCGI_Header header; FCGI_EndRequestBody body; } FCGI_EndRequestRecord; /* * Values for protocolStatus component of FCGI_EndRequestBody */ #define FCGI_REQUEST_COMPLETE 0 #define FCGI_CANT_MPX_CONN 1 #define FCGI_OVERLOADED 2 #define FCGI_UNKNOWN_ROLE 3 /* * Variable names for FCGI_GET_VALUES / FCGI_GET_VALUES_RESULT records */ #define FCGI_MAX_CONNS "FCGI_MAX_CONNS" #define FCGI_MAX_REQS "FCGI_MAX_REQS" #define FCGI_MPXS_CONNS "FCGI_MPXS_CONNS" typedef struct { unsigned char type; unsigned char reserved[7]; } FCGI_UnknownTypeBody; typedef struct { FCGI_Header header; FCGI_UnknownTypeBody body; } FCGI_UnknownTypeRecord;
National Center for Supercomputer Applications, The Common Gateway Interface, version CGI/1.1.
D.R.T. Robinson, The WWW Common Gateway Interface Version 1.1, Internet-Draft, 15 February 1996.
The following chart lists all of the record types and indicates these properties of each:
WS->App management stream FCGI_GET_VALUES x x FCGI_GET_VALUES_RESULT x FCGI_UNKNOWN_TYPE x FCGI_BEGIN_REQUEST x FCGI_ABORT_REQUEST x FCGI_END_REQUEST FCGI_PARAMS x x FCGI_STDIN x x FCGI_DATA x x FCGI_STDOUT x FCGI_STDERR x
Additional notational conventions for the examples:
1. A simple request with no data on stdin, and a successful response:
{FCGI_BEGIN_REQUEST, 1, {FCGI_RESPONDER, 0}} {FCGI_PARAMS, 1, "\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... "} {FCGI_PARAMS, 1, ""} {FCGI_STDIN, 1, ""} {FCGI_STDOUT, 1, "Content-type: text/html\r\n\r\n<html>\n<head> ... "} {FCGI_STDOUT, 1, ""} {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}}
2. Similar to example 1, but this time with data on stdin. The Web server chooses to send the parameters using more FCGI_PARAMS records than before:
{FCGI_BEGIN_REQUEST, 1, {FCGI_RESPONDER, 0}} {FCGI_PARAMS, 1, "\013\002SERVER_PORT80\013\016SER"} {FCGI_PARAMS, 1, "VER_ADDR199.170.183.42 ... "} {FCGI_PARAMS, 1, ""} {FCGI_STDIN, 1, "quantity=100&item=3047936"} {FCGI_STDIN, 1, ""} {FCGI_STDOUT, 1, "Content-type: text/html\r\n\r\n<html>\n<head> ... "} {FCGI_STDOUT, 1, ""} {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}}
3. Similar to example 1, but this time the application detects an error. The application logs a message to stderr, returns a page to the client, and returns non-zero exit status to the Web server. The application chooses to send the page using more FCGI_STDOUT records:
{FCGI_BEGIN_REQUEST, 1, {FCGI_RESPONDER, 0}} {FCGI_PARAMS, 1, "\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... "} {FCGI_PARAMS, 1, ""} {FCGI_STDIN, 1, ""} {FCGI_STDOUT, 1, "Content-type: text/html\r\n\r\n<ht"} {FCGI_STDERR, 1, "config error: missing SI_UID\n"} {FCGI_STDOUT, 1, "ml>\n<head> ... "} {FCGI_STDOUT, 1, ""} {FCGI_STDERR, 1, ""} {FCGI_END_REQUEST, 1, {938, FCGI_REQUEST_COMPLETE}}
4. Two instances of example 1, multiplexed onto a single connection. The first request is more difficult than the second, so the application finishes the requests out of order:
{FCGI_BEGIN_REQUEST, 1, {FCGI_RESPONDER, FCGI_KEEP_CONN}} {FCGI_PARAMS, 1, "\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... "} {FCGI_PARAMS, 1, ""} {FCGI_BEGIN_REQUEST, 2, {FCGI_RESPONDER, FCGI_KEEP_CONN}} {FCGI_PARAMS, 2, "\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... "} {FCGI_STDIN, 1, ""} {FCGI_STDOUT, 1, "Content-type: text/html\r\n\r\n"} {FCGI_PARAMS, 2, ""} {FCGI_STDIN, 2, ""} {FCGI_STDOUT, 2, "Content-type: text/html\r\n\r\n<html>\n<head> ... "} {FCGI_STDOUT, 2, ""} {FCGI_END_REQUEST, 2, {0, FCGI_REQUEST_COMPLETE}} {FCGI_STDOUT, 1, "<html>\n<head> ... "} {FCGI_STDOUT, 1, ""} {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}}