Debian Codegraph @

fcgi/doc/fastcgi-prog-guide/ch1intro.htm

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
2 <HTML>
3 <HEAD>
4 <TITLE>
5 FastCGI Programmer&#39;s Guide - Chapter 1, The Fast Common Gateway Interface
6 </TITLE>
7 <STYLE TYPE="text/css">
8 body {
9 background-color: #ffffff;
10 }
11 li.c2 {list-style: none}
12 div.c1 {text-align: center}
13 </STYLE>
14 </HEAD>
15 <BODY>
16 <A HREF="cover.htm">[Top]</A> <A HREF="ap_guide.htm">[Prev]</A> <A HREF="ch2c.htm">[Next]</A> <A HREF=
17 "ap_guida.htm">[Bottom]</A>
18 <HR>
19 <BR>
20 <A NAME="9432"></A>
21 <DIV CLASS="c1">
22 <H1>
23 1 The Fast Common<BR>
24 Gateway Interface
25 </H1>
26 </DIV>
27 <A NAME="7982"></A>
28 <P>
29 The Fast Common Gateway Interface (FastCGI) is an enhancement to the existing CGI (Common Gateway Interface),
30 which is a standard for interfacing external applications with Web servers.
31 </P>
32 <P>
33 <A NAME="8373"></A> FastCGI is a proposed open standard and we expect both free and commercial Web servers to
34 support it. FastCGI is included in Open Market WebServer and Secure WebServer, versions 2.0 and greater.
35 </P>
36 <BR>
37 <BR>
38 <H1>
39 Advantages of FastCGI
40 </H1>
41 <A NAME="8369"></A>
42 <P>
43 FastCGI extends and enhances the CGI model in several ways:
44 </P>
45 <BR>
46 <BR>
47 <UL>
48 <LI CLASS="c2">
49 <A NAME="7832"></A>
50 </LI>
51 <LI>
52 FastCGI enables applications to persist between client requests, eliminating application start up overhead
53 and allowing the application to maintain state between client calls. <A NAME="7995"></A>
54 </LI>
55 <LI>
56 FastCGI enables applications to reside on remote systems (rather than having to reside on the same system
57 as the Web server) <A NAME="7997"></A>
58 </LI>
59 <LI>
60 FastCGI enables additional flexibility in application functionality, with explicit support for applications
61 that do client authentication and filtering of input.
62 </LI>
63 </UL>
64 <H2>
65 Long-lived Applications
66 </H2>
67 <A NAME="8458"></A>
68 <P>
69 CGI applications are ephemeral and short-lived: each time a client requests a CGI application, the server asks
70 the operating system to spawn a new CGI process. After the CGI process satisfies the request, the server kills
71 it. The server spawns and subsequently kills a new process for each client request.
72 </P>
73 <P>
74 <A NAME="8459"></A> FastCGI applications are long-lived, and can persist between client calls. The server
75 spawns the FastCGI process once and it continues to run and satisfy client requests until it is explicitly
76 terminated. You can also ask the Web server to start multiple copies of a FastCGI application, if you expect
77 that concurrent processing will improve the application&#39;s performance.
78 </P>
79 <P>
80 <A NAME="5761"></A> Long-lived applications have two important advantages over short-lived applications:
81 </P>
82 <BR>
83 <BR>
84 <UL>
85 <LI CLASS="c2">
86 <A NAME="7138"></A>
87 </LI>
88 <LI>
89 A short-lived application pays start up overhead on every request; a long-lived application spreads the
90 overhead over many requests. For an application that has a heavy start up cost, such as opening a database,
91 doing initialization on every call can be very inefficient. Reinitializing for every client is also very
92 inefficient for Perl programs, where the interpreter reads through the entire program before executing any
93 of it. <A NAME="9204"></A>
94 </LI>
95 <LI>
96 A long-lived application can cache information in memory between requests, allowing it to respond more
97 quickly to later requests.
98 </LI>
99 </UL>
100 <A NAME="8733"></A>
101 <P>
102 FastCGI is not the only way to get a long-lived application on the Web, however. For example, there are many
103 existing search engines that are implemented as long-lived applications.
104 </P>
105 <P>
106 <A NAME="8734"></A> In most cases, these applications rely on customized Web servers. In other words, since
107 most Web servers do not support long-lived applications, a programmer must code this support into a Web
108 server. This approach requires a tremendous amount of work and also ties the application to a particular
109 server.
110 </P>
111 <P>
112 <A NAME="8735"></A> Another way to get a long-lived application is to write code that calls routines from the
113 Web server&#39;s API. This alternative involves a lot of extra coding, ties the application to a particular
114 Web server, and introduces problems of maintainability, scalability, and security.
115 </P>
116 <P>
117 <A NAME="8736"></A> We believe that FastCGI is the most general and flexible strategy for building long-lived
118 Web applications.
119 </P>
120 <BR>
121 <BR>
122 <H2>
123 Separating Application and Server
124 </H2>
125 <A NAME="8446"></A>
126 <P>
127 CGI applications must run on the same node as the Web server; FastCGI applications can run on any node that
128 can be reached from your Web server using TCP/IP protocols. For example, you might want to run the FastCGI
129 application on a high-speed computer server or database engine, and run the Web server on a different node.
130 </P>
131 <BR>
132 <BR>
133 <H2>
134 FastCGI &quot;Roles&quot;
135 </H2>
136 <A NAME="8777"></A>
137 <P>
138 CGI and FastCGI applications are effective ways to allow an application to act as an extension to the Web
139 server. CGI provides no explicit support for different kinds of applications: under CGI, every application
140 receives an HTTP request, does something with it, and generates an HTTP response. FastCGI provides explicit
141 support for several common &quot;roles&quot; that applications can play.
142 </P>
143 <P>
144 <A NAME="8769"></A> The three roles supported by the WebServer 2.0 are:
145 </P>
146 <BR>
147 <BR>
148 <UL>
149 <LI CLASS="c2">
150 <A NAME="8409"></A>
151 </LI>
152 <LI>
153 Responder <A NAME="8410"></A>
154 </LI>
155 <LI>
156 Filter <A NAME="8411"></A>
157 </LI>
158 <LI>
159 Authorizer
160 </LI>
161 </UL>
162 <H3>
163 Responder Applications
164 </H3>
165 <A NAME="8679"></A>
166 <P>
167 A <EM>responder</EM> application is the most basic kind of FastCGI application: it receives the information
168 associated with an HTTP request and generates an HTTP response. Responder is the role most similar to
169 traditional CGI programming, and most FastCGI applications are responders.
170 </P>
171 <BR>
172 <BR>
173 <H3>
174 Filter Applications
175 </H3>
176 <A NAME="8681"></A>
177 <P>
178 A <EM>filter</EM> FastCGI application receives the information associated with an HTTP request, plus an extra
179 stream of data from a file stored on the Web server, and generates a &quot;filtered&quot; version of the data
180 stream as an HTTP response.
181 </P>
182 <P>
183 <A NAME="8421"></A> With filter applications, the system administrator maps a particular MIME-type to a
184 particular filter FastCGI application. When a client requests a URL with that MIME-type, the Web server
185 invokes the filter application, which processes the file at the specified URL and sends a response (usually
186 HTML text) back to the client.
187 </P>
188 <P>
189 <A NAME="8422"></A> For example, suppose you write a filter FastCGI application that converts SGML text to
190 HTML, and map the extension .sgml (MIME-type SGML) to your filter FastCGI application. Now, suppose that a
191 user requests the following URL:
192 </P>
193 <BR>
194 <BR>
195 <PRE>
196 <A NAME="8423">/www.aerjug.com/docs/chap1.sgml
197 </A>
198 </PRE>
199 <A NAME="8424"></A>
200 <P>
201 Given this URL, the Web server passes <CODE>chap1.sgml</CODE> as input to your filter FastCGI application,
202 which processes <CODE>chap1.sgml</CODE> and returns an HTML version of it to the requesting client.
203 </P>
204 <BR>
205 <BR>
206 <H3>
207 Authorizer Applications
208 </H3>
209 <A NAME="8426"></A>
210 <P>
211 An <EM>authorizer</EM> FastCGI application receives the information in an HTTP request header and generates a
212 decision whether to authorize the request.
213 </P>
214 <P>
215 <A NAME="8428"></A> To mark a FastCGI application as having the authorizer role, the system administrator
216 names the application inside the server configuration file, using a directive called
217 <CODE>AuthorizeRegion</CODE>. (See the Open Market Web Server manual for information on server configuration
218 directives.)
219 </P>
220 <P>
221 <A NAME="8429"></A> When a client requests a URL that meets the <CODE>AuthorizeRegion</CODE> criteria, the Web
222 server calls your authorizer FastCGI application. If your application grants authorization (by returning a
223 response code of 200), the Web server resumes execution of commands in the <CODE>AuthorizeRegion</CODE>
224 section. If your application denies authorization (by returning any other response code), the Web server stops
225 processing subsequent commands in the <CODE>AuthorizeRegion</CODE> section, and returns the response from your
226 FastCGI application to the client.
227 </P>
228 <P>
229 <A NAME="8431"></A> Authorizer applications can return headers containing environment variables. Other CGI or
230 FastCGI programs accessing this request (including other authorizers) can access these environment variables.
231 The headers must have the following format:
232 </P>
233 <BR>
234 <BR>
235 <PRE>
236 <A NAME="8432">Variable-<EM>name</EM>: <EM>value</EM>
237 </A>
238 </PRE>
239 <A NAME="8433"></A>
240 <P>
241 For example, the following header
242 </P>
243 <BR>
244 <BR>
245 <PRE>
246 <A NAME="8434">Variable-AUTH_METHOD: database lookup
247 </A>
248 </PRE>
249 <A NAME="8435"></A>
250 <P>
251 causes the environment variable <CODE>AUTH_METHOD</CODE> to be set to <CODE>&quot;database lookup&quot;</CODE>
252 for this request. Other CGI or FastCGI applications running on this request can access the value of
253 <CODE>AUTH_METHOD</CODE>.
254 </P>
255 <P>
256 <A NAME="8437"></A> Authorizer applications cannot successfully read from standard input. Any attempts to read
257 from standard input result in an immediate EOF.
258 </P>
259 <P>
260 <A NAME="8438"></A> All data that authorizer applications write to standard error will get written to the
261 traditional server error logs.
262 </P>
263 <BR>
264 <BR>
265 <H1>
266 Writing FastCGI Applications
267 </H1>
268 <A NAME="9301"></A>
269 <P>
270 The work involved in writing a FastCGI application depends in large part on the I/O libraries that you use.
271 This manual describes how to write FastCGI applications in terms of the Open Market libraries, which are
272 available for C, Perl, and Tcl. FastCGI is an open standard and you are welcome to build your own libraries
273 for other languages as well, but this manual focuses on building FastCGI applications in the context of the
274 Open Market libraries.
275 </P>
276 <P>
277 <A NAME="9443"></A>
278 </P>
279 <P>
280 <A NAME="9450"></A> In general, the goal of the libraries is to make the job of writing a FastCGI application
281 as much like writing a CGI application as possible. For example, you use the same techniques for query string
282 decoding, HTML output to stdout, use of environment variables, and so on. When you use our libraries, porting
283 CGI applications to FastCGI is mostly a matter of restructuring the code to take advantage of FastCGI features
284 and libraries.
285 </P>
286 <BR>
287 <BR>
288 <H2>
289 Code Structure
290 </H2>
291 <A NAME="9470"></A>
292 <P>
293 The main task of converting a CGI program into a FastCGI program is separating the initialization code from
294 the code that needs to run for each request. The structure should look something like this:
295 </P>
296 <BR>
297 <BR>
298 <PRE>
299 <A NAME="9471">Initialization code
300 </A>
301 <A NAME="9472">Start of response loop
302 </A>
303 <A NAME="9473"> body of response loop
304 </A>
305 <A NAME="9474">End of response loop
306 </A>
307 </PRE>
308 <A NAME="9475"></A>
309 <P>
310 The <EM>initialization code</EM> is run exactly once, when the application is initialized. Initialization code
311 usually performs time-consuming operations such as opening databases or calculating values for tables or
312 bitmaps.
313 </P>
314 <P>
315 <A NAME="9477"></A> The <EM>response loop</EM> runs continuously, waiting for client requests to arrive. The
316 loop starts with a call to <CODE>FCGI_Accept</CODE>, a routine in the FastCGI library. The
317 <CODE>FCGI_Accept</CODE> routine blocks program execution until a client requests the FastCGI application.
318 When a client request comes in, <CODE>FCGI_Accept</CODE> unblocks, runs one iteration of the response loop
319 body, and then blocks again waiting for another client request. The loop terminates only when the system
320 administrator or the Web server kills the FastCGI application.
321 </P>
322 <BR>
323 <BR>
324 <H2>
325 Initial Environment Variables
326 </H2>
327 <A NAME="9786"></A>
328 <P>
329 When a FastCGI process starts up, it has not yet accepted a request, and therefore none of the CGI environment
330 variables are set.
331 </P>
332 <P>
333 <A NAME="9787"></A> You set the initial environment of a FastCGI process started by the <CODE>AppClass</CODE>
334 directive using the <CODE>-initial-env</CODE> option. The process would use this environment to configure its
335 options and locate files or databases.
336 </P>
337 <P>
338 <A NAME="9829"></A> In FastCGI processes started by the <CODE>AppClass</CODE> directive with the -affinity
339 option, the <CODE>FCGI_PROCESS_ID</CODE> variable is set in the initial environment (not in the environment of
340 a request). <CODE>FCGI_PROCESS_ID</CODE> is a decimal number in the range 0 to N - 1 where N is the number of
341 processes (argument to the <CODE>-processes</CODE> option to <CODE>AppClass</CODE>). The process would use
342 <CODE>FCGI_PROCESS_ID</CODE> in conjunction with other variables to locate session-related files or databases
343 during restart.
344 </P>
345 <BR>
346 <BR>
347 <H2>
348 Per-Request Environment Variables
349 </H2>
350 <A NAME="9481"></A>
351 <P>
352 In general, FastCGI uses the same per-request environment variables as CGI, and you access the values of
353 environment variables in FastCGI applications just as you would in CGI applications. The only differences are
354 as follows:
355 </P>
356 <BR>
357 <BR>
358 <UL>
359 <LI CLASS="c2">
360 <A NAME="9483"></A>
361 </LI>
362 <LI>
363 In Authorizer FastCGI applications, the Web server unsets the <CODE>PATH_INFO</CODE>,
364 <CODE>PATH_TRANSLATED</CODE>, and <CODE>CONTENT_LENGTH</CODE> variables. <A NAME="9484"></A>
365 </LI>
366 <LI>
367 In Filter FastCGI applications, the Web server sets two additional environment variables:
368 <UL>
369 <LI CLASS="c2">
370 <A NAME="9486"></A>
371 </LI>
372 <LI>
373 <CODE>FILE_LAST_MOD</CODE>: The Web server sets <CODE>FILE_LAST_MOD</CODE> to the date and time that
374 filter input file was last modified. The format is the number of seconds since midnight (UTC),
375 January 1, 1970. <A NAME="9488"></A>
376 </LI>
377 <LI>
378 <CODE>FCGI_DATA_LENGTH</CODE>: The application reads at most <CODE>FCGI_DATA_LENGTH</CODE> bytes from
379 the data stream before receiving the end-of-stream indication.
380 </LI>
381 </UL>
382 <A NAME="9490"></A>
383 </LI>
384 <LI>
385 FastCGI sets <CODE>FCGI_ROLE</CODE> for each request to <CODE>RESPONDER</CODE>, <CODE>AUTHORIZER</CODE>, or
386 <CODE>FILTER</CODE>.
387 </LI>
388 </UL>
389 <H2>
390 Building FastCGI Applications in C
391 </H2>
392 <A NAME="9049"></A>
393 <P>
394 The Software Development Toolkit that accompanies WebServer 2.0 contains two libraries, fcgi_stdio and
395 fcgiapp, for building FastCGI applications in C.
396 </P>
397 <P>
398 <A NAME="9723"></A> The fcgi_stdio library implements our philosophy of making FastCGI applications similar to
399 CGI applications, and provides full binary compatibility between FastCGI applications and CGI applications:
400 you can run the same C binary as either CGI or FastCGI.
401 </P>
402 <P>
403 <A NAME="9545"></A> The fcgiapp library is more specific to FastCGI, and doesn&#39;t attempt the veneer of
404 CGI.
405 </P>
406 <P>
407 <A NAME="9731"></A> We recommend that you use the fcgi_stdio library, and this manual describes the routines
408 in that library. The documentation for the fcgiapp library is in the code in the development kit.
409 </P>
410 <BR>
411 <BR>
412 <H2>
413 Building FastCGI Applications in Perl
414 </H2>
415 <A NAME="9581"></A>
416 <P>
417 To build FastCGI applications in Perl, you need a FastCGI-savvy version of Perl, plus the FastCGI extension to
418 Perl. We build FastCGI-savvy versions of the Perl interpreter for several common platforms and make them
419 available on our Website. For details and examples, see Chapter <A HREF="ch3perl.htm#3659">3, &quot;Developing
420 FastCGI Applications in Perl,&quot; on page 17</A>.
421 </P>
422 <BR>
423 <BR>
424 <H2>
425 Building FastCGI Applications in Tcl
426 </H2>
427 <A NAME="9586"></A>
428 <P>
429 To build FastCGI applications in Tcl, you need a FastCGI-savvy version of Tcl. We build FastCGI-savvy versions
430 of the Tcl interpreter for several common platforms and make them available on our Website. For details and
431 examples, see Chapter <A HREF="ch4tcl.htm#3659">4, &quot;Developing FastCGI Applications in Tcl,&quot; on page
432 19</A>.
433 </P>
434 <BR>
435 <BR>
436 <H1>
437 Implementation Details
438 </H1>
439 <A NAME="8066"></A>
440 <P>
441 The FastCGI application libraries are designed to shield you from the details of the FastCGI design. This
442 section is designed for the curious reader who would like some low-level understanding. If you are not curious
443 about the implementation, you can happily skip this section.
444 </P>
445 <P>
446 <A NAME="8554"></A> As shown in the following figure, CGI applications use the three standard POSIX streams
447 (<CODE>stdin</CODE>, <CODE>stdout</CODE>, and <CODE>stderr</CODE>), plus environment variables, to communicate
448 with an HTTP server.
449 </P>
450 <P>
451 <A NAME="8359"></A> <IMG ALT="error-file:TidyOut.log" SRC="ch1intra.gif">
452 </P>
453 <P>
454 <A NAME="4295"></A>
455 </P>
456 <BR>
457 <BR>
458 <H5>
459 Figure 1: Flow of Data in CGI
460 </H5>
461 <A NAME="9001"></A>
462 <P>
463 The fundamental difference between FastCGI and CGI is that FastCGI applications are long-lived, which means
464 that the Web Server needs to rendezvous with a running application, rather than starting the application in
465 order to explicitly communicate with it.
466 </P>
467 <P>
468 <A NAME="9110"></A> The FastCGI implementation basically creates a bidirectional connection between two
469 processes that have no relationship. FastCGI uses a single connection for all the data associated with an
470 application -- stdin, stdout, stderr, and environment variables. The data on the connection is encapsulated
471 using a FastCGI protocol that allows stdin and the environment variables to share the same half connection (on
472 the way in) and stdout and stderr to share the half connection (on the way out).
473 </P>
474 <P>
475 <A NAME="9020"></A> On the input side, the FastCGI application receives data on the connection, unpacks it to
476 separate stdin from the environment variables and then invokes the application. On the output side, FastCGI
477 wraps stdout and stderr with appropriate protocol headers, and sends the encapsulated data out to the server.
478 </P>
479 <P>
480 <A NAME="9032"></A> Since a FastCGI application does not always run on the same node as the HTTP server, we
481 support two implementations of the connection: a <EM>stream pipe</EM><A HREF="#9645"><SUP>1</SUP></A>, for
482 communications on the same machine, and TCP streams, for communication when the client and the server are on
483 different machines.
484 </P>
485 <P>
486 <A NAME="8576"></A> <IMG ALT="error-file:TidyOut.log" SRC="ch1inta1.gif">
487 </P>
488 <BR>
489 <BR>
490 <H5>
491 Figure 2: Flow of Data in FastCGI when server and application are on different machines
492 </H5>
493 <H2>
494 The fcgi_stdio Library: I/O Compatibility
495 </H2>
496 <A NAME="8977"></A>
497 <P>
498 The implementation for I/O compatibility is that the library <CODE>fcgi_stdio.h</CODE> contains macros to
499 translate the types and procedures defined in stdio.h into the appropriate FastCGI calls. For example,
500 consider a FastCGI program written in C containing the following line of code:
501 </P>
502 <BR>
503 <BR>
504 <PRE>
505 <A NAME="5877">fprintf(stdout, &quot;&lt;H2&gt;Aerobic Juggling&lt;/H2&gt;/n&quot;);
506 </A>
507 </PRE>
508 <A NAME="9659"></A> <CODE>fcgi_stdio.h</CODE>
509 <P>
510 header file contains the macro
511 </P>
512 <BR>
513 <BR>
514 <PRE>
515 <A NAME="6403">#define fprintf FCGI_fprintf
516 </A>
517 </PRE>
518 <A NAME="6402"></A>
519 <P>
520 So the preprocessor translates the <CODE>fprintf</CODE> call into the following call:
521 </P>
522 <BR>
523 <BR>
524 <PRE>
525 <A NAME="6411">FCGI_fprintf(stdout, &quot;&lt;H2&gt;Aerobic Juggling&lt;/H2&gt;/n&quot;);
526 </A>
527 </PRE>
528 <A NAME="5888"></A> <CODE>FCGI_fprintf</CODE>
529 <P>
530 takes the same arguments as <CODE>fprintf</CODE>.
531 </P>
532 <P>
533 <A NAME="9664"></A> The implementation of FCGI_fprintf tests the file to see if it is a normal C stream or a
534 FastCGI stream, and calls the appropriate implementation.
535 </P>
536 <P>
537 <A NAME="6463"></A> The <CODE>fcgi_stdio.h</CODE> header file contains macros to translate calls to all ISO
538 stdio.h routines (and all conventional Posix additions, such as <CODE>fileno</CODE>, <CODE>fdopen</CODE>,
539 <CODE>popen</CODE>, and <CODE>pclose</CODE>) into their FastCGI equivalents.
540 </P>
541 <BR>
542 <BR>
543 <H2>
544 The fcgi_stdio Library: Binary compatibility
545 </H2>
546 <A NAME="9579"></A>
547 <P>
548 The fcgi_stdio library provides full binary compatibility between FastCGI applications and CGI applications:
549 you can run the same C binary as either CGI or FastCGI.
550 </P>
551 <P>
552 <A NAME="9580"></A> The implementation is in FCGI_Accept: the FCGI_Accept function tests its environment to
553 determine whether the application was invoked as a CGI program or an FastCGI program. If it was invoked as a
554 CGI program, the request loop will satisfy a single client request and then exit, producing CGI behavior.
555 </P>
556 <P>
557 <A NAME="8957"></A>
558 </P>
559 <P>
560 </P>
561 <HR>
562 <BR>
563 <A HREF="cover.htm">[Top]</A> <A HREF="ap_guide.htm">[Prev]</A> <A HREF="ch2c.htm">[Next]</A> <A HREF=
564 "ap_guida.htm">[Bottom]</A>
565 <HR>
566 <BR>
567 <SUP>1</SUP><A NAME="9645"></A>
568 <P>
569 UNIX Network Programming, W. Richard Stevens, 1990 Prentice-Hall, Section 7.9
570 </P>
571 <P>
572 <!-- This file was created with Quadralay WebWorks Publisher 3.0.3 -->
573 <!-- -->
574 <!-- For more information on how this document, and how the rest of -->
575 <!-- this server was created, email [email protected] -->
576 <!-- -->
577 <!-- Last updated: 04/15/96 08:00:13 -->
578 </P>
579 </BODY>
580 </HTML>
581