Introduction

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.

Usage

$ chicken-install bokbok

• Demo client
• Demo server

See the API reference for further details.

Concepts

Creating connections

A server is created by start-server, 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 stop-server!. You can block until it's died with wait-until-server-stopped.

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

Using connections

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 request! to send a request to the other side or close-connection! to close the connection - and both sides have a request handler and a close handler ready to handle those cases.

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

Encryption

If a username and key (which can be generated from a string by calling passphrase->key is given when open-connection 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 #f 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.

Future work

Better test suite

We don't have an automated test of the actual bokbok client/server code, just low-level packet encoding tools. Write a test that spins up a server and talks to it (the full gamut - requests in each direction, errors, connection shutdown), and run it against both TCP and UNIX-domain.

Better docs

Include actual usage examples in here.

Subprocess mode

It's neat to be able to run a server as a process handling a single connection on stdin/stdout, either directly (the client starts the server) or via inetd.

There's code to do this in bokbok, but it's commented out as Chicken's threading blocks the whole process when the server thread blocks on reading from standard input. Fixing that will involve rearranging the low-level packet I/O to work in a nonblocking manner.