[catagits/fcgi2.git] / doc / www5-api-workshop.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
   <HEAD>
      <TITLE>
         FastCGI: A High-Performance Gateway Interface
      </TITLE>
<STYLE TYPE="text/css">
 h5.c2 {text-align: center}
 div.c1 {text-align: center}
</STYLE>
   </HEAD>
   <BODY>
      <DIV CLASS="c1">
         <H2>
            FastCGI: A High-Performance Gateway Interface
         </H2>
         Position paper for the workshop &quot;Programming the Web - a search for APIs&quot;,<BR>
         Fifth International World Wide Web Conference, 6 May 1996, Paris, France.<BR>
         <P>
            Mark R. Brown<BR>
            Open Market, Inc.<BR>
         </P>
         <P>
            2 May 1996<BR>
         </P>
      </DIV>
      <P>
      </P>
      <H5 CLASS="c2">
         Copyright &copy; 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>
      </H5>
      <HR>
      <H3>
         Abstract
      </H3>
      <P>
         FastCGI is a fast, open, and secure Web server interface that solves the performance problems inherent in CGI
         without introducing any of the new problems associated with writing applications to lower-level Web server
         APIs. Modules to support FastCGI can be plugged into Web server APIs such as Apache API, NSAPI, and ISAPI. Key
         considerations in designing FastCGI included minimizing the cost of migrating CGI applications (including
         applications written in popular scripting languages such as Perl), supporting both single-threaded and
         multi-threaded application programming, supporting distributed configurations for scaling and high
         availability, and generalizing the roles that gateway applications can play beyond CGI&#39;s
         &quot;responder&quot; role.
      </P>
      <P>
         For more information on FastCGI, including an interface specification and a module for the Apache server,
         visit the <A HREF="http://www.fastcgi.com/">www.fastcgi.com Web site</A>.
      </P>
      <H3>
         1. Introduction
      </H3>
      <P>
         The surge in the use of the Web by business has created great demand for applications that create dynamic
         content. These applications allow businesses to deliver products, services, and messages whose shape and
         content are influenced by interaction with and knowledge of users.
      </P>
      <P>
         This move towards dynamic Web content has highlighted the performance limits of CGI (Common Gateway
         Interface). In response there has been a proliferation of Web server APIs. These APIs address some (though not
         all) of the performance problems with CGI, but are not designed to meet the need of business applications.
         When applied to business applications, Web server APIs suffer from these problems:
      </P>
      <UL>
         <LI>
            <B>Complexity.</B> Server APIs introduce a steep learning curve, with increased implementation and
            maintenance costs.
         </LI>
         <LI>
            <B>Language dependence.</B> Applications have to be written in a language supported by the server API
            (usually C/C++). Perl, the most popular language for CGI programs, can&#39;t be used with any existing
            server API.
         </LI>
         <LI>
            <B>No process isolation.</B> Since the applications run in the server&#39;s address space, buggy
            applications can corrupt the core server (or each other). A malicious or buggy application can compromise
            server security, and bugs in the core server can corrupt applications.
         </LI>
         <LI>
            <B>Proprietary.</B> Coding your application to a particular API locks you into a particular server.
         </LI>
         <LI>
            <B>Tie-in to server architecture.</B> API applications have to share the same architecture as the server:
            If the Web server is multi-threaded, the application has to be thread-safe. If the Web server has
            single-threaded processes, multi-threaded applications don&#39;t gain any performance advantage. Also, when
            the server&#39;s architecture changes, the API will usually have to change, and applications will have to
            be adapted or rewritten.
         </LI>
      </UL>
      <P>
         Web server APIs are suitable for applications that require an intimate connection to the core Web server, such
         as security protocols. But using a Web server API for a Web business application would be much like using an
         old-fashioned TP monitor, which required linking applications right into the monitor, for a modern business
         transaction processing application. The old-fashioned solution suffers a huge development and maintenance cost
         penalty because it ignores 30 years of progress in computing technology, and may end up providing inferior
         performance to boot. Nobody uses the old technology unless they are already locked into it.
      </P>
      <P>
         FastCGI is best viewed as a new implementation of CGI, designed to overcome CGI&#39;s performance problems.
         The major implementation differences are:
      </P>
      <UL>
         <LI>
            FastCGI processes are persistent: after finishing a request, they wait for a new request instead of
            exiting.
         </LI>
         <LI>
            Instead of using operating system environment variables and pipes, the FastCGI protocol multiplexes the
            environment information, standard input, output, and error over a single full-duplex connection. This
            allows FastCGI programs to run on remote machines, using TCP connections between the Web server and the
            FastCGI application.
         </LI>
      </UL>
      <P>
         FastCGI communicates the exact same information as CGI in a different way. Because FastCGI <I>is</I> CGI, and
         like CGI runs applications in separate processes, it suffers none of the server API problems listed above.
      </P>
      <H3>
         2. Migration from CGI
      </H3>
      <P>
         Open Market has developed a FastCGI application library that implements the FastCGI protocol, hiding the
         protocol details from the developer. This library, which is freely available, makes writing FastCGI programs
         as easy as writing CGI applications.
      </P>
      <P>
         The application library provides replacements for the C language standard I/O (stdio) routines such as
         <TT>printf()</TT> and <TT>gets()</TT>. The library converts references to environment variables, standard
         input, standard output, and standard error to the FastCGI protocol. References to other files &quot;fall
         through&quot; to the underlying operating system standard I/O routines. This approach has several benefits:
      </P>
      <UL>
         <LI>
            Developers don&#39;t have to learn a new API to develop FastCGI applications.
         </LI>
         <LI>
            Existing CGI programs can be migrated with minimal source changes.
         </LI>
         <LI>
            FastCGI interpreters for Perl, Tcl, and other interpreted languages can be built without modifying the
            interpreter source code.
         </LI>
      </UL>
      <P>
         Here&#39;s a simple FastCGI application:
      </P>
      <BR>
      <BR>
