
=====================================
pure-fastcgi: FastCGI module for Pure
=====================================

.. default-domain:: pure
.. module:: fastcgi

Version @version@, |today|

Albert Gräf <aggraef@gmail.com>

This module lets you write FastCGI_ scripts with Pure, to be run by web
servers like Apache_. Compared to normal CGI scripts, this has the advantage
that the script keeps running and may process as many requests from the web
server as you like, in order to reduce startup times and enable caching
techniques. Most ordinary CGI scripts can be converted to use FastCGI with
minimal changes.

.. _FastCGI: http://www.fastcgi.com
.. _Apache: http://www.apache.org/

Copying
=======

Copyright (c) 2009 by Albert Graef. pure-fastcgi is distributed under a
3-clause BSD-style license, please see the included COPYING file for details.

Installation
============

Besides Pure, you'll need to have the FastCGI_ library installed to compile
this module. Also, to run FastCGI scripts, your web server must be configured
accordingly; see the documentation of FastCGI and your web server for details.

Get the latest source from
https://bitbucket.org/purelang/pure-lang/downloads/pure-fastcgi-@version@.tar.gz.

Running ``make`` compiles the module, ``make install`` installs it in your
Pure library directory. You might have to adjust the path to the fcgi_stdio.h
header file in fastcgi.c and/or the option to link in the FastCGI library in
the Makefile.

The Makefile tries to guess the host system type and Pure version, and
set up some platform-specific things accordingly. If this doesn't work for
your system then you'll have to edit the Makefile accordingly.

Usage
=====

pure-fastcgi provides the ``accept`` function with which you tell the FastCGI
server that your script is ready to accept another request.

.. namespace:: fastcgi

.. function:: accept

   Accept a FastCGI request.

The module also overrides a number of standard I/O functions so that they talk
to the server instead. These routines are all in the ``fastcgi`` namespace. In
your Pure script, you can set up a simple loop to process requests as
follows::

  #!/usr/local/bin/pure -x

  using fastcgi;
  using namespace fastcgi;

  extern char *getenv(char*);

  main count = main count when
    count = count+1;
    printf "Content-type: text/html\n\n\
  <title>FastCGI Hello! (Pure, fcgi_stdio library)</title>\
  <h1>FastCGI Hello! (Pure, fcgi_stdio library)</h1>\
  Request number %d running on host <i>%s</i>\n"
    (count,getenv "SERVER_NAME");
  end if accept >= 0;

  main 0;

(You might have to adjust the "shebang" in the first line above, so that the
shell finds the Pure interpreter. Also, remember to make the script executable.
If you're worried about startup times, or if your operating system doesn't
support shebangs, then you can also use the Pure interpreter to compile the
script to a native executable instead.)

This script keeps running until :func:`accept` returns ``-1`` to indicate that
the script should exit. Each call to :func:`accept` blocks until either a
request is available or the FastCGI server detects an error or other kind of
termination condition. As with ordinary CGI, additional information about the
request is available through various environment variables. A list of commonly
supported environment variables and their meaning can be found in `The Common
Gateway Interface`_ specification.

.. _The Common Gateway Interface: http://hoohoo.ncsa.uiuc.edu/cgi/

A number of other routines are provided to deal with data filters, finish a
request and set an exit status for a request. These correspond to operations
provided by the FastCGI library, see the FastCGI documentation and the
FCGI_Accept(3), FCGI_StartFilterData(3), FCGI_Finish(3) and
FCGI_SetExitStatus(3) manpages for details. An interface to the FCGI_ToFILE
macro is also available. Note that in Pure these functions are called
``accept``, ``start_filter_data``, ``finish``, ``set_exit_status`` and
``to_file``, respectively, and are all declared in the ``fastcgi`` namespace.
A detailed listing of all routines can be found in the fastcgi.pure module.

Please see the examples subdirectory in the pure-fastcgi sources for some more
elaborate examples.

Note that to run your FastCGI scripts in a browser, your web server must have
the FastCGI module loaded and must also be set up to execute the
scripts. E.g., when using Apache, the following configuration file entry will
set up a directory for FastCGI scripts::

  ScriptAlias /fastcgi-bin/ "/srv/www/fastcgi-bin/"
  <Location /fastcgi-bin/>
      Options ExecCGI 
      SetHandler fastcgi-script
      Order allow,deny
      Allow from all
  </Location>

(Replace ``fastcgi-script`` with ``fcgid-script`` if you're running
``mod_fcgid`` rather than ``mod_fastcgi``.)

Put this entry into http.conf or a similar file provided by your Apache
installation (usually under /etc/apache2), and restart Apache. After that you
can just throw your scripts into the ``fastcgi-bin`` directory to have them
executed via an URL like ``http://localhost/fastcgi-bin/myscript``.

You can also set up a handler for the ``.pure`` filename extension as
follows::

  <IfModule mod_fastcgi.c>
  <FilesMatch "\.pure$">
      AddHandler fastcgi-script .pure
      Options +ExecCGI
  </FilesMatch>
  </IfModule>

(Again, you'll have to adjust the ``IfModule`` statement and replace
``fastcgi-script`` with ``fcgid-script`` if you're running ``mod_fcgid``.)
After that you should be able to execute scripts with the proper extension
anywhere under your server's document root.
