# aloysius

**EARLY AND EXPERIMENTAL**

Aloysius is the HTTP server interface I want to use. It's very
slow at present, and still quite early, but it's at least a
proof-of-concept of something I think should exist.

## Basic Use

The Aloysius server does nothing but pass HTTP requests and
responses between other servers: it is, in effect, a mechanism
for establishing reverse proxies.

The server is invoked with a single optional argument, and it
continues running in the foreground until it is killed with
standard Unix signals. The argument is a directory, and if that
directory exists, it switches to that directory before
continuing. It then reads configuration from that directory and
will continuously forward requests based on that configuration.

The configuration directory contains zero or more
subdirectories, each of which describes a given request filter
and forwarding mechanism. The subdirectory may contain several
specifically named files, whose contents specify a forwarding
system:

~~~
path:    which request paths to match; defaults to "*"
domain:  which request subdomains to match; defaults to "*"
mode:    how to forward the request; defaults to "http"
host:    which host to forward to; defaults to "localhost"
port:    which port to forward to; defaults to "80"
conf:    which path to forward to; defaults to "/dev/null"
resp:    which HTTP response to issue; defaults to 303
~~~

These are interpreted as follows:

- The `path` and `domain` fields tell us which requests to forward:
both of them default to accepting anything, and both of them
allow their values to have the wildcard character `*`.

- The `mode` field tells us _how_ to forward requests. There are
three possible forwarding modes:
    - If the mode is `http`, then Aloysius will forward the HTTP
      request to the server listening on the host `host` and the
	  port `port`.
    - If the mode is `aloys`, then Aloysius will recursively check
	  the configuration directory at `conf`.
    - If the mode is `redir`, then Aloysius will respond with an
	  HTTP response code as indicated in `resp` and redirect to
	  the host as indicated in `host`.

## Example Setups

Because configuration is specified as a directory, rather than as
a single file, we can use properties of the Unix file system as a
simple ACL-like mechanism. For example, a system administrator
can set up a user-owned configuration directory for each user,
and then use a global configuration directory to forward requests
to that user on a per-subdomain basis:

~~~
$ mkdir -p /var/run/aloys
$ for U in $USERS
> do
>     # find the user's home directory
>     HOMEDIR=`cat /etc/passwd | grep ${U} | cut -d ':' -f 6`
>
>     # add a configuration directory to each user
>     mkdir -p ${HOMEDIR}/aloys
>     chown ${U} ${HOMEDIR}/aloys
>
>     # add a new forwarding rule for each user
>     mkdir -p /var/run/aloys/${U}-local
>     # make ${U}.example.com forward to the user's aloys configuration
>     echo "${U}.example.com"  >/var/run/aloys/user-${U}/domain
>     echo "aloys"             >/var/run/aloys/user-${U}/mode
>     echo "${HOMEDIR}/aloys"  >/var/run/aloys/user-${U}/conf
> done
$ aloysius /var/run/aloys
~~~

Now, if a given user wants to set up a local HTTP server that
produces dynamic content, they can add the appropriate forwarding
configuration to their own directory, but they cannot modify
other users' configurations or the global configuration.

Even if you're running a single server, but want to have multiple
services on it, this can be a convenient way to set up reverse
proxy servers without needing root access.