<PRE>
    #include &lt;fcgi_stdio.h&gt;

    void main(void)
    {
        int count = 0;
        while(FCGI_Accept() &gt;= 0) {
            printf(&quot;Content-type: text/html\r\n&quot;);
            printf(&quot;\r\n&quot;);
            printf(&quot;Hello world!&lt;br&gt;\r\n&quot;);
            printf(&quot;Request number %d.&quot;, count++);
        }
        exit(0);
    }
</PRE>
      <P>
         This application returns a &quot;Hello world&quot; HTML response to the client. It also keeps a counter of the
         number of times it has been accessed, displaying the value of the counter at each request. The
         <TT>fcgi_stdio.h</TT> header file provides the FastCGI replacement routines for the C standard I/O library.
         The <TT>FCGI_Accept()</TT> routine accepts a new request from the Web server.
      </P>
      <P>
         The application library was designed to make migration of existing CGI programs as simple as possible. Many
         applications can be converted by adding a loop around the main request processing code and recompiling with
         the FastCGI application library. To ease migration to FastCGI, executables built with the application library
         can run as either CGI or FastCGI programs, depending on how they are invoked. The library detects the
         execution environment and automatically selects FastCGI or regular I/O routines, as appropriate.
      </P>
      <P>
         Applications written in Perl, Tcl, and other scripting languages can be migrated by using a language
         interpreter built with the application library. FastCGI-integrated Tcl and Perl interpreters for popular Unix
         platforms are available from the <I>www.fastcgi.com</I> Web site. The interpreters are backward-compatible:
         They can run standard Tcl and Perl applications.
      </P>
      <H3>
         3. Single-threaded and multi-threaded applications
      </H3>
      <P>
         FastCGI gives developers a free choice of whether to develop applications in a single-threaded or
         multi-threaded style. The FastCGI interface supports multi-threading in two ways:
      </P>
      <UL>
         <LI>
            Applications can accept concurrent Web server connections to provide concurrent requests to multiple
            application threads.
         </LI>
         <LI>
            Applications can accept multiplexed Web server connections, in which concurrent requests are communicated
            over a single connection to multiple application threads.
         </LI>
      </UL>
      <P>
         Multi-threaded programming is complex -- concurrency makes programs difficult to test and debug -- so many
         developers will prefer to program in the familiar single-threaded style. By having several concurrent
         processes running the same application it is often possible to achieve high performance with single-threaded
         programming.
      </P>
      <P>
         The FastCGI interface allows Web servers to implement <I>session affinity</I>, a feature that allows
         applications to maintain caches of user-related data. With session affinity, when several concurrent processes
         are running the same application, the Web server routes all requests from a particular user to the same
         application process. Web server APIs don&#39;t provide this functionality to single-threaded applications, so
         the performance of an API-based application is often inferior to the performance of the corresponding FastCGI
         application.
      </P>
      <H3>
         4. Distributed FastCGI
      </H3>
      <P>
         Because FastCGI can communicate over TCP/IP connections, it supports configurations in which applications run
         remotely from the Web server. This can provide scaling, load balancing, high availability, and connections to
         systems that don&#39;t have Web servers.
      </P>
      <P>
         Distributed FastCGI can also provide security advantages. A Web server outside a corporate firewall can
         communicate through the firewall to internal databases. For instance, an application might need to
         authenticate incoming users as customers in order to give access to certain documents on the external Web
         site. With FastCGI this authentication can be done without replicating data and without compromising security.
      </P>
      <H3>
         5. Roles
      </H3>
      <P>
         A problem with CGI is its limited functionality: CGI programs can only provide responses to requests. FastCGI
         provides expanded functionality with support for three different application &quot;roles&quot;:
      </P>
      <UL>
         <LI>
            <B>Responder.</B> This is the basic FastCGI role, and corresponds to the simple functionality offered by
            CGI today.
         </LI>
         <LI>
            <B>Filter.</B> The FastCGI application filters the requested Web server file before sending it to the
            client.
         </LI>
         <LI>
            <B>Authorizer.</B> The FastCGI program performs an access control decision for the request (such as
            performing a username/password database lookup).
         </LI>
      </UL>
      <P>
         Other roles will be defined in the future. For instance, a &quot;logger&quot; role would be useful, where the
         FastCGI program would receive the server&#39;s log entries for real-time processing and analysis.
      </P>
      <H3>
         6. Conclusions
      </H3>
      <P>
         Today&#39;s Web business applications need a platform that&#39;s fast, open, maintainable, straightforward,
         stable, and secure. FastCGI&#39;s design meets these requirements, and provides a logical migration path from
         the proven and widely deployed CGI technology. This allows developers to take advantage of FastCGI&#39;s
         benefits without losing their existing investment in CGI applications.
      </P>
      <P>
         For more information about FastCGI, visit the <A HREF="http://www.fastcgi.com/">www.fastcgi.com Web site</A>.
      </P>
   </BODY>
