To ensure coherence of the Rube Goldberg Machine, all writes to interlace databases need to be re-routed to the update handler presently named track -- <database>/_design/interlace/_update/track. This piece of code annotates documents with extra metadata, such as the user responsible for the write.

views

Various views for sifting through history.

In a working interlace installation, the master copy of the design document lives in the database germ. On the filesystem, it is represented by a subdirectory of schema/, and written to germ by the push-ddocslake task.

design/interlace is written in livescript and runs in couchdb's javascript query server augmented with the livescript compiler.

helpers daemons

The Librarian

Librarian is responsible for interlace databases:

It accepts PUT requests on /_create and creates new databases pre-populated with design docs.

It also broadcasts the creation of new databases by writing to /interlace-broadcasts/event:db:created

It monitors changes of design docs in germ and writes them to all other interlace databases.

The Archivist

Archivist maintains the archive. It monitors changes on all the interlace databases and for each written document doc, it creates a new document with the structure {"type": "history", "doc": doc}, to serve as a history snapshot.

This implies history is flat within the database, organized for analyzing via views.

The Anonymous

Anonymous takes care of extra user tasks. It can perform a (couch-level) log-in if {"assertion": a} is posted as JSON to _anonymous/persona/login, where a is a Persona-generated login assertion. It will create accounts in couch as needed.

Caveat: it stores a randomly generated password in plain text on the user's documents, to perform couch login. This implies it will fail if the actual password is changed. It also implies you don't know your couch password as long as you are using Persona to log in.

Helper daemons are written in livescript and run on node.js. This directory is an npm package, geared towards self-contained installation.

Integration considerations

We rely on proxies adding some headers:

x-forwarded-for : a somewhat-standard way of recording client address.

x-original-host : arbitrary way of having the original Host header preserved.

We add the following endpoints (aside from <database>/_design/interlace/...):

/_create : creates instance databases

/_anonymous/persona/login : performs Persona login

...and the clients probably need access to at least these:

/_security : login and logout

/_anonymous : Persona login

Access control

TODO

Build / Install

run npm install pull the dependencies in.

run slake build to build the sources.

run slake push-ddoc to re-publish design docs.

run npm install -g to install the library to $(PREFIX)/node_modules and binaries to $(PREFIX)/bin

configure couch to run daemons by dropping the config snippet into /etc/couchdb/local.d

( Alternatively, the global-install step can be bypassed if the paths in the couch config are adjusted accordingly.