Introduction

<h1>Introduction</h1>

Bokbok is a toolkit for exposing and consuming APIs between processes.

It supports:

  *  TCP or UNIX-domain sockets.
  *  Optional encryption and authentication (with pre-shared keys).
  *  Multithreading over a single connection: multiple threads may
     make requests via the same connection, and multiple request handlers can be
     running at once in their own threads.
  *  Connections are symmetrical once established: either side may
     invoke the other side's API at any time, "client" and "server"
     are just a matter of who sat passively waiting for a connection
     and who initiated it.

<h1>Usage</h1>

<pre>$ chicken-install bokbok</pre>

<ul>
<li><a href="bokbok-client.scm">Demo client</a></li>
<li><a href="bokbok-server.scm">Demo server</a></li>
</ul>

<h1>Concepts</h1>

<h2>Creating connections</h2>

A server is created by <tt>start-server</tt>, given an address to bind
to (IPv4 or UNIX socket). When connections come in, an "open handler"
is notified of the new connection.

The server can be asked to terminate with <tt>stop-server!</tt>. You
can block until it's died with <tt>wait-until-server-stopped</tt>.

A client is created by calling <tt>open-connection</tt>, given an
address to connect to, and creates a connection.

<h2>Using connections</h2>

Once connection setup is complete, connections are the same for both
client and server; that distinction is purely a matter of who created
the connection. Both sides can call <tt>request!</tt> to send a
request to the other side or <tt>close-connection!</tt> to close the
connection - and both sides have a request handler and a close handler
ready to handle those cases.

Normally the "client" calls <tt>close-connection!</tt>, but that's
just convention.

<h2>Encryption</h2>

If a username and key (which can be generated from a string by calling
<tt>passphrase->key</tt> is given when <tt>open-connection</tt> is
called, then the connection is opened as an encrypted connection. It
won't work very well if the wrong key for that username is provided,
or the username is unknown on the server.

If a server is started in encrypted mode, a key lookup function must
be provided. When a connection comes in, the username provided by the
client is passed to the key lookup function, which must either return
a key or <tt>#f</tt> if the user is not allowed to connect. If the key
returend matches the one the user provides, the connection will
succeed and be encrypted.

A random session key is actually used for encryption, chosen by the
client; the user's key is used to encrypt the session key for
transmission to the server, then discarded.