</HTML>
Commit	Line	Data
852467e2	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
	2	<HTML>
	3	<HEAD>
	4	<TITLE>
	5	FastCGI: A High-Performance Gateway Interface
	6	</TITLE>
	7	<STYLE TYPE="text/css">
	8	h5.c2 {text-align: center}
	9	div.c1 {text-align: center}
	10	</STYLE>
	11	</HEAD>
	12	<BODY>
	13	<DIV CLASS="c1">
	14	<H2>
	15	FastCGI: A High-Performance Gateway Interface
	16	</H2>
	17	Position paper for the workshop "Programming the Web - a search for APIs",<BR>
	18	Fifth International World Wide Web Conference, 6 May 1996, Paris, France.<BR>
	19	<P>
	20	Mark R. Brown<BR>
	21	Open Market, Inc.<BR>
	22	</P>
	23	<P>
	24	2 May 1996<BR>
	25	</P>
	26	</DIV>
	27	<P>
	28	</P>
	29	<H5 CLASS="c2">
	30	Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge, MA 02142 U.S.A.<BR>
	31	Tel: 617-621-9500 Fax: 617-621-1703 URL: <A HREF=
	32	"http://www.openmarket.com/">http://www.openmarket.com/</A><BR>
	33	</H5>
	34	<HR>
	35	<H3>
	36	Abstract
	37	</H3>
	38	<P>
	39	FastCGI is a fast, open, and secure Web server interface that solves the performance problems inherent in CGI
	40	without introducing any of the new problems associated with writing applications to lower-level Web server
	41	APIs. Modules to support FastCGI can be plugged into Web server APIs such as Apache API, NSAPI, and ISAPI. Key
	42	considerations in designing FastCGI included minimizing the cost of migrating CGI applications (including
	43	applications written in popular scripting languages such as Perl), supporting both single-threaded and
	44	multi-threaded application programming, supporting distributed configurations for scaling and high
	45	availability, and generalizing the roles that gateway applications can play beyond CGI's
	46	"responder" role.
	47	</P>
	48	<P>
	49	For more information on FastCGI, including an interface specification and a module for the Apache server,
	50	visit the <A HREF="http://www.fastcgi.com/">www.fastcgi.com Web site</A>.
	51	</P>
	52	<H3>
	53	1. Introduction
	54	</H3>
	55	<P>
	56	The surge in the use of the Web by business has created great demand for applications that create dynamic
	57	content. These applications allow businesses to deliver products, services, and messages whose shape and
	58	content are influenced by interaction with and knowledge of users.
	59	</P>
	60	<P>
	61	This move towards dynamic Web content has highlighted the performance limits of CGI (Common Gateway
	62	Interface). In response there has been a proliferation of Web server APIs. These APIs address some (though not
	63	all) of the performance problems with CGI, but are not designed to meet the need of business applications.
	64	When applied to business applications, Web server APIs suffer from these problems:
65	</P>
66	<UL>
67	<LI>
68	<B>Complexity.</B> Server APIs introduce a steep learning curve, with increased implementation and
69	maintenance costs.
70	</LI>
71	<LI>
72	<B>Language dependence.</B> Applications have to be written in a language supported by the server API
73	(usually C/C++). Perl, the most popular language for CGI programs, can't be used with any existing
74	server API.
75	</LI>
76	<LI>
77	<B>No process isolation.</B> Since the applications run in the server's address space, buggy
78	applications can corrupt the core server (or each other). A malicious or buggy application can compromise
79	server security, and bugs in the core server can corrupt applications.
80	</LI>
81	<LI>
82	<B>Proprietary.</B> Coding your application to a particular API locks you into a particular server.
83	</LI>
84	<LI>
85	<B>Tie-in to server architecture.</B> API applications have to share the same architecture as the server:
86	If the Web server is multi-threaded, the application has to be thread-safe. If the Web server has
87	single-threaded processes, multi-threaded applications don't gain any performance advantage. Also, when
88	the server's architecture changes, the API will usually have to change, and applications will have to
89	be adapted or rewritten.
90	</LI>
91	</UL>
92	<P>
93	Web server APIs are suitable for applications that require an intimate connection to the core Web server, such
94	as security protocols. But using a Web server API for a Web business application would be much like using an
95	old-fashioned TP monitor, which required linking applications right into the monitor, for a modern business
96	transaction processing application. The old-fashioned solution suffers a huge development and maintenance cost
97	penalty because it ignores 30 years of progress in computing technology, and may end up providing inferior
98	performance to boot. Nobody uses the old technology unless they are already locked into it.
99	</P>
100	<P>
101	FastCGI is best viewed as a new implementation of CGI, designed to overcome CGI's performance problems.
102	The major implementation differences are:
103	</P>
104	<UL>
105	<LI>
106	FastCGI processes are persistent: after finishing a request, they wait for a new request instead of
107	exiting.
108	</LI>
109	<LI>
110	Instead of using operating system environment variables and pipes, the FastCGI protocol multiplexes the
111	environment information, standard input, output, and error over a single full-duplex connection. This
112	allows FastCGI programs to run on remote machines, using TCP connections between the Web server and the
113	FastCGI application.
114	</LI>
115	</UL>
116	<P>
117	FastCGI communicates the exact same information as CGI in a different way. Because FastCGI <I>is</I> CGI, and
118	like CGI runs applications in separate processes, it suffers none of the server API problems listed above.
119	</P>
120	<H3>
121	2. Migration from CGI
122	</H3>
123	<P>
124	Open Market has developed a FastCGI application library that implements the FastCGI protocol, hiding the
125	protocol details from the developer. This library, which is freely available, makes writing FastCGI programs
126	as easy as writing CGI applications.
127	</P>
128	<P>
129	The application library provides replacements for the C language standard I/O (stdio) routines such as
130	<TT>printf()</TT> and <TT>gets()</TT>. The library converts references to environment variables, standard
131	input, standard output, and standard error to the FastCGI protocol. References to other files "fall
132	through" to the underlying operating system standard I/O routines. This approach has several benefits:
133	</P>
134	<UL>
135	<LI>
136	Developers don't have to learn a new API to develop FastCGI applications.
137	</LI>
138	<LI>
139	Existing CGI programs can be migrated with minimal source changes.
140	</LI>
141	<LI>
142	FastCGI interpreters for Perl, Tcl, and other interpreted languages can be built without modifying the
143	interpreter source code.
144	</LI>
145	</UL>
146	<P>
147	Here's a simple FastCGI application:
148	</P>
149	<BR>
150	<BR>
151	<PRE>
152	#include <fcgi_stdio.h>
153
154	void main(void)
155	{
156	int count = 0;
157	while(FCGI_Accept() >= 0) {
158	printf("Content-type: text/html\r\n");
159	printf("\r\n");
160	printf("Hello world!<br>\r\n");
161	printf("Request number %d.", count++);
162	}
163	exit(0);
164	}
165	</PRE>
166	<P>
167	This application returns a "Hello world" HTML response to the client. It also keeps a counter of the
168	number of times it has been accessed, displaying the value of the counter at each request. The
169	<TT>fcgi_stdio.h</TT> header file provides the FastCGI replacement routines for the C standard I/O library.
170	The <TT>FCGI_Accept()</TT> routine accepts a new request from the Web server.
171	</P>
172	<P>
173	The application library was designed to make migration of existing CGI programs as simple as possible. Many
174	applications can be converted by adding a loop around the main request processing code and recompiling with
175	the FastCGI application library. To ease migration to FastCGI, executables built with the application library
176	can run as either CGI or FastCGI programs, depending on how they are invoked. The library detects the
177	execution environment and automatically selects FastCGI or regular I/O routines, as appropriate.
178	</P>
179	<P>
180	Applications written in Perl, Tcl, and other scripting languages can be migrated by using a language
181	interpreter built with the application library. FastCGI-integrated Tcl and Perl interpreters for popular Unix
182	platforms are available from the <I>www.fastcgi.com</I> Web site. The interpreters are backward-compatible:
183	They can run standard Tcl and Perl applications.
184	</P>
185	<H3>
186	3. Single-threaded and multi-threaded applications
187	</H3>
188	<P>
189	FastCGI gives developers a free choice of whether to develop applications in a single-threaded or
190	multi-threaded style. The FastCGI interface supports multi-threading in two ways:
191	</P>
192	<UL>
193	<LI>
194	Applications can accept concurrent Web server connections to provide concurrent requests to multiple
195	application threads.
196	</LI>
197	<LI>
198	Applications can accept multiplexed Web server connections, in which concurrent requests are communicated
199	over a single connection to multiple application threads.
200	</LI>
201	</UL>
202	<P>
203	Multi-threaded programming is complex -- concurrency makes programs difficult to test and debug -- so many
204	developers will prefer to program in the familiar single-threaded style. By having several concurrent
205	processes running the same application it is often possible to achieve high performance with single-threaded
206	programming.
207	</P>
208	<P>
209	The FastCGI interface allows Web servers to implement <I>session affinity</I>, a feature that allows
210	applications to maintain caches of user-related data. With session affinity, when several concurrent processes
211	are running the same application, the Web server routes all requests from a particular user to the same
212	application process. Web server APIs don't provide this functionality to single-threaded applications, so
213	the performance of an API-based application is often inferior to the performance of the corresponding FastCGI
214	application.
215	</P>
216	<H3>
217	4. Distributed FastCGI
218	</H3>
219	<P>
220	Because FastCGI can communicate over TCP/IP connections, it supports configurations in which applications run
221	remotely from the Web server. This can provide scaling, load balancing, high availability, and connections to
222	systems that don't have Web servers.
223	</P>
224	<P>
225	Distributed FastCGI can also provide security advantages. A Web server outside a corporate firewall can
226	communicate through the firewall to internal databases. For instance, an application might need to
227	authenticate incoming users as customers in order to give access to certain documents on the external Web
228	site. With FastCGI this authentication can be done without replicating data and without compromising security.
229	</P>
230	<H3>
231	5. Roles
232	</H3>
233	<P>
234	A problem with CGI is its limited functionality: CGI programs can only provide responses to requests. FastCGI
235	provides expanded functionality with support for three different application "roles":
236	</P>
237	<UL>
238	<LI>
239	<B>Responder.</B> This is the basic FastCGI role, and corresponds to the simple functionality offered by
240	CGI today.
241	</LI>
242	<LI>
243	<B>Filter.</B> The FastCGI application filters the requested Web server file before sending it to the
244	client.
245	</LI>
246	<LI>
247	<B>Authorizer.</B> The FastCGI program performs an access control decision for the request (such as
248	performing a username/password database lookup).
249	</LI>
250	</UL>
251	<P>
252	Other roles will be defined in the future. For instance, a "logger" role would be useful, where the
253	FastCGI program would receive the server's log entries for real-time processing and analysis.
254	</P>
255	<H3>
256	6. Conclusions
257	</H3>
258	<P>
259	Today's Web business applications need a platform that's fast, open, maintainable, straightforward,
260	stable, and secure. FastCGI's design meets these requirements, and provides a logical migration path from
261	the proven and widely deployed CGI technology. This allows developers to take advantage of FastCGI's
262	benefits without losing their existing investment in CGI applications.
263	</P>
264	<P>
265	For more information about FastCGI, visit the <A HREF="http://www.fastcgi.com/">www.fastcgi.com Web site</A>.
266	</P>
267	</BODY>
268	</HTML>
269