Not Always Online
Bivouac does not assume every mirror, editor, or user is always online. Instead, members of a Crew opportunistically mirror from their friends blogs. For most decisions there will be some defined techie or administrator who tallies up votes and is the primary mirror or custodian venue, so the rest don't need to keep documents around.
Similar to cicadas, this requires the hapenstance that you and your friends' blogs happen to be online at the same time. Syncing USBs of folder content is probably feasible too (as with a sneakernet).
Group updates in bloat mode are much slower than what you're used to in fediverse PubSub. A site rendered once a day might complete a sync and decision cycle in a week.
Venue/Carrier health
Venues and Carriers' health can be expressed in a few states:
- dead - unreachable for longer than expected
- pending - they have changes
- quiet - they don't have changes
- broken - unsolvable zipper state or key we can't find
This can be viewed in a network health table.
Synced Topics
the part that will probably disappoint Aphyr for not being serializable
Folders in Bivouac's cache are initially random identifiers (UUID v4). In database jargon this is a surrogate key. If you do have a name for that folder (for example, the identity documents for @alice), during the sync and render phases the cannonized files become naturalized. These UUID folders are called "synced topics".
You may optionally use the same UUID4 IDs as the server you download from, but you may just as easily rotate them (e.g. on malicious conflicts). If you canonized a name, it could be rendered into a folder named the same thing, for example "/alice/".
Documents also have an internal UUID4, used by the author (that should be unique to the author). The folder could use the same UUID, or something else.
Meaning is derived based on what the peers in the group name things, not what folder the XML is in (the published site could be a random layout, as long as your editor can find the cicada files to download what matters).
Lists of content, recent changes, and the sync state of the group are detailed in .cicada
files in the folders. These are like torrent files, detailing the name, size, and SHA256
hashes. A CRDT or MVCC system might be smarter but this is good enough.
Document Lifetimes
Cicada documents detail in units of days:
- how long the files should be kept around (lifetimes)
- how often you should check for changes (cycles)
- how long each step in a process lasts (phases)
If a network partition persists, eventually nodes that have a file meant to have been deleted will move past their expiry time and should discard the half-unused file. Files that should stick around should be kept by at least one custodian venue.
Some documents are constantly renewed (like Phish or Crew documents). Others, like Decisions or Cicada changelogs, are slowly erased with time.
Temporal Operation Precedence
Deletions are noted in the cicada index but no tombstone file is kept.
- Last write wins
- Update wins over create
- Create wins over delete
Some topic folders might depend on other topic folders. Right now folders are flat rather
than nested. For now I'll point out that the permissions documents (the Mores
file
extensions) folders matter more than, say a decision document, and evaluate first during
rendering. Newer Phish
documents are similarly explored to find out if the new phish
keys were used to sign a pending document, for example.
Mods do have temporal powers to re-order, delete, or request replacements for documents if the sync zipper gets stuck. These temporal powers are used for example by Facilitators of a debate if any sort of human edits to an option need to be made to unstick the process. If a mod writes a cicada patch to reorder or insert something, their document ordering is the one that counts.
Sync Zipper
Sync is eventual, lazy and optimistic (creation, propagation, scheduling, conflict resolution, commitment). If a client is completely offline for a decision and didn't delegate their decision, they miss it. You can imagine sync like many simultaneous zippers that are in the process of individually meshing:
- the far ends we don't know about (drafts on other people's machines)
- (share) the ends they've published, and we've yet to download (parts of the zipper we can see)
- (receive) the known files, ordered in the time they were published (just before the zipper)
- (order, conflict or accept, certify, act) the files as accepted and applied (this is the state any sort of permissions/Mores access control lists or Karma are evaluated on)
- files that we're not presently applying, but still depend on for some reason
- files that are deprecated but still here on some custodian's server (in case someone who missed things might get lost) - other zipper end opening
- files that are getting deleted
Two phase commits (commit/abort votes), locks, rollbacks, MVCCs (read/write timestamps), & CRDTs are not considered here. It is approximately last-write-wins.
Where proof of a timestamp or receipt is needed, rather than rely on signed timestamp servers (e.g., RFC-3161 whatever), we ask a node to countersign a document a day or so later. This countersigning is also useful for noting the position of other servers' Cicada zippers (to know who to download what from).
Current, Pending, and Deprecated
Bivouac's cache and published sites have three subfolders: current, pending, and deprecated. Any pending file includes the user's current minisign public key fingerprint as part of the filename (for example, only one selection vote can be made per user on a vote, or only one NS change option can be made per user).
If the "pending" folder is empty, the topic is said to be "quiescent". If new changes exist, that's like having the zipper need to zip upwards to finish being in sync. Once it is, the bottom of the zipper can unzip and older state can be forgotten.
We only need to keep around the agreed upon current state of a folder during a quiescent cycle. Note that something might depend on many folders (for example, a folder of rules for this election, another folder for members of the electorate) - so that's why some files might still be needed for another purpose across the group.
For example, an election might contain a phase where an election is proposed, but needs enough signatures. Then, it might need a phase for candidates to get signatures. finally, people need to vote on candidates, and the results are tallied.
The authoritative state machine(s) are operated on a specific user's box, but other members of the group can be observers in some cases. This is explained more in the final bivouac section.
Cicada will not sync files in your salted deny list tags (more on those in Decal).
Torrent Super-Seeding
Cicada can include definitions for super-seeding, just like torrents. For example, if you have 8 documents, you can start by sharing a cicada file to each friend detailing one of the documents, and they mirror on day one. Next, on day two they ask their other friends (if they're online) for the other docs. Maybe they're lucky and can assemble everything. Or, you've updated your cicada doc for each friend and now list 2 docs for each friend. If it's up to the clients, they'll try to sort randomly and evenly/opportunistically download from many.
Caching is not Mirroring
Just because a file is synced to your device for review does not mean that Bivouac will mirror it publicly on your site. You need to define or approve per folder or group (etc) whether something should auto-mirror or whether it requires your approval (or a specific amount of karma or specific tags to not be present, etc)
If you don't know a lot about a group, you can download the group's cicada file. If you're after particular decisions, you can download just their update files.
You can optionally mirror the known state/cicada file of other servers (for example, noting that another server claims to have specific portions or is caught up to a specific cycle or phase).