Commit | Line | Data |
852467e2 |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> |
2 | <HTML> |
3 | <!--Copyright (c) 1996 Open Market, Inc. --> |
af1b4cad |
4 | <!--See the file "LICENSE" for information on usage and redistribution--> |
852467e2 |
5 | <!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. --> |
6 | <HEAD> |
7 | <TITLE> |
8 | FastCGI Specification |
9 | </TITLE> |
10 | <STYLE TYPE="text/css"> |
11 | h5.c2 {text-align: center} |
12 | div.c1 {text-align: center} |
13 | </STYLE> |
14 | </HEAD> |
15 | <BODY> |
16 | <DIV CLASS="c1"> |
17 | <H2> |
18 | FastCGI Specification |
19 | </H2> |
20 | </DIV> |
21 | <DIV CLASS="c1"> |
22 | Mark R. Brown<BR> |
23 | Open Market, Inc.<BR> |
24 | <P> |
25 | Document Version: 1.0<BR> |
26 | 29 April 1996<BR> |
27 | </P> |
28 | </DIV> |
29 | <P> |
30 | </P> |
31 | <H5 CLASS="c2"> |
32 | Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge, MA 02142 U.S.A.<BR> |
33 | Tel: 617-621-9500 Fax: 617-621-1703 URL: <A HREF= |
34 | "http://www.openmarket.com/">http://www.openmarket.com/</A><BR> |
35 | <BR> |
36 | $Id: fcgi-spec.html,v 1.4 2002/02/25 00:42:59 robs Exp $ |
37 | </H5> |
38 | <HR> |
39 | <UL TYPE="square"> |
40 | <LI> |
41 | <A HREF="#S1">1. Introduction</A> |
42 | </LI> |
43 | <LI> |
44 | <A HREF="#S2">2. Initial Process State</A> |
45 | <UL TYPE="square"> |
46 | <LI> |
47 | <A HREF="#S2.1">2.1 Argument list</A> |
48 | </LI> |
49 | <LI> |
50 | <A HREF="#S2.2">2.2 File descriptors</A> |
51 | </LI> |
52 | <LI> |
53 | <A HREF="#S2.3">2.3 Environment variables</A> |
54 | </LI> |
55 | <LI> |
56 | <A HREF="#S2.4">2.4 Other state</A> |
57 | </LI> |
58 | </UL> |
59 | </LI> |
60 | <LI> |
61 | <A HREF="#S3">3. Protocol Basics</A> |
62 | <UL TYPE="square"> |
63 | <LI> |
64 | <A HREF="#S3.1">3.1 Notation</A> |
65 | </LI> |
66 | <LI> |
67 | <A HREF="#S3.2">3.2 Accepting Transport Connections</A> |
68 | </LI> |
69 | <LI> |
70 | <A HREF="#S3.3">3.3 Records</A> |
71 | </LI> |
72 | <LI> |
73 | <A HREF="#S3.4">3.4 Name-Value Pairs</A> |
74 | </LI> |
75 | <LI> |
76 | <A HREF="#S3.5">3.5 Closing Transport Connections</A> |
77 | </LI> |
78 | </UL> |
79 | </LI> |
80 | <LI> |
81 | <A HREF="#S4">4. Management Record Types</A> |
82 | <UL TYPE="square"> |
83 | <LI> |
84 | <A HREF="#S4.1">4.1 <TT>FCGI_GET_VALUES, FCGI_GET_VALUES_RESULT</TT></A> |
85 | </LI> |
86 | <LI> |
87 | <A HREF="#S4.2">4.2 <TT>FCGI_UNKNOWN_TYPE</TT></A> |
88 | </LI> |
89 | </UL> |
90 | </LI> |
91 | <LI> |
92 | <A HREF="#S5">5. Application Record Types</A> |
93 | <UL TYPE="square"> |
94 | <LI> |
95 | <A HREF="#S5.1">5.1 <TT>FCGI_BEGIN_REQUEST</TT></A> |
96 | </LI> |
97 | <LI> |
98 | <A HREF="#S5.2">5.2 Name-Value Pair Streams: <TT>FCGI_PARAMS</TT>, <TT>FCGI_RESULTS</TT></A> |
99 | </LI> |
100 | <LI> |
101 | <A HREF="#S5.3">5.3 Byte Streams: <TT>FCGI_STDIN</TT>, <TT>FCGI_DATA</TT>, <TT>FCGI_STDOUT</TT>, |
102 | <TT>FCGI_STDERR</TT></A> |
103 | </LI> |
104 | <LI> |
105 | <A HREF="#S5.4">5.4 <TT>FCGI_ABORT_REQUEST</TT></A> |
106 | </LI> |
107 | <LI> |
108 | <A HREF="#S5.5">5.5 <TT>FCGI_END_REQUEST</TT></A> |
109 | </LI> |
110 | </UL> |
111 | </LI> |
112 | <LI> |
113 | <A HREF="#S6">6. Roles</A> |
114 | <UL TYPE="square"> |
115 | <LI> |
116 | <A HREF="#S6.1">6.1 Role Protocols</A> |
117 | </LI> |
118 | <LI> |
119 | <A HREF="#S6.2">6.2 Responder</A> |
120 | </LI> |
121 | <LI> |
122 | <A HREF="#S6.3">6.3 Authorizer</A> |
123 | </LI> |
124 | <LI> |
125 | <A HREF="#S6.4">6.4 Filter</A> |
126 | </LI> |
127 | </UL> |
128 | </LI> |
129 | <LI> |
130 | <A HREF="#S7">7. Errors</A> |
131 | </LI> |
132 | <LI> |
133 | <A HREF="#S8">8. Types and Constants</A> |
134 | </LI> |
135 | <LI> |
136 | <A HREF="#S9">9. References</A> |
137 | </LI> |
138 | <LI> |
139 | <A HREF="#SA">A. Table: Properties of the record types</A> |
140 | </LI> |
141 | <LI> |
142 | <A HREF="#SB">B. Typical Protocol Message Flow</A> |
143 | </LI> |
144 | </UL> |
145 | <P> |
146 | </P> |
147 | <HR> |
148 | <H3> |
149 | <A NAME="S1">1. Introduction</A> |
150 | </H3> |
151 | <P> |
152 | FastCGI is an open extension to CGI that provides high performance for all Internet applications without the |
153 | penalties of Web server APIs. |
154 | </P> |
155 | <P> |
156 | This specification has narrow goal: to specify, from an application perspective, the interface between a |
157 | FastCGI application and a Web server that supports FastCGI. Many Web server features related to FastCGI, e.g. |
158 | application management facilities, have nothing to do with the application to Web server interface, and are |
159 | not described here. |
160 | </P> |
161 | <P> |
162 | This specification is for Unix (more precisely, for POSIX systems that support Berkeley Sockets). The bulk of |
163 | the specification is a simple communications protocol that is independent of byte ordering and will extend to |
164 | other systems. |
165 | </P> |
166 | <P> |
167 | We'll introduce FastCGI by comparing it with conventional Unix implementations of CGI/1.1. FastCGI is |
168 | designed to support long-lived application processes, i.e. <I>application servers</I>. That's a major |
169 | difference compared with conventional Unix implementations of CGI/1.1, which construct an application process, |
170 | use it respond to one request, and have it exit. |
171 | </P> |
172 | <P> |
173 | The initial state of a FastCGI process is more spartan than the initial state of a CGI/1.1 process, because |
174 | the FastCGI process doesn't begin life connected to anything. It doesn't have the conventional open |
175 | files <TT>stdin</TT>, <TT>stdout</TT>, and <TT>stderr</TT>, and it doesn't receive much information |
176 | through environment variables. The key piece of initial state in a FastCGI process is a listening socket, |
177 | through which it accepts connections from a Web server. |
178 | </P> |
179 | <P> |
180 | After a FastCGI process accepts a connection on its listening socket, the process executes a simple protocol |
181 | to receive and send data. The protocol serves two purposes. First, the protocol multiplexes a single transport |
182 | connection between several independent FastCGI requests. This supports applications that are able to process |
183 | concurrent requests using event-driven or multi-threaded programming techniques. Second, within each request |
184 | the protocol provides several independent data streams in each direction. This way, for instance, both |
185 | <TT>stdout</TT> and <TT>stderr</TT> data pass over a single transport connection from the application to the |
186 | Web server, rather than requiring separate pipes as with CGI/1.1. |
187 | </P> |
188 | <P> |
189 | A FastCGI application plays one of several well-defined <I>roles</I>. The most familiar is the |
190 | <I>Responder</I> role, in which the application receives all the information associated with an HTTP request |
191 | and generates an HTTP response; that's the role CGI/1.1 programs play. A second role is <I>Authorizer</I>, |
192 | in which the application receives all the information associated with an HTTP request and generates an |
193 | authorized/unauthorized decision. A third role is <I>Filter</I>, in which the application receives all the |
194 | information associated with an HTTP request, plus an extra stream of data from a file stored on the Web |
195 | server, and generates a "filtered" version of the data stream as an HTTP response. The framework is |
196 | extensible so that more FastCGI can be defined later. |
197 | </P> |
198 | <P> |
199 | In the remainder of this specification the terms "FastCGI application," "application |
200 | process," or "application server" are abbreviated to "application" whenever that |
201 | won't cause confusion. |
202 | </P> |
203 | <P> |
204 | </P> |
205 | <H3> |
206 | <A NAME="S2">2. Initial Process State</A> |
207 | </H3> |
208 | <H4> |
209 | <A NAME="S2.1">2.1 Argument list</A> |
210 | </H4> |
211 | <P> |
212 | By default the Web server creates an argument list containing a single element, the name of the application, |
213 | taken to be the last component of the executable's path name. The Web server may provide a way to specify |
214 | a different application name, or a more elaborate argument list. |
215 | </P> |
216 | <P> |
217 | Note that the file executed by the Web server might be an interpreter file (a text file that starts with the |
218 | characters <TT>#!</TT>), in which case the application's argument list is constructed as described in the |
219 | <TT>execve</TT> manpage. |
220 | </P> |
221 | <P> |
222 | </P> |
223 | <H4> |
224 | <A NAME="S2.2">2.2 File descriptors</A> |
225 | </H4> |
226 | <P> |
227 | The Web server leaves a single file descriptor, <TT>FCGI_LISTENSOCK_FILENO</TT>, open when the application |
228 | begins execution. This descriptor refers to a listening socket created by the Web server. |
229 | </P> |
230 | <P> |
231 | <TT>FCGI_LISTENSOCK_FILENO</TT> equals <TT>STDIN_FILENO</TT>. The standard descriptors <TT>STDOUT_FILENO</TT> |
232 | and <TT>STDERR_FILENO</TT> are closed when the application begins execution. A reliable method for an |
233 | application to determine whether it was invoked using CGI or FastCGI is to call |
234 | <TT>getpeername(FCGI_LISTENSOCK_FILENO)</TT>, which returns -1 with <TT>errno</TT> set to <TT>ENOTCONN</TT> |
235 | for a FastCGI application. |
236 | </P> |
237 | <P> |
238 | The Web server's choice of reliable transport, Unix stream pipes (<TT>AF_UNIX</TT>) or TCP/IP |
239 | (<TT>AF_INET</TT>), is implicit in the internal state of the <TT>FCGI_LISTENSOCK_FILENO</TT> socket. |
240 | </P> |
241 | <P> |
242 | </P> |
243 | <H4> |
244 | <A NAME="S2.3">2.3 Environment variables</A> |
245 | </H4> |
246 | <P> |
247 | The Web server may use environment variables to pass parameters to the application. This specification defines |
248 | one such variable, <TT>FCGI_WEB_SERVER_ADDRS</TT>; we expect more to be defined as the specification evolves. |
249 | The Web server may provide a way to bind other environment variables, such as the <TT>PATH</TT> variable. |
250 | </P> |
251 | <P> |
252 | </P> |
253 | <H4> |
254 | <A NAME="S2.4">2.4 Other state</A> |
255 | </H4> |
256 | <P> |
257 | The Web server may provide a way to specify other components of an application's initial process state, |
258 | such as the priority, user ID, group ID, root directory, and working directory of the process. |
259 | </P> |
260 | <P> |
261 | </P> |
262 | <H3> |
263 | <A NAME="S3">3. Protocol Basics</A> |
264 | </H3> |
265 | <H4> |
266 | <A NAME="S3.1">3.1 Notation</A> |
267 | </H4> |
268 | <P> |
269 | We use C language notation to define protocol message formats. All structure elements are defined in terms of |
270 | the <TT>unsigned char</TT> type, and are arranged so that an ISO C compiler lays them out in the obvious |
271 | manner, with no padding. The first byte defined in the structure is transmitted first, the second byte second, |
272 | etc. |
273 | </P> |
274 | <P> |
275 | We use two conventions to abbreviate our definitions. |
276 | </P> |
277 | <P> |
278 | First, when two adjacent structure components are named identically except for the suffixes |
279 | "<TT>B1</TT>" and "<TT>B0</TT>," it means that the two components may be viewed as a |
280 | single number, computed as <TT>B1<<8 + B0</TT>. The name of this single number is the name of the |
281 | components, minus the suffixes. This convention generalizes in an obvious way to handle numbers represented in |
282 | more than two bytes. |
283 | </P> |
284 | <P> |
285 | Second, we extend C <TT>struct</TT>s to allow the form |
286 | </P> |
287 | <PRE> |
288 | struct { |
289 | unsigned char mumbleLengthB1; |
290 | unsigned char mumbleLengthB0; |
291 | ... /* other stuff */ |
292 | unsigned char mumbleData[mumbleLength]; |
293 | }; |
294 | </PRE> |
295 | <P> |
296 | meaning a structure of varying length, where the length of a component is determined by the values of the |
297 | indicated earlier component or components. |
298 | </P> |
299 | <P> |
300 | </P> |
301 | <H4> |
302 | <A NAME="S3.2">3.2 Accepting Transport Connections</A> |
303 | </H4> |
304 | <P> |
305 | A FastCGI application calls <TT>accept()</TT> on the socket referred to by file descriptor |
306 | <TT>FCGI_LISTENSOCK_FILENO</TT> to accept a new transport connection. If the <TT>accept()</TT> succeeds, and |
307 | the <TT>FCGI_WEB_SERVER_ADDRS</TT> environment variable is bound, the application application immediately |
308 | performs the following special processing: |
309 | </P> |
310 | <P> |
311 | </P> |
312 | <UL TYPE="square"> |
313 | <LI> |
314 | <TT>FCGI_WEB_SERVER_ADDRS</TT>: The value is a list of valid IP addresses for the Web server. |
315 | <P> |
316 | If <TT>FCGI_WEB_SERVER_ADDRS</TT> was bound, the application checks the peer IP address of the new |
317 | connection for membership in the list. If the check fails (including the possibility that the connection |
318 | didn't use TCP/IP transport), the application responds by closing the connection. |
319 | </P> |
320 | <P> |
321 | <TT>FCGI_WEB_SERVER_ADDRS</TT> is expressed as a comma-separated list of IP addresses. Each IP address |
322 | is written as four decimal numbers in the range [0..255] separated by decimal points. So one legal |
323 | binding for this variable is <TT>FCGI_WEB_SERVER_ADDRS=199.170.183.28,199.170.183.71</TT>. |
324 | </P> |
325 | <BR> |
326 | <BR> |
327 | </LI> |
328 | </UL> |
329 | <P> |
330 | An application may accept several concurrent transport connections, but it need not do so. |
331 | </P> |
332 | <P> |
333 | </P> |
334 | <H4> |
335 | <A NAME="S3.3">3.3 Records</A> |
336 | </H4> |
337 | <P> |
338 | Applications execute requests from a Web server using a simple protocol. Details of the protocol depend upon |
339 | the application's role, but roughly speaking the Web server first sends parameters and other data to the |
340 | application, then the application sends result data to the Web server, and finally the application sends the |
341 | Web server an indication that the request is complete. |
342 | </P> |
343 | <P> |
344 | All data that flows over the transport connection is carried in <I>FastCGI records</I>. FastCGI records |
345 | accomplish two things. First, records multiplex the transport connection between several independent FastCGI |
346 | requests. This multiplexing supports applications that are able to process concurrent requests using |
347 | event-driven or multi-threaded programming techniques. Second, records provide several independent data |
348 | streams in each direction within a single request. This way, for instance, both <TT>stdout</TT> and |
349 | <TT>stderr</TT> data can pass over a single transport connection from the application to the Web server, |
350 | rather than requiring separate connections. |
351 | </P> |
352 | <P> |
353 | </P> |
354 | <PRE> |
355 | typedef struct { |
356 | unsigned char version; |
357 | unsigned char type; |
358 | unsigned char requestIdB1; |
359 | unsigned char requestIdB0; |
360 | unsigned char contentLengthB1; |
361 | unsigned char contentLengthB0; |
362 | unsigned char paddingLength; |
363 | unsigned char reserved; |
364 | unsigned char contentData[contentLength]; |
365 | unsigned char paddingData[paddingLength]; |
366 | } FCGI_Record; |
367 | </PRE> |
368 | <P> |
369 | A FastCGI record consists of a fixed-length prefix followed by a variable number of content and padding bytes. |
370 | A record contains seven components: |
371 | </P> |
372 | <P> |
373 | </P> |
374 | <UL TYPE="square"> |
375 | <LI> |
376 | <TT>version</TT>: Identifies the FastCGI protocol version. This specification documents |
377 | <TT>FCGI_VERSION_1</TT>. |
378 | <P> |
379 | </P> |
380 | </LI> |
381 | <LI> |
382 | <TT>type</TT>: Identifies the FastCGI record type, i.e. the general function that the record performs. |
383 | Specific record types and their functions are detailed in later sections. |
384 | <P> |
385 | </P> |
386 | </LI> |
387 | <LI> |
388 | <TT>requestId</TT>: Identifies the <I>FastCGI request</I> to which the record belongs. |
389 | <P> |
390 | </P> |
391 | </LI> |
392 | <LI> |
393 | <TT>contentLength</TT>: The number of bytes in the <TT>contentData</TT> component of the record. |
394 | <P> |
395 | </P> |
396 | </LI> |
397 | <LI> |
398 | <TT>paddingLength</TT>: The number of bytes in the <TT>paddingData</TT> component of the record. |
399 | <P> |
400 | </P> |
401 | </LI> |
402 | <LI> |
403 | <TT>contentData</TT>: Between 0 and 65535 bytes of data, interpreted according to the record type. |
404 | <P> |
405 | </P> |
406 | </LI> |
407 | <LI> |
408 | <TT>paddingData</TT>: Between 0 and 255 bytes of data, which are ignored.<BR> |
409 | <BR> |
410 | </LI> |
411 | </UL> |
412 | <P> |
413 | We use a relaxed C <TT>struct</TT> initializer syntax to specify constant FastCGI records. We omit the |
414 | <TT>version</TT> component, ignore padding, and treat <TT>requestId</TT> as a number. Thus |
415 | <TT>{FCGI_END_REQUEST, 1, {FCGI_REQUEST_COMPLETE,0}}</TT> is a record with <TT>type == FCGI_END_REQUEST</TT>, |
416 | <TT>requestId == 1</TT>, and <TT>contentData == {FCGI_REQUEST_COMPLETE,0}</TT>. |
417 | </P> |
418 | <P> |
419 | </P> |
420 | <H5> |
421 | Padding |
422 | </H5> |
423 | <P> |
424 | The protocol allows senders to pad the records they send, and requires receivers to interpret the |
425 | <TT>paddingLength</TT> and skip the <TT>paddingData</TT>. Padding allows senders to keep data aligned for more |
426 | efficient processing. Experience with the X window system protocols shows the performance benefit of such |
427 | alignment. |
428 | </P> |
429 | <P> |
430 | We recommend that records be placed on boundaries that are multiples of eight bytes. The fixed-length portion |
431 | of a <TT>FCGI_Record</TT> is eight bytes. |
432 | </P> |
433 | <P> |
434 | </P> |
435 | <H5> |
436 | Managing Request IDs |
437 | </H5> |
438 | <P> |
439 | The Web server re-uses FastCGI request IDs; the application keeps track of the current state of each request |
440 | ID on a given transport connection. A request ID <TT>R</TT> becomes active when the application receives a |
441 | record <TT>{FCGI_BEGIN_REQUEST, R, ...}</TT> and becomes inactive when the application sends a record |
442 | <TT>{FCGI_END_REQUEST, R, ...}</TT> to the Web server. |
443 | </P> |
444 | <P> |
445 | While a request ID <TT>R</TT> is inactive, the application ignores records with <TT>requestId == R</TT>, |
446 | except for <TT>FCGI_BEGIN_REQUEST</TT> records as just described. |
447 | </P> |
448 | <P> |
449 | The Web server attempts to keep FastCGI request IDs small. That way the application can keep track of request |
450 | ID states using a short array rather than a long array or a hash table. An application also has the option of |
451 | accepting only one request at a time. In this case the application simply checks incoming <TT>requestId</TT> |
452 | values against the current request ID. |
453 | </P> |
454 | <P> |
455 | </P> |
456 | <H5> |
457 | Types of Record Types |
458 | </H5> |
459 | <P> |
460 | There are two useful ways of classifying FastCGI record types. |
461 | </P> |
462 | <P> |
463 | The first distinction is between <I>management</I> records and <I>application</I> records. A management record |
464 | contains information that is not specific to any Web server request, such as information about the protocol |
465 | capabilities of the application. An application record contains information about a particular request, |
466 | identified by the <TT>requestId</TT> component. |
467 | </P> |
468 | <P> |
469 | Management records have a <TT>requestId</TT> value of zero, also called the <I>null request ID</I>. |
470 | Application records have a nonzero <TT>requestId</TT>. |
471 | </P> |
472 | <P> |
473 | The second distinction is between <I>discrete</I> and <I>stream</I> records. A discrete record contains a |
474 | meaningful unit of data all by itself. A stream record is part of a <I>stream</I>, i.e. a series of zero or |
475 | more non-empty records (<TT>length != 0</TT>) of the stream type, followed by an empty record (<TT>length == |
476 | 0</TT>) of the stream type. The <TT>contentData</TT> components of a stream's records, when concatenated, |
477 | form a byte sequence; this byte sequence is the value of the stream. Therefore the value of a stream is |
478 | independent of how many records it contains or how its bytes are divided among the non-empty records. |
479 | </P> |
480 | <P> |
481 | These two classifications are independent. Among the record types defined in this version of the FastCGI |
482 | protocol, all management record types are also discrete record types, and nearly all application record types |
483 | are stream record types. But three application record types are discrete, and nothing prevents defining a |
484 | management record type that's a stream in some later version of the protocol. |
485 | </P> |
486 | <P> |
487 | </P> |
488 | <H4> |
489 | <A NAME="S3.4">3.4 Name-Value Pairs</A> |
490 | </H4> |
491 | <P> |
492 | In many of their roles, FastCGI applications need to read and write varying numbers of variable-length values. |
493 | So it is useful to adopt a standard format for encoding a name-value pair. |
494 | </P> |
495 | <P> |
496 | FastCGI transmits a name-value pair as the length of the name, followed by the length of the value, followed |
497 | by the name, followed by the value. Lengths of 127 bytes and less can be encoded in one byte, while longer |
498 | lengths are always encoded in four bytes: |
499 | </P> |
500 | <P> |
501 | </P> |
502 | <PRE> |
503 | typedef struct { |
504 | unsigned char nameLengthB0; /* nameLengthB0 >> 7 == 0 */ |
505 | unsigned char valueLengthB0; /* valueLengthB0 >> 7 == 0 */ |
506 | unsigned char nameData[nameLength]; |
507 | unsigned char valueData[valueLength]; |
508 | } FCGI_NameValuePair11; |
509 | |
510 | typedef struct { |
511 | unsigned char nameLengthB0; /* nameLengthB0 >> 7 == 0 */ |
512 | unsigned char valueLengthB3; /* valueLengthB3 >> 7 == 1 */ |
513 | unsigned char valueLengthB2; |
514 | unsigned char valueLengthB1; |
515 | unsigned char valueLengthB0; |
516 | unsigned char nameData[nameLength]; |
517 | unsigned char valueData[valueLength |
518 | ((B3 & 0x7f) << 24) + (B2 << 16) + (B1 << 8) + B0]; |
519 | } FCGI_NameValuePair14; |
520 | |
521 | typedef struct { |
522 | unsigned char nameLengthB3; /* nameLengthB3 >> 7 == 1 */ |
523 | unsigned char nameLengthB2; |
524 | unsigned char nameLengthB1; |
525 | unsigned char nameLengthB0; |
526 | unsigned char valueLengthB0; /* valueLengthB0 >> 7 == 0 */ |
527 | unsigned char nameData[nameLength |
528 | ((B3 & 0x7f) << 24) + (B2 << 16) + (B1 << 8) + B0]; |
529 | unsigned char valueData[valueLength]; |
530 | } FCGI_NameValuePair41; |
531 | |
532 | typedef struct { |
533 | unsigned char nameLengthB3; /* nameLengthB3 >> 7 == 1 */ |
534 | unsigned char nameLengthB2; |
535 | unsigned char nameLengthB1; |
536 | unsigned char nameLengthB0; |
537 | unsigned char valueLengthB3; /* valueLengthB3 >> 7 == 1 */ |
538 | unsigned char valueLengthB2; |
539 | unsigned char valueLengthB1; |
540 | unsigned char valueLengthB0; |
541 | unsigned char nameData[nameLength |
542 | ((B3 & 0x7f) << 24) + (B2 << 16) + (B1 << 8) + B0]; |
543 | unsigned char valueData[valueLength |
544 | ((B3 & 0x7f) << 24) + (B2 << 16) + (B1 << 8) + B0]; |
545 | } FCGI_NameValuePair44; |
546 | </PRE> |
547 | <P> |
548 | The high-order bit of the first byte of a length indicates the length's encoding. A high-order zero |
549 | implies a one-byte encoding, a one a four-byte encoding. |
550 | </P> |
551 | <P> |
552 | This name-value pair format allows the sender to transmit binary values without additional encoding, and |
553 | enables the receiver to allocate the correct amount of storage immediately even for large values. |
554 | </P> |
555 | <P> |
556 | </P> |
557 | <H4> |
558 | <A NAME="S3.5">3.5 Closing Transport Connections</A> |
559 | </H4> |
560 | <P> |
561 | The Web server controls the lifetime of transport connections. The Web server can close a connection when no |
562 | requests are active. Or the Web server can delegate close authority to the application (see |
563 | <TT>FCGI_BEGIN_REQUEST</TT>). In this case the application closes the connection at the end of a specified |
564 | request. |
565 | </P> |
566 | <P> |
567 | This flexibility accommodates a variety of application styles. Simple applications will process one request at |
568 | a time and accept a new transport connection for each request. More complex applications will process |
569 | concurrent requests, over one or multiple transport connections, and will keep transport connections open for |
570 | long periods of time. |
571 | </P> |
572 | <P> |
573 | A simple application gets a significant performance boost by closing the transport connection when it has |
574 | finished writing its response. The Web server needs to control the connection lifetime for long-lived |
575 | connections. |
576 | </P> |
577 | <P> |
578 | When an application closes a connection or finds that a connection has closed, the application initiates a new |
579 | connection. |
580 | </P> |
581 | <P> |
582 | </P> |
583 | <H3> |
584 | <A NAME="S4">4. Management Record Types</A> |
585 | </H3> |
586 | <H4> |
587 | <A NAME="S4.1">4.1 <TT>FCGI_GET_VALUES, FCGI_GET_VALUES_RESULT</TT></A> |
588 | </H4> |
589 | <P> |
590 | The Web server can query specific variables within the application. The server will typically perform a query |
591 | on application startup in order to to automate certain aspects of system configuration. |
592 | </P> |
593 | <P> |
594 | The application receives a query as a record <TT>{FCGI_GET_VALUES, 0, ...}</TT>. The <TT>contentData</TT> |
595 | portion of a <TT>FCGI_GET_VALUES</TT> record contains a sequence of name-value pairs with empty values. |
596 | </P> |
597 | <P> |
598 | The application responds by sending a record <TT>{FCGI_GET_VALUES_RESULT, 0, ...}</TT> with the values |
599 | supplied. If the application doesn't understand a variable name that was included in the query, it omits |
600 | that name from the response. |
601 | </P> |
602 | <P> |
603 | <TT>FCGI_GET_VALUES</TT> is designed to allow an open-ended set of variables. The initial set provides |
604 | information to help the server perform application and connection management: |
605 | </P> |
606 | <P> |
607 | </P> |
608 | <UL TYPE="square"> |
609 | <LI> |
610 | <TT>FCGI_MAX_CONNS</TT>: The maximum number of concurrent transport connections this application will |
611 | accept, e.g. <TT>"1"</TT> or <TT>"10"</TT>. |
612 | <P> |
613 | </P> |
614 | </LI> |
615 | <LI> |
616 | <TT>FCGI_MAX_REQS</TT>: The maximum number of concurrent requests this application will accept, e.g. |
617 | <TT>"1"</TT> or <TT>"50"</TT>. |
618 | <P> |
619 | </P> |
620 | </LI> |
621 | <LI> |
622 | <TT>FCGI_MPXS_CONNS</TT>: <TT>"0"</TT> if this application does not multiplex connections (i.e. |
623 | handle concurrent requests over each connection), <TT>"1"</TT> otherwise.<BR> |
624 | <BR> |
625 | </LI> |
626 | </UL> |
627 | <P> |
628 | An application may receive a <TT>FCGI_GET_VALUES</TT> record at any time. The application's response |
629 | should not involve the application proper but only the FastCGI library. |
630 | </P> |
631 | <P> |
632 | </P> |
633 | <H4> |
634 | <A NAME="S4.2">4.2 <TT>FCGI_UNKNOWN_TYPE</TT></A> |
635 | </H4> |
636 | <P> |
637 | The set of management record types is likely to grow in future versions of this protocol. To provide for this |
638 | evolution, the protocol includes the <TT>FCGI_UNKNOWN_TYPE</TT> management record. When an application |
639 | receives a management record whose type <TT>T</TT> it does not understand, the application responds with |
640 | <TT>{FCGI_UNKNOWN_TYPE, 0, {T}}</TT>. |
641 | </P> |
642 | <P> |
643 | The <TT>contentData</TT> component of a <TT>FCGI_UNKNOWN_TYPE</TT> record has the form: |
644 | </P> |
645 | <PRE> |
646 | typedef struct { |
647 | unsigned char type; |
648 | unsigned char reserved[7]; |
649 | } FCGI_UnknownTypeBody; |
650 | </PRE> |
651 | <P> |
652 | The <TT>type</TT> component is the type of the unrecognized management record. |
653 | </P> |
654 | <P> |
655 | </P> |
656 | <H3> |
657 | <A NAME="S5">5. Application Record Types</A> |
658 | </H3> |
659 | <H4> |
660 | <A NAME="S5.1">5.1 <TT>FCGI_BEGIN_REQUEST</TT></A> |
661 | </H4> |
662 | <P> |
663 | The Web server sends a <TT>FCGI_BEGIN_REQUEST</TT> record to start a request. |
664 | </P> |
665 | <P> |
666 | The <TT>contentData</TT> component of a <TT>FCGI_BEGIN_REQUEST</TT> record has the form: |
667 | </P> |
668 | <PRE> |
669 | typedef struct { |
670 | unsigned char roleB1; |
671 | unsigned char roleB0; |
672 | unsigned char flags; |
673 | unsigned char reserved[5]; |
674 | } FCGI_BeginRequestBody; |
675 | </PRE> |
676 | <P> |
677 | The <TT>role</TT> component sets the role the Web server expects the application to play. The |
678 | currently-defined roles are: |
679 | </P> |
680 | <P> |
681 | </P> |
682 | <UL TYPE="square"> |
683 | <LI> |
684 | <TT>FCGI_RESPONDER</TT> |
685 | </LI> |
686 | <LI> |
687 | <TT>FCGI_AUTHORIZER</TT> |
688 | </LI> |
689 | <LI> |
690 | <TT>FCGI_FILTER</TT> |
691 | </LI> |
692 | </UL> |
693 | <P> |
694 | Roles are described in more detail in <A HREF="#S6">Section 6</A> below. |
695 | </P> |
696 | <P> |
697 | The <TT>flags</TT> component contains a bit that controls connection shutdown: |
698 | </P> |
699 | <P> |
700 | </P> |
701 | <UL TYPE="square"> |
702 | <LI> |
703 | <TT>flags & FCGI_KEEP_CONN</TT>: If zero, the application closes the connection after responding to |
704 | this request. If not zero, the application does not close the connection after responding to this request; |
705 | the Web server retains responsibility for the connection.<BR> |
706 | <BR> |
707 | </LI> |
708 | </UL> |
709 | <H4> |
710 | <A NAME="S5.2">5.2 Name-Value Pair Stream: <TT>FCGI_PARAMS</TT></A> |
711 | </H4> |
712 | <TT>FCGI_PARAMS</TT> |
713 | <P> |
714 | is a stream record type used in sending name-value pairs from the Web server to the application. The |
715 | name-value pairs are sent down the stream one after the other, in no specified order. |
716 | </P> |
717 | <P> |
718 | </P> |
719 | <H4> |
720 | <A NAME="S5.3">5.3 Byte Streams: <TT>FCGI_STDIN</TT>, <TT>FCGI_DATA</TT>, <TT>FCGI_STDOUT</TT>, |
721 | <TT>FCGI_STDERR</TT></A> |
722 | </H4> |
723 | <TT>FCGI_STDIN</TT> |
724 | <P> |
725 | is a stream record type used in sending arbitrary data from the Web server to the application. |
726 | <TT>FCGI_DATA</TT> is a second stream record type used to send additional data to the application. |
727 | </P> |
728 | <P> |
729 | <TT>FCGI_STDOUT</TT> and <TT>FCGI_STDERR</TT> are stream record types for sending arbitrary data and error |
730 | data respectively from the application to the Web server. |
731 | </P> |
732 | <P> |
733 | </P> |
734 | <H4> |
735 | <A NAME="S5.4">5.4 <TT>FCGI_ABORT_REQUEST</TT></A> |
736 | </H4> |
737 | <P> |
738 | The Web server sends a <TT>FCGI_ABORT_REQUEST</TT> record to abort a request. After receiving |
739 | <TT>{FCGI_ABORT_REQUEST, R}</TT>, the application responds as soon as possible with <TT>{FCGI_END_REQUEST, R, |
740 | {FCGI_REQUEST_COMPLETE, appStatus}}</TT>. This is truly a response from the application, not a low-level |
741 | acknowledgement from the FastCGI library. |
742 | </P> |
743 | <P> |
744 | A Web server aborts a FastCGI request when an HTTP client closes its transport connection while the FastCGI |
745 | request is running on behalf of that client. The situation may seem unlikely; most FastCGI requests will have |
746 | short response times, with the Web server providing output buffering if the client is slow. But the FastCGI |
747 | application may be delayed communicating with another system, or performing a server push. |
748 | </P> |
749 | <P> |
750 | When a Web server is not multiplexing requests over a transport connection, the Web server can abort a request |
751 | by closing the request's transport connection. But with multiplexed requests, closing the transport |
752 | connection has the unfortunate effect of aborting <I>all</I> the requests on the connection. |
753 | </P> |
754 | <P> |
755 | </P> |
756 | <H4> |
757 | <A NAME="S5.5">5.5 <TT>FCGI_END_REQUEST</TT></A> |
758 | </H4> |
759 | <P> |
760 | The application sends a <TT>FCGI_END_REQUEST</TT> record to terminate a request, either because the |
761 | application has processed the request or because the application has rejected the request. |
762 | </P> |
763 | <P> |
764 | The <TT>contentData</TT> component of a <TT>FCGI_END_REQUEST</TT> record has the form: |
765 | </P> |
766 | <PRE> |
767 | typedef struct { |
768 | unsigned char appStatusB3; |
769 | unsigned char appStatusB2; |
770 | unsigned char appStatusB1; |
771 | unsigned char appStatusB0; |
772 | unsigned char protocolStatus; |
773 | unsigned char reserved[3]; |
774 | } FCGI_EndRequestBody; |
775 | </PRE> |
776 | <P> |
777 | The <TT>appStatus</TT> component is an application-level status code. Each role documents its usage of |
778 | <TT>appStatus</TT>. |
779 | </P> |
780 | <P> |
781 | The <TT>protocolStatus</TT> component is a protocol-level status code; the possible <TT>protocolStatus</TT> |
782 | values are: |
783 | </P> |
784 | <P> |
785 | </P> |
786 | <UL TYPE="square"> |
787 | <LI> |
788 | <TT>FCGI_REQUEST_COMPLETE</TT>: normal end of request. |
789 | <P> |
790 | </P> |
791 | </LI> |
792 | <LI> |
793 | <TT>FCGI_CANT_MPX_CONN</TT>: rejecting a new request. This happens when a Web server sends concurrent |
794 | requests over one connection to an application that is designed to process one request at a time per |
795 | connection. |
796 | <P> |
797 | </P> |
798 | </LI> |
799 | <LI> |
800 | <TT>FCGI_OVERLOADED</TT>: rejecting a new request. This happens when the application runs out of some |
801 | resource, e.g. database connections. |
802 | <P> |
803 | </P> |
804 | </LI> |
805 | <LI> |
806 | <TT>FCGI_UNKNOWN_ROLE</TT>: rejecting a new request. This happens when the Web server has specified a role |
807 | that is unknown to the application.<BR> |
808 | <BR> |
809 | </LI> |
810 | </UL> |
811 | <H3> |
812 | <A NAME="S6">6. Roles</A> |
813 | </H3> |
814 | <H4> |
815 | <A NAME="S6.1">6.1 Role Protocols</A> |
816 | </H4> |
817 | <P> |
818 | Role protocols only include records with application record types. They transfer essentially all data using |
819 | streams. |
820 | </P> |
821 | <P> |
822 | To make the protocols reliable and to simplify application programming, role protocols are designed to use |
823 | <I>nearly sequential marshalling</I>. In a protocol with strictly sequential marshalling, the application |
824 | receives its first input, then its second, etc. until it has received them all. Similarly, the application |
825 | sends its first output, then its second, etc. until it has sent them all. Inputs are not interleaved with each |
826 | other, and outputs are not interleaved with each other. |
827 | </P> |
828 | <P> |
829 | The sequential marshalling rule is too restrictive for some FastCGI roles, because CGI programs can write to |
830 | both <TT>stdout</TT> and <TT>stderr</TT> without timing restrictions. So role protocols that use both |
831 | <TT>FCGI_STDOUT</TT> and <TT>FCGI_STDERR</TT> allow these two streams to be interleaved. |
832 | </P> |
833 | <P> |
834 | All role protocols use the <TT>FCGI_STDERR</TT> stream just the way <TT>stderr</TT> is used in conventional |
835 | applications programming: to report application-level errors in an intelligible way. Use of the |
836 | <TT>FCGI_STDERR</TT> stream is always optional. If an application has no errors to report, it sends either no |
837 | <TT>FCGI_STDERR</TT> records or one zero-length <TT>FCGI_STDERR</TT> record. |
838 | </P> |
839 | <P> |
840 | When a role protocol calls for transmitting a stream other than <TT>FCGI_STDERR</TT>, at least one record of |
841 | the stream type is always transmitted, even if the stream is empty. |
842 | </P> |
843 | <P> |
844 | Again in the interests of reliable protocols and simplified application programming, role protocols are |
845 | designed to be <I>nearly request-response</I>. In a truly request-response protocol, the application receives |
846 | all of its input records before sending its first output record. Request-response protocols don't allow |
847 | pipelining. |
848 | </P> |
849 | <P> |
850 | The request-response rule is too restrictive for some FastCGI roles; after all, CGI programs aren't |
851 | restricted to read all of <TT>stdin</TT> before starting to write <TT>stdout</TT>. So some role protocols |
852 | allow that specific possibility. First the application receives all of its inputs except for a final stream |
853 | input. As the application begins to receive the final stream input, it can begin writing its output. |
854 | </P> |
855 | <P> |
856 | When a role protocol uses <TT>FCGI_PARAMS</TT> to transmit textual values, such as the values that CGI |
857 | programs obtain from environment variables, the length of the value does not include the terminating null |
858 | byte, and the value itself does not include a null byte. An application that needs to provide |
859 | <TT>environ(7)</TT> format name-value pairs must insert an equal sign between the name and value and append a |
860 | null byte after the value. |
861 | </P> |
862 | <P> |
863 | Role protocols do not support the non-parsed header feature of CGI. FastCGI applications set response status |
864 | using the <TT>Status</TT> and <TT>Location</TT> CGI headers. |
865 | </P> |
866 | <P> |
867 | </P> |
868 | <H4> |
869 | <A NAME="S6.2">6.2 Responder</A> |
870 | </H4> |
871 | <P> |
872 | A Responder FastCGI application has the same purpose as a CGI/1.1 program: It receives all the information |
873 | associated with an HTTP request and generates an HTTP response. |
874 | </P> |
875 | <P> |
876 | It suffices to explain how each element of CGI/1.1 is emulated by a Responder: |
877 | </P> |
878 | <BR> |
879 | <BR> |
880 | <UL TYPE="square"> |
881 | <LI> |
882 | The Responder application receives CGI/1.1 environment variables from the Web server over |
883 | <TT>FCGI_PARAMS</TT>. |
884 | <P> |
885 | </P> |
886 | </LI> |
887 | <LI> |
888 | Next the Responder application receives CGI/1.1 <TT>stdin</TT> data from the Web server over |
889 | <TT>FCGI_STDIN</TT>. The application receives at most <TT>CONTENT_LENGTH</TT> bytes from this stream before |
890 | receiving the end-of-stream indication. (The application receives less than <TT>CONTENT_LENGTH</TT> bytes |
891 | only if the HTTP client fails to provide them, e.g. because the client crashed.) |
892 | <P> |
893 | </P> |
894 | </LI> |
895 | <LI> |
896 | The Responder application sends CGI/1.1 <TT>stdout</TT> data to the Web server over <TT>FCGI_STDOUT</TT>, |
897 | and CGI/1.1 <TT>stderr</TT> data over <TT>FCGI_STDERR</TT>. The application sends these concurrently, not |
898 | one after the other. The application must wait to finish reading <TT>FCGI_PARAMS</TT> before it begins |
899 | writing <TT>FCGI_STDOUT</TT> and <TT>FCGI_STDERR</TT>, but it needn't finish reading from |
900 | <TT>FCGI_STDIN</TT> before it begins writing these two streams. |
901 | <P> |
902 | </P> |
903 | </LI> |
904 | <LI> |
905 | After sending all its <TT>stdout</TT> and <TT>stderr</TT> data, the Responder application sends a |
906 | <TT>FCGI_END_REQUEST</TT> record. The application sets the <TT>protocolStatus</TT> component to |
907 | <TT>FCGI_REQUEST_COMPLETE</TT> and the <TT>appStatus</TT> component to the status code that the CGI program |
908 | would have returned via the <TT>exit</TT> system call.<BR> |
909 | <BR> |
910 | </LI> |
911 | </UL> |
912 | <P> |
913 | A Responder performing an update, e.g. implementing a <TT>POST</TT> method, should compare the number of bytes |
914 | received on <TT>FCGI_STDIN</TT> with <TT>CONTENT_LENGTH</TT> and abort the update if the two numbers are not |
915 | equal. |
916 | </P> |
917 | <P> |
918 | </P> |
919 | <H4> |
920 | <A NAME="S6.3">6.3 Authorizer</A> |
921 | </H4> |
922 | <P> |
923 | An Authorizer FastCGI application receives all the information associated with an HTTP request and generates |
924 | an authorized/unauthorized decision. In case of an authorized decision the Authorizer can also associate |
925 | name-value pairs with the HTTP request; when giving an unauthorized decision the Authorizer sends a complete |
926 | response to the HTTP client. |
927 | </P> |
928 | <P> |
929 | Since CGI/1.1 defines a perfectly good way to represent the information associated with an HTTP request, |
930 | Authorizers use the same representation: |
931 | </P> |
932 | <P> |
933 | </P> |
934 | <UL TYPE="square"> |
935 | <LI> |
936 | The Authorizer application receives HTTP request information from the Web server on the |
937 | <TT>FCGI_PARAMS</TT> stream, in the same format as a Responder. The Web server does not send |
938 | <TT>CONTENT_LENGTH</TT>, <TT>PATH_INFO</TT>, <TT>PATH_TRANSLATED</TT>, and <TT>SCRIPT_NAME</TT> headers. |
939 | <P> |
940 | </P> |
941 | </LI> |
942 | <LI> |
943 | The Authorizer application sends <TT>stdout</TT> and <TT>stderr</TT> data in the same manner as a |
944 | Responder. The CGI/1.1 response status specifies the disposition of the request. If the application sends |
945 | status 200 (OK), the Web server allows access. Depending upon its configuration the Web server may proceed |
946 | with other access checks, including requests to other Authorizers. |
947 | <P> |
948 | An Authorizer application's 200 response may include headers whose names are prefixed with |
949 | <TT>Variable-</TT>. These headers communicate name-value pairs from the application to the Web server. |
950 | For instance, the response header |
951 | </P> |
952 | <PRE> |
953 | Variable-AUTH_METHOD: database lookup |
954 | </PRE> |
955 | transmits the value <TT>"database lookup"</TT> with name <TT>AUTH-METHOD</TT>. The server |
956 | associates such name-value pairs with the HTTP request and includes them in subsequent CGI or FastCGI |
957 | requests performed in processing the HTTP request. When the application gives a 200 response, the server |
958 | ignores response headers whose names aren't prefixed with <TT>Variable-</TT> prefix, and ignores any |
959 | response content. |
960 | <P> |
961 | For Authorizer response status values other than "200" (OK), the Web server denies access and |
962 | sends the response status, headers, and content back to the HTTP client. |
963 | </P> |
964 | <BR> |
965 | <BR> |
966 | </LI> |
967 | </UL> |
968 | <H4> |
969 | <A NAME="S6.4">6.4 Filter</A> |
970 | </H4> |
971 | <P> |
972 | A Filter FastCGI application receives all the information associated with an HTTP request, plus an extra |
973 | stream of data from a file stored on the Web server, and generates a "filtered" version of the data |
974 | stream as an HTTP response. |
975 | </P> |
976 | <P> |
977 | A Filter is similar in functionality to a Responder that takes a data file as a parameter. The difference is |
978 | that with a Filter, both the data file and the Filter itself can be access controlled using the Web |
979 | server's access control mechanisms, while a Responder that takes the name of a data file as a parameter |
980 | must perform its own access control checks on the data file. |
981 | </P> |
982 | <P> |
983 | The steps taken by a Filter are similar to those of a Responder. The server presents the Filter with |
984 | environment variables first, then standard input (normally form <TT>POST</TT> data), finally the data file |
985 | input: |
986 | </P> |
987 | <BR> |
988 | <BR> |
989 | <UL TYPE="square"> |
990 | <LI> |
991 | Like a Responder, the Filter application receives name-value pairs from the Web server over |
992 | <TT>FCGI_PARAMS</TT>. Filter applications receive two Filter-specific variables: |
993 | <TT>FCGI_DATA_LAST_MOD</TT> and <TT>FCGI_DATA_LENGTH</TT>. |
994 | <P> |
995 | </P> |
996 | </LI> |
997 | <LI> |
998 | Next the Filter application receives CGI/1.1 <TT>stdin</TT> data from the Web server over |
999 | <TT>FCGI_STDIN</TT>. The application receives at most <TT>CONTENT_LENGTH</TT> bytes from this stream before |
1000 | receiving the end-of-stream indication. (The application receives less than <TT>CONTENT_LENGTH</TT> bytes |
1001 | only if the HTTP client fails to provide them, e.g. because the client crashed.) |
1002 | <P> |
1003 | </P> |
1004 | </LI> |
1005 | <LI> |
1006 | Next the Filter application receives the file data from the Web server over <TT>FCGI_DATA</TT>. This |
1007 | file's last modification time (expressed as an integer number of seconds since the epoch January 1, |
1008 | 1970 UTC) is <TT>FCGI_DATA_LAST_MOD</TT>; the application may consult this variable and respond from a |
1009 | cache without reading the file data. The application reads at most <TT>FCGI_DATA_LENGTH</TT> bytes from |
1010 | this stream before receiving the end-of-stream indication. |
1011 | <P> |
1012 | </P> |
1013 | </LI> |
1014 | <LI> |
1015 | The Filter application sends CGI/1.1 <TT>stdout</TT> data to the Web server over <TT>FCGI_STDOUT</TT>, and |
1016 | CGI/1.1 <TT>stderr</TT> data over <TT>FCGI_STDERR</TT>. The application sends these concurrently, not one |
1017 | after the other. The application must wait to finish reading <TT>FCGI_STDIN</TT> before it begins writing |
1018 | <TT>FCGI_STDOUT</TT> and <TT>FCGI_STDERR</TT>, but it needn't finish reading from <TT>FCGI_DATA</TT> |
1019 | before it begins writing these two streams. |
1020 | <P> |
1021 | </P> |
1022 | </LI> |
1023 | <LI> |
1024 | After sending all its <TT>stdout</TT> and <TT>stderr</TT> data, the application sends a |
1025 | <TT>FCGI_END_REQUEST</TT> record. The application sets the <TT>protocolStatus</TT> component to |
1026 | <TT>FCGI_REQUEST_COMPLETE</TT> and the <TT>appStatus</TT> component to the status code that a similar CGI |
1027 | program would have returned via the <TT>exit</TT> system call.<BR> |
1028 | <BR> |
1029 | </LI> |
1030 | </UL> |
1031 | <P> |
1032 | A Filter should compare the number of bytes received on <TT>FCGI_STDIN</TT> with <TT>CONTENT_LENGTH</TT> and |
1033 | on <TT>FCGI_DATA</TT> with <TT>FCGI_DATA_LENGTH</TT>. If the numbers don't match and the Filter is a |
1034 | query, the Filter response should provide an indication that data is missing. If the numbers don't match |
1035 | and the Filter is an update, the Filter should abort the update. |
1036 | </P> |
1037 | <P> |
1038 | </P> |
1039 | <H3> |
1040 | <A NAME="S7">7. Errors</A> |
1041 | </H3> |
1042 | <P> |
1043 | A FastCGI application exits with zero status to indicate that it terminated on purpose, e.g. in order to |
1044 | perform a crude form of garbage collection. A FastCGI application that exits with nonzero status is assumed to |
1045 | have crashed. How a Web server or other application manager responds to applications that exit with zero or |
1046 | nonzero status is outside the scope of this specification. |
1047 | </P> |
1048 | <P> |
1049 | A Web server can request that a FastCGI application exit by sending it <TT>SIGTERM</TT>. If the application |
1050 | ignores <TT>SIGTERM</TT> the Web server can resort to <TT>SIGKILL</TT>. |
1051 | </P> |
1052 | <P> |
1053 | FastCGI applications report application-level errors with the <TT>FCGI_STDERR</TT> stream and the |
1054 | <TT>appStatus</TT> component of the <TT>FCGI_END_REQUEST</TT> record. In many cases an error will be reported |
1055 | directly to the user via the <TT>FCGI_STDOUT</TT> stream. |
1056 | </P> |
1057 | <P> |
1058 | On Unix, applications report lower-level errors, including FastCGI protocol errors and syntax errors in |
1059 | FastCGI environment variables, to <TT>syslog</TT>. Depending upon the severity of the error, the application |
1060 | may either continue or exit with nonzero status. |
1061 | </P> |
1062 | <P> |
1063 | </P> |
1064 | <H3> |
1065 | <A NAME="S8">8. Types and Constants</A> |
1066 | </H3> |
1067 | <PRE> |
1068 | /* |
1069 | * Listening socket file number |
1070 | */ |
1071 | #define FCGI_LISTENSOCK_FILENO 0 |
1072 | |
1073 | typedef struct { |
1074 | unsigned char version; |
1075 | unsigned char type; |
1076 | unsigned char requestIdB1; |
1077 | unsigned char requestIdB0; |
1078 | unsigned char contentLengthB1; |
1079 | unsigned char contentLengthB0; |
1080 | unsigned char paddingLength; |
1081 | unsigned char reserved; |
1082 | } FCGI_Header; |
1083 | |
1084 | /* |
1085 | * Number of bytes in a FCGI_Header. Future versions of the protocol |
1086 | * will not reduce this number. |
1087 | */ |
1088 | #define FCGI_HEADER_LEN 8 |
1089 | |
1090 | /* |
1091 | * Value for version component of FCGI_Header |
1092 | */ |
1093 | #define FCGI_VERSION_1 1 |
1094 | |
1095 | /* |
1096 | * Values for type component of FCGI_Header |
1097 | */ |
1098 | #define FCGI_BEGIN_REQUEST 1 |
1099 | #define FCGI_ABORT_REQUEST 2 |
1100 | #define FCGI_END_REQUEST 3 |
1101 | #define FCGI_PARAMS 4 |
1102 | #define FCGI_STDIN 5 |
1103 | #define FCGI_STDOUT 6 |
1104 | #define FCGI_STDERR 7 |
1105 | #define FCGI_DATA 8 |
1106 | #define FCGI_GET_VALUES 9 |
1107 | #define FCGI_GET_VALUES_RESULT 10 |
1108 | #define FCGI_UNKNOWN_TYPE 11 |
1109 | #define FCGI_MAXTYPE (FCGI_UNKNOWN_TYPE) |
1110 | |
1111 | /* |
1112 | * Value for requestId component of FCGI_Header |
1113 | */ |
1114 | #define FCGI_NULL_REQUEST_ID 0 |
1115 | |
1116 | typedef struct { |
1117 | unsigned char roleB1; |
1118 | unsigned char roleB0; |
1119 | unsigned char flags; |
1120 | unsigned char reserved[5]; |
1121 | } FCGI_BeginRequestBody; |
1122 | |
1123 | typedef struct { |
1124 | FCGI_Header header; |
1125 | FCGI_BeginRequestBody body; |
1126 | } FCGI_BeginRequestRecord; |
1127 | |
1128 | /* |
1129 | * Mask for flags component of FCGI_BeginRequestBody |
1130 | */ |
1131 | #define FCGI_KEEP_CONN 1 |
1132 | |
1133 | /* |
1134 | * Values for role component of FCGI_BeginRequestBody |
1135 | */ |
1136 | #define FCGI_RESPONDER 1 |
1137 | #define FCGI_AUTHORIZER 2 |
1138 | #define FCGI_FILTER 3 |
1139 | |
1140 | typedef struct { |
1141 | unsigned char appStatusB3; |
1142 | unsigned char appStatusB2; |
1143 | unsigned char appStatusB1; |
1144 | unsigned char appStatusB0; |
1145 | unsigned char protocolStatus; |
1146 | unsigned char reserved[3]; |
1147 | } FCGI_EndRequestBody; |
1148 | |
1149 | typedef struct { |
1150 | FCGI_Header header; |
1151 | FCGI_EndRequestBody body; |
1152 | } FCGI_EndRequestRecord; |
1153 | |
1154 | /* |
1155 | * Values for protocolStatus component of FCGI_EndRequestBody |
1156 | */ |
1157 | #define FCGI_REQUEST_COMPLETE 0 |
1158 | #define FCGI_CANT_MPX_CONN 1 |
1159 | #define FCGI_OVERLOADED 2 |
1160 | #define FCGI_UNKNOWN_ROLE 3 |
1161 | |
1162 | /* |
1163 | * Variable names for FCGI_GET_VALUES / FCGI_GET_VALUES_RESULT records |
1164 | */ |
1165 | #define FCGI_MAX_CONNS "FCGI_MAX_CONNS" |
1166 | #define FCGI_MAX_REQS "FCGI_MAX_REQS" |
1167 | #define FCGI_MPXS_CONNS "FCGI_MPXS_CONNS" |
1168 | |
1169 | typedef struct { |
1170 | unsigned char type; |
1171 | unsigned char reserved[7]; |
1172 | } FCGI_UnknownTypeBody; |
1173 | |
1174 | typedef struct { |
1175 | FCGI_Header header; |
1176 | FCGI_UnknownTypeBody body; |
1177 | } FCGI_UnknownTypeRecord; |
1178 | </PRE> |
1179 | <P> |
1180 | </P> |
1181 | <H3> |
1182 | <A NAME="S9">9. References</A> |
1183 | </H3> |
1184 | <P> |
1185 | National Center for Supercomputer Applications, <A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/">The Common Gateway |
1186 | Interface</A>, version CGI/1.1. |
1187 | </P> |
1188 | <P> |
1189 | D.R.T. Robinson, <A HREF="http://cgi-spec.golux.com/">The WWW |
1190 | Common Gateway Interface Version 1.1</A>, Internet-Draft, 15 February 1996. |
1191 | </P> |
1192 | <P> |
1193 | </P> |
1194 | <H3> |
1195 | <A NAME="SA">A. Table: Properties of the record types</A> |
1196 | </H3> |
1197 | <P> |
1198 | The following chart lists all of the record types and indicates these properties of each: |
1199 | </P> |
1200 | <P> |
1201 | </P> |
1202 | <UL TYPE="square"> |
1203 | <LI> |
1204 | <TT>WS->App</TT>: records of this type can only be sent by the Web server to the application. Records of |
1205 | other types can only be sent by the application to the Web server. |
1206 | <P> |
1207 | </P> |
1208 | </LI> |
1209 | <LI> |
1210 | <TT>management</TT>: records of this type contain information that is not specific to a Web server request, |
1211 | and use the null request ID. Records of other types contain request-specific information, and cannot use |
1212 | the null request ID. |
1213 | <P> |
1214 | </P> |
1215 | </LI> |
1216 | <LI> |
1217 | <TT>stream</TT>: records of this type form a stream, terminated by a record with empty |
1218 | <TT>contentData</TT>. Records of other types are discrete; each carries a meaningful unit of data.<BR> |
1219 | <BR> |
1220 | </LI> |
1221 | </UL> |
1222 | <PRE> |
1223 | WS->App management stream |
1224 | |
1225 | FCGI_GET_VALUES x x |
1226 | FCGI_GET_VALUES_RESULT x |
1227 | FCGI_UNKNOWN_TYPE x |
1228 | |
1229 | FCGI_BEGIN_REQUEST x |
1230 | FCGI_ABORT_REQUEST x |
1231 | FCGI_END_REQUEST |
1232 | FCGI_PARAMS x x |
1233 | FCGI_STDIN x x |
1234 | FCGI_DATA x x |
1235 | FCGI_STDOUT x |
1236 | FCGI_STDERR x |
1237 | |
1238 | |
1239 | </PRE> |
1240 | <P> |
1241 | </P> |
1242 | <H3> |
1243 | <A NAME="SB">B. Typical Protocol Message Flow</A> |
1244 | </H3> |
1245 | <P> |
1246 | Additional notational conventions for the examples: |
1247 | </P> |
1248 | <UL> |
1249 | <LI> |
1250 | The <TT>contentData</TT> of stream records (<TT>FCGI_PARAMS</TT>, <TT>FCGI_STDIN</TT>, |
1251 | <TT>FCGI_STDOUT</TT>, and <TT>FCGI_STDERR</TT>) is represented as a character string. A string ending in |
1252 | <TT>" ... "</TT> is too long to display, so only a prefix is shown. |
1253 | </LI> |
1254 | <LI> |
1255 | Messages sent to the Web server are indented with respect to messages received from the Web server. |
1256 | </LI> |
1257 | <LI> |
1258 | Messages are shown in the time sequence experienced by the application. |
1259 | </LI> |
1260 | </UL> |
1261 | <P> |
1262 | 1. A simple request with no data on <TT>stdin</TT>, and a successful response: |
1263 | </P> |
1264 | <PRE> |
1265 | {FCGI_BEGIN_REQUEST, 1, {FCGI_RESPONDER, 0}} |
1266 | {FCGI_PARAMS, 1, "\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... "} |
1267 | {FCGI_PARAMS, 1, ""} |
1268 | {FCGI_STDIN, 1, ""} |
1269 | |
1270 | {FCGI_STDOUT, 1, "Content-type: text/html\r\n\r\n<html>\n<head> ... "} |
1271 | {FCGI_STDOUT, 1, ""} |
1272 | {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}} |
1273 | </PRE> |
1274 | <P> |
1275 | 2. Similar to example 1, but this time with data on <TT>stdin</TT>. The Web server chooses to send the |
1276 | parameters using more <TT>FCGI_PARAMS</TT> records than before: |
1277 | </P> |
1278 | <PRE> |
1279 | {FCGI_BEGIN_REQUEST, 1, {FCGI_RESPONDER, 0}} |
1280 | {FCGI_PARAMS, 1, "\013\002SERVER_PORT80\013\016SER"} |
1281 | {FCGI_PARAMS, 1, "VER_ADDR199.170.183.42 ... "} |
1282 | {FCGI_PARAMS, 1, ""} |
1283 | {FCGI_STDIN, 1, "quantity=100&item=3047936"} |
1284 | {FCGI_STDIN, 1, ""} |
1285 | |
1286 | {FCGI_STDOUT, 1, "Content-type: text/html\r\n\r\n<html>\n<head> ... "} |
1287 | {FCGI_STDOUT, 1, ""} |
1288 | {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}} |
1289 | </PRE> |
1290 | <P> |
1291 | 3. Similar to example 1, but this time the application detects an error. The application logs a message to |
1292 | <TT>stderr</TT>, returns a page to the client, and returns non-zero exit status to the Web server. The |
1293 | application chooses to send the page using more <TT>FCGI_STDOUT</TT> records: |
1294 | </P> |
1295 | <PRE> |
1296 | {FCGI_BEGIN_REQUEST, 1, {FCGI_RESPONDER, 0}} |
1297 | {FCGI_PARAMS, 1, "\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... "} |
1298 | {FCGI_PARAMS, 1, ""} |
1299 | {FCGI_STDIN, 1, ""} |
1300 | |
1301 | {FCGI_STDOUT, 1, "Content-type: text/html\r\n\r\n<ht"} |
1302 | {FCGI_STDERR, 1, "config error: missing SI_UID\n"} |
1303 | {FCGI_STDOUT, 1, "ml>\n<head> ... "} |
1304 | {FCGI_STDOUT, 1, ""} |
1305 | {FCGI_STDERR, 1, ""} |
1306 | {FCGI_END_REQUEST, 1, {938, FCGI_REQUEST_COMPLETE}} |
1307 | </PRE> |
1308 | <P> |
1309 | 4. Two instances of example 1, multiplexed onto a single connection. The first request is more difficult than |
1310 | the second, so the application finishes the requests out of order: |
1311 | </P> |
1312 | <PRE> |
1313 | {FCGI_BEGIN_REQUEST, 1, {FCGI_RESPONDER, FCGI_KEEP_CONN}} |
1314 | {FCGI_PARAMS, 1, "\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... "} |
1315 | {FCGI_PARAMS, 1, ""} |
1316 | {FCGI_BEGIN_REQUEST, 2, {FCGI_RESPONDER, FCGI_KEEP_CONN}} |
1317 | {FCGI_PARAMS, 2, "\013\002SERVER_PORT80\013\016SERVER_ADDR199.170.183.42 ... "} |
1318 | {FCGI_STDIN, 1, ""} |
1319 | |
1320 | {FCGI_STDOUT, 1, "Content-type: text/html\r\n\r\n"} |
1321 | |
1322 | {FCGI_PARAMS, 2, ""} |
1323 | {FCGI_STDIN, 2, ""} |
1324 | |
1325 | {FCGI_STDOUT, 2, "Content-type: text/html\r\n\r\n<html>\n<head> ... "} |
1326 | {FCGI_STDOUT, 2, ""} |
1327 | {FCGI_END_REQUEST, 2, {0, FCGI_REQUEST_COMPLETE}} |
1328 | {FCGI_STDOUT, 1, "<html>\n<head> ... "} |
1329 | {FCGI_STDOUT, 1, ""} |
1330 | {FCGI_END_REQUEST, 1, {0, FCGI_REQUEST_COMPLETE}} |
1331 | </PRE> |
1332 | <P> |
1333 | </P> |
1334 | <HR> |
1335 | <ADDRESS> |
1336 | © 1995, 1996 Open Market, Inc. / mbrown@openmarket.com |
1337 | </ADDRESS> |
1338 | </BODY> |
1339 | </HTML> |
1340 | |