[ANN] acgi-0.1.0

[Ara.T.Howard]

--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--