armchair-historian

interlace couch extensions

what

The package has two areas: some features are implemented as design documents, stored in the database, while others are standalone programs, run and supervised by couch, as helper daemons.

Design Docs

Currently there is only one -- _design/interlace -- and its presence in a given database marks it as an "interlace database."

Its components are:

Interlace databases have custom validation logic (see below), with access policies defined in their respective _security documents, just as couch-native access policies are.

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.

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-ddoc slake task.

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

helpers daemons

Librarian is responsible for interlace databases:

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.

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:

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

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

Access control

TODO

Build / Install

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

Further work

Rewrite this in Erlang and stick it into the database.

( 2013-07-26 )

git clone git://git.numm.org/armchair-historian

snapshot: armchair-historian.zip

files