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