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