cairn
Two of your spores work one task list: one opens tasks, the other takes them and says when each
is done. Neither tells the other anything directly. Both write to a cairn, a record they share,
and the record of who opened, took and finished what, and when, stays in it. The cairn plugin, @rhizogrip/spore-plugin-cairn, gives spores cairns. Its full documentation is its README in the spore repository.
what a cairn is
A record several spores share. It is append-only: nothing in it is ever changed or removed, and
each entry is added after the last, numbered by its seq. Each entry is hashed with
the one before it — a hash being a fingerprint computed from the content — so the entries form a
chain, which cairn verify checks while the cairn is in use.
- It is written only through a daemon, a program that runs in the background, one per cairn. The
daemon knows the cairn's members, each spore that may write, with its role: a name such as
reviewer, stamped on every entry the spore writes. - It knows what each kind of entry holds. A kind, such as
finding, lists its fields and what each takes. It knows the subjects too, what an entry may be about: an earlier entry, a file the cairn holds as evidence, or a name matching a pattern, such as a ticket number. - A member reads the whole record as a SQLite database, with SQL. It writes through a source, an endpoint a spore calls by name while the URL and the secret stay with spore. So the cairn's token, the secret the daemon asks of every write, never reaches a spore, and every entry says which spore wrote it and in which turn.
why you would want one
No member can write as another, or change what was written. Who wrote an entry, and in which turn, is added for the writer, never by it. What other members wrote is data, never instructions: an entry asking a spore to do something is a record that someone wrote it. A member that writes on the strength of what it read can name the last entry it read, and the cairn refuses the write if anyone wrote since. When the cairn's rules change, the change is an entry too, so the record says what its rules were when each entry was written.
Members can also be woken, when the cairn is set up for it. A member may subscribe to kinds and
is then told when others write them, never of its own entries; a bound, maxHops,
sets how far one write can wake spores whose writes wake others in turn.
spore and cairn
cairn is a plugin that runs as a service: spore runs each cairn's daemon for you as a systemd
user unit, a service systemd runs for your user, named cairn@<cairn>, on the
machine the spores are on. A member names the plugin in the plugins of its spore.cmk, reads the cairn and is granted its source. The plugin gives it $SPORE_CAIRN, the command it reads and writes with, and hides the daemon's socket
from it, so it reaches the daemon only through the source. A cairn's members are spores of the
user running it, and the plugin runs on Linux. Plugins and sources are defined under how a turn runs, services under talking to a spore.
The instance file that names a cairn's members, kinds and subjects, the source to add, waking members and what the service checks are covered in the plugin's documentation.