bin/gitweb-gc.sh: add gitweb FastCGI utility script
commit6c476e790ce56a207f4f76ecc7b1de9a7c00ff35
authorKyle J. McKay <mackyle@gmail.com>
Thu, 28 Jan 2021 06:25:22 +0000 (27 23:25 -0700)
committerKyle J. McKay <mackyle@gmail.com>
Thu, 28 Jan 2021 06:25:22 +0000 (27 23:25 -0700)
treeea1c40a841e7f665b5e15ab40eed64f9ba47df16
parent7e4648bc1bb36053ace2eece9aeca448f9a897df
bin/gitweb-gc.sh: add gitweb FastCGI utility script

The FastCGI specification can still be found at:

  https://web.archive.org/web/20160310000121/http://www.fastcgi.com/devkit/doc/fcgi-spec.html

or alternatively archived here:

  https://fast-cgi.github.io/

Section "7. Errors" states:

> A FastCGI application exits with zero status to indicate that it
> terminated on purpose, e.g. in order to perform a crude form of
> garbage collection. A FastCGI application that exits with nonzero
> status is assumed to have crashed.

The gitweb.cgi application running in FastCGI mode falls into the
category of "application exits with zero status to indicate that
it terminated on purpose, e.g. in order to perform a crude form of
garbage collection."

The standard gitweb.cgi when running in FastCGI mode always exits with
"zero status" after serving 100 requests.

While Apache's mod_fcgid can easily be configured to expect this
behavior (via the `FcgidCmdOptions /gitweb.cgi MaxRequestsPerProcess 100`
configuration line), mod_fcgid handles unexpected "zero status" exits
just fine as well and simply restarts the cgi as needed.

Some other web servers that provide FastCGI support are not nearly as
forgiving (they do not handle the unexpected "zero status" exit) or as
accomodating (they do not have the equivalent of the `MaxRequestsPerProcess`
configuration option).

For example, lighttpd behaves very badly when gitweb exits with the
unexpected "zero status" after 100 requests and then proceeds to drop and
fail any outstanding requests to that FastCGI application before it manages
to restart it.

This causes a bad user experience as every so often requests will fail,
but then succeed when retried.

To accomodate these web servers that poorly implement the FastCGI
specification while allowing gitweb.cgi running in FastCGI mode to work
without intermittent failures, provide an intermediary "helper" script
that conceals the "zero status" (aka "crude form of garbage collection")
exits from the web server and seemlessly restarts a new copy of gitweb.cgi.

This allows use of gitweb.cgi in FastCGI mode reliably with a greater variety
of web server software than would otherwise be possible.

The new script, "gitweb-gc.sh" gets installed in the
"$Girocco::Config::basedir/bin" directory after performing an install of
Girocco.

When configuring a web server that does not properly handle FastCGI
"zero status [...] crude form of garbage collection" exits, instead of
configuring it to execute "$Gircco::Config::cgiroot/gitweb.cgi" directly,
it must be configured to execute "$Girocco::Config::basedir/bin/gitweb-gc.sh"
instead.

This will allow the deficient web server software to provide gitweb
services via FastCGI (much, much, much, much more responsive than spawning
a new gitweb instance for each request) while avoiding sporadic intermittent
failures as gitweb exits after serving 100 requests to perform a "crude form
of garbage collection."

Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
bin/gitweb-gc.sh [new file with mode: 0755]