From: "Ara.T.Howard" <Ara.T.Howard@...>
Date: 2005-09-15T14:51:14+09:00
Subject: [ANN] acgi-0.1.0

--8323328-1895207346-1126763468=:15399
Content-Type: MULTIPART/MIXED; BOUNDARY="8323328-1895207346-1126763468=:15399"

  This message is in MIME format.  The first part should be readable text,
  while the remaining parts are likely unreadable without MIME-aware tools.

--8323328-1895207346-1126763468=:15399
Content-Type: TEXT/PLAIN; charset=X-UNKNOWN; format=flowed
Content-Transfer-Encoding: QUOTED-PRINTABLE


URIS

   http://codeforpeople.com/lib/ruby/acgi/


SYNOPSIS

   as=C2=B7sid=C2=B7u=C2=B7ous (adj.)

     1. constant in application or attention; diligent: an assiduous worker=
 who
     strove for perfection.

     2. unceasing; persistent: assiduous research.

   acgi : assiduous or ara's cgi (emphasis on the 'ass' in assiduous) a dro=
p-in
   replacement for ruby's built-in cgi that provides copious features such =
as

     - no apache modules
     - persistence
     - speed
     - simplicity
     - familiarity
     - no apache modules
     - browser neutrality
     - could easily be made platform independent
     - no apache modules
     - no special webserver setup or system privledges required
     - ability to install to a webserver via ftp
     - no apache modules
     - session affinity, all request handled by one process
     - automatic reload if code changes
     - ability to run script simulaneously as acgi and cgi for debuggging
     - ability to easily start/stop/restart/check-on running server
     - 178 lines of ruby code (and one c program)
     - no apache modules


PERFORMANCE

   case one, a simple cgi that just dumps the environment:

   with acgi:

     [ahoward@localhost acgi-0.1.0]$ ab -n100 -c4 http://localhost/acgi/acg=
i-0.1.0/ | grep 'Requests per second'
     Requests per second:    74.93 [#/sec] (mean)

   without:

     [ahoward@localhost acgi-0.1.0]$ ab -n100 -c4 http://localhost/acgi/acg=
i-0.1.0/server.cgi | grep 'Requests per second'
     Requests per second:    18.76 [#/sec] (mean)


   a more realistic cgi that uses sessions and sleeps for 1 second to mimic
   connecting to a database:

   with acgi:

     [ahoward@localhost acgi-0.1.0]$ ab -n100 -c4 http://localhost/acgi/acg=
i-0.1.0/ | grep 'Requests per second'
     Requests per second:    24.20 [#/sec] (mean)

   without:

     [ahoward@localhost acgi-0.1.0]$ ab -n100 -c4 http://localhost/acgi/acg=
i-0.1.0/server.cgi | grep 'Requests per second'
     Requests per second:    3.63 [#/sec] (mean)


ARCHITECHTURE

   the design of acgi is similar to that of fastcgi (http://www.fastcgi.com=
) but
   requires no external modules, configuration of apache, etc.

   a acgi application consists of a cgi server backend which loops, handlin=
g all
   incoming requests; the requests are delegated to this backend server via=
 a
   simple, fast to start up, 'index.cgi' program written in c.  communicati=
on
   between 'index.cgi' and it's backend server is via named pipes (fifos):


                         -------------
                         | index.cgi |          <- transient compiled c cod=
e
                         -------------
                         |=09|   |
                         | fifos for stderr, stdout, stdin, env
                         |=09|   |
                        /=09|    \
                 ------------------------------
                 |                            |
                 |         cgi server         | <- persistent looping ruby =
code
                 |                            |
                 ------------------------------

   note that the architechture is similar in spirit to fastcgi - it provide=
s
   speed by avoiding startup overhead and redundant work like database conn=
ection
   setup.  in this case, contrasted with fastcgi, the whole thing takes pla=
ce
   outside of the webserver in the application domain and, therfore, commun=
icates
   via named pipes rather than unix domain sockets.


REQUEST CYCLE

   - request comes in to web server

   - request is passed to index.cgi which, itself, is a very simple compile=
d c
     program (ultra fast startup time) which in turn does the following

       - make sure the ruby server is running, spawn it in the background i=
ff
         required.  this is a non-blocking operation that functions as a si=
mple
         process manager in order to ensure a server is running at all time=
s.

       - aqurire a lock (fcntl) to prevent any other concurrent invocations=
 of
         index.cgi from overlapping - all invocations procede one at a time=
 in
         the order of receipt.  there are never concurrent requests to the
         server.  we can't all send data down the pipe at once.

       - serialize the environment and send it down the pipe

       - read any stderr/stdout from the ruby server via fifos and write th=
em to
         stderr/stdout respectively.  stdout and stderr go to the 'normal' =
places
         - the client and webserver log respectively.

       - release lock - automatic when index.cgi process dies anyhow

   - the ruby server, for it's part, does the following

     - aquire a lock which prevent multiple copies of itself from running
       simoultaneously.  this is the same lock the c program checks in a
       non-blocking fashion to see if the server is running.

     - loops doing the following

       - loading the environment

       - handling request with stderr/stdout/stdin redirected to pipes bein=
g read
         by index.cgi, the compiled c program

   this cycle is mostly transparent to the cgi progam.  for instace, to con=
vert
   an existing cgi program into an acgi program one would simply change

     require 'cgi'

     cgi =3D CGI::new
     cgi.out{ content }

   to

     require 'cgi'
     require 'acgi

     ACGI::each_cgi do |cgi|
       cgi.out{ content }
     end

   the same cgi script acts both as the backend to the index.cgi c program =
and
   the frontend to any 'normal' cgi requests.  the works as follows:  say y=
ou
   name your cgi program 'server.cgi' and it lives in a directory under the
   webroot like so

     acgi/server.cgi
     acgi/index.cgi

   then, assuming a webserver setup that uses index.cgi for directory index=
ing,
   one can hit a url like

     http://localhost/acgi/

   or

     http://localhost/acgi/index.cgi

   and the fast version will be run.  hitting

     http://localhost/acgi/server.cgi

   results in normal (slow) cgi mode - useful for debugging.


IMPLEMENTATION

   shoddy - but getting better (note move to 0.1.0 !!).

   this version is proof of concept only!!!  it's likely to run only on lin=
ux,
   though it may run on many *nix platforms.  or maybe not.  the sun could
   explode if you run the example program.  security is not considered.


RUNNING THE EXAMPLE

     - unpack tarball in webroot

     - make

     - point browser at

         http:://your.host.com/path/where/you/unpacked/

       to see the acgi version or

     - point browser at

         http:://your.host.com/path/where/you/unpacked/server.cgi

       to see the slow cgi version

   obviously you'll need cgi setup for you web server, index.cgi set for
   directory index, ruby installed, etc.  but nothing out of the ordinary.

   the server program will support some basic funtionality, as shown by the=
se
   examples:

     [ahoward@localhost acgi-0.1.0]$ sudo ./server.cgi status
     alive (10882)

     [ahoward@localhost acgi-0.1.0]$ sudo ./server.cgi pid
     10882

     [ahoward@localhost acgi-0.1.0]$ sudo ./server.cgi stop
     [ahoward@localhost acgi-0.1.0]$ sudo ./server.cgi status
     dead (10899)

     [ahoward@localhost acgi-0.1.0]$ sudo ./server.cgi start
     [ahoward@localhost acgi-0.1.0]$ sudo ./server.cgi status
     alive (10904)

     [ahoward@localhost acgi-0.1.0]$ sudo ./server.cgi restart
     [ahoward@localhost acgi-0.1.0]$ sudo ./server.cgi status
     alive (10904)

   the function is obvious.  sudo only needs to be used if the server ended=
 up
   getting started by the webserver, if it's running as you it is not neede=
d.

   for testing a server can be started by hand using

     ./server.cgi --server

   though you may actually want

     sudo -u apache ./server.cgi --server

   to run as the webserver uid.


DEPENDANCIES

   posixlock - included in depends dir, built during make - no need to inst=
all.


BUGS

   > 42


WHY

   i think having something out there that was almost as fast as fastcgi, b=
ut
   without the 'drain bamage' of installing it would be most useful.  plus =
i'm
   hopeful that it would actully be made quite a bit faster.  even if that =
turns
   out not to be true i imagine it'd be fast enough for many applications -=
 you
   could buy another node for the time spent installing/configuring/maintai=
ning
   fastcgi and cluster them to make it up ;-) i'd like to get a minimal pac=
kage
   going that supports windows and *nix.  if you are interested in particip=
ating
   please contact me.  mostly i'm in need of windows c/ipc knowledge - but =
i'm
   considering using the apr library (apache portable runtime) to write the
   index.c bit in a portable fashion which minimizes the brain power needed=
=2E
   it's pretty simple c anyhow.

EMAIL

   ara [dot] t [dot] howard [at] noaa [dot] gov

-a
--=20
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D
| email :: ara [dot] t [dot] howard [at] noaa [dot] gov
| phone :: 303.497.6469
| Your life dwells amoung the causes of death
| Like a lamp standing in a strong breeze.  --Nagarjuna
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D

--8323328-1895207346-1126763468=:15399--
--8323328-1895207346-1126763468=:15399--