URIS
http://codeforpeople.com/lib/ruby/acgi/
SYNOPSIS
as·sid·u·ous (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 drop-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/acgi-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/acgi-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/acgi-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/acgi-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, handling all
incoming requests; the requests are delegated to this backend server via a
simple, fast to start up, 'index.cgi' program written in c. communication
between 'index.cgi' and it's backend server is via named pipes (fifos):
···
-------------
> index.cgi | <- transient compiled c code
-------------
> > >
> fifos for stderr, stdout, stdin, env
> > >
/ | \
------------------------------
> >
> cgi server | <- persistent looping ruby code
> >
------------------------------
note that the architechture is similar in spirit to fastcgi - it provides
speed by avoiding startup overhead and redundant work like database connection
setup. in this case, contrasted with fastcgi, the whole thing takes place
outside of the webserver in the application domain and, therfore, communicates
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 compiled c
program (ultra fast startup time) which in turn does the following
- make sure the ruby server is running, spawn it in the background iff
required. this is a non-blocking operation that functions as a simple
process manager in order to ensure a server is running at all times.
- 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 them 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 being read
by index.cgi, the compiled c program
this cycle is mostly transparent to the cgi progam. for instace, to convert
an existing cgi program into an acgi program one would simply change
require 'cgi'
cgi = 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 you
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 indexing,
one can hit a url like
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 linux,
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 these
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 needed.
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 install.
BUGS
> 42
WHY
i think having something out there that was almost as fast as fastcgi, but
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/maintaining
fastcgi and cluster them to make it up 
i'd like to get a minimal package
going that supports windows and *nix. if you are interested in participating
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.
it's pretty simple c anyhow.
ara [dot] t [dot] howard [at] noaa [dot] gov
-a
--
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
===============================================================================