chickadee » bokbok

[[tags: egg]

bokbok

Description

A secure remote procedure call library for Chicken Scheme.

It supports:

Code repository

The source code for bokbok is hosted in Fossil at http://www.kitten-technologies.co.uk/project/bokbok.

Author

Alaric Snell-Pym

Requirements

Requires the tweetnacl, socket, srfi-27 and matchable eggs.

Quick start

See https://www.kitten-technologies.co.uk/project/bokbok/doc/trunk/bokbok-client.scm and https://www.kitten-technologies.co.uk/project/bokbok/doc/trunk/bokbok-server.scm for a demo client and server.

API reference

passphrase->key passphrase-stringprocedure

Converts an arbitrary passphrase string into a key object that can be used as an argument to open-connection! or returned from a server's username->key callback.

open-connection! address username key request-handler close-handlerprocedure

Opens a connection, returning a connection object.

address can be in any of the following forms:

  • "HOSTNAME:PORT" or (tcp HOSTNAME PORT) for a TCP connection
  • "PATH/TO/SOCKET" or (unix "PATH/TO/SOCKET") for a UNIX domain connection

username and key will be used to authenticate and encrypt the connection; the server can't accept the connection unless the key matches what it expects for that username. So if you or the server have not got the right key, the connection will fail.

For an unencrypted and unauthenticated insecure connection, set username and key to #f.

request-handler is a callback that will be invoked (in a thread) for any requests that come from the server. It will be applied to two arguments: the connection object itself and the request received from the server. Its return value will be taken as the response to the request and sent back to the server. Any errors raised in the request-handler will be sent back to the server.

close-handler is a callback that will be invoked (in a thread) if the connection is closed by the server. It will be applied to a single argument, the connection object.

open-connection returns the connection object.

connection? conprocedure

Returns #t if and only if the argument is a connection object.

connection-user conprocedure

Returns the username of the connection, or #f if it's an insecure connection.

connection-addr conprocedure

Returns the address of the other end of the connection.

close-connection! conprocedure

Closes a connection.

request! con messageprocedure

Sends the message (an arbitrary sexpr) as a request to the other end of the connection, and blocks waiting for a response. This is thread-safe - multiple threads may call request! on the same connection in parallel, and although the connection is blocked while a request is being sent or a response received, it is not blocked while a request is being processed at the other end, and responses may come back in a different order to the requests sent.

If the request fails for networky reasons, a suitable error is raised; if the request handler at the far end fails, a remote error is raised.

remote-error? errorprocedure

Returns #t if and only if the error is a remote error.

remote-error-message errorprocedure

Returns a string describing what went wrong at the other end of the connection.

start-server bind-addr backlog user->key open-handler request-handler close-handlerprocedure

Starts a bokbok server in a thread, and returns a server object.

bind-addr is the address to bind to, either (unix PATH) for a Unix-domain socket or (tcp ADDRESS PORT) for a TCP socket. An ADDRESS of #f causes it to bind on all available addresses.

backlog is the listen backlog. This is a slightly mysterious tuning parameter that can matter in highly-loaded systems. Try using 10.

user->key, if provided, is a callback closure invoked to authenticate and authorize encrypted connections. It is passed a username string, and must return a key object that matches the key object used by the client when opening the connection. Attach it to whatever passes for a database of users on the server. It should return #f for an unrecognised or otherwise not allowed to connect username. If #f is provided, then the server listens for insecure connections.

open-handler is a callback closure invoked whenever a new connection is made to the server. It is applied to the connection object.

request-handler is a callback closure invoked whenever the client sends a request to the server on any connection, as explained above under open-connection.

close-handler is a callback closure invoked when the client closes a connection. It is applied to the connection object.

stop-server! serverprocedure

Asks the server to stop.

wait-until-server-stopped serverprocedure

Blocks until the server has stopped.

Contents »