aboutsummaryrefslogtreecommitdiffstats
path: root/docs
Commit message (Collapse)AuthorAgeFilesLines
* guides: keys in an ssh-agentecdsaslopulus64 min.3-6/+30
| | | | | | A party's key is `ssh-ed25519` or `ecdsa-sha2-nistp256`; the client signs with a private key file or through an ssh-agent holding the key, given its public key. Code of its own signing with ECDSA makes `s` low, which `ssh-keygen` does only half the time.
* federation.md, federation-tests.md: ecdsa-sha2-nistp256 keys, their ↵slopulus64 min.2-17/+28
| | | | | | | | signature low-S A key is `ssh-ed25519` or `ecdsa-sha2-nistp256`, spelled alike; an ECDSA signature is over SHA-256, its `s` low and `r` and `s` SSH's shortest mpints, so that it is spelled one way. The vectors and the agent test, among the harness's.
* dashboard: the federation, in a swarm holding a storeHEADmastertv5 hours4-2/+52
| | | | | | | | | | | | | | In a swarm holding a store, the snapshot names the node's party, and the document box shows what counts as the node reads it, read every 5 s: the current version, the parties with their keys and nodes, the rules, the values at places as a tree with who writes there, the proposals on the version with where each stands, who voted what and what its version changes, and what the node refused. `document` beside `remake…` shows the document underneath. Where the node votes for its party by itself, a proposal that can still pass has a vote of each kind, cast through the node on a second click. The page writes no values: a party signs its writes with its key.
* events: the store's summary names the node's party, and whether it votes for ittv5 hours3-9/+16
| | | | | | `GET /events` names the party the node is of (`party`, `--store-party`) and whether it votes for it by itself (`votesByItself`, `--store-vote-key`), and so casts a vote by hand (`POST /admin/events/vote`): what a page offering votes through the node asks.
* continuum-party: options from configuration files, as the node'stv5 hours2-1/+24
| | | | | | | | | `continuum-party` takes its options (`node`, `token`, `key`, `record`: `config::PARTY_OPTIONS`) on the command line and in configuration files of the node's format: `--config`, repeatable, arguments winning, `--unset`, includes and imports. The configuration's loader takes the options it reads as a table (`config::with_options`, `config::merged`, `file::load_with`), the node's or the client's, and a key naming none of them is an error in either; `node` and `token` are secrets, never logged.
* continuum-party proposals: where each proposal stands, and what it changestv5 hours1-0/+11
| | | | | | | | `continuum-party proposals` lists the proposals on the current version at the node, each with whether it passed or is dead and the parties voting `true` and `false`, as `GET /events/counts` names them, and what its version changes of the current one, read from an event proposing it, its signature checked: each field whose value differs, and of `keys` and `nodes` each party's (`client::changes`).
* events: counts names who voted what, and whether a proposal passed or is deadtv5 hours4-7/+38
| | | | | | | | `GET /events/counts` gives each proposal on the current version the parties voting `true` and `false` (`yes`, `no`), whether it passed and whether it is dead (`passed`, `dead`), as the node reads its votes (`State::tally`, which the fold judges by too), so that reading where a vote stands takes no fetch of every vote. A party's client still decides its votes by the votes it checks itself.
* guides: designing a federation's rulestv7 hours2-0/+91
| | | | | | How rules match, a namespace each, zones and blocks a party holds by its name, shared places given by rules of their own and kept apart from party names, what rules cost in votes and size, and the krebs registry's rules as an example.
* guides: building on a federated swarm's APItv7 hours2-0/+91
| | | | | | Reading what counts and when to read again, writing through the party's client or as events of its own spelled and signed as the federation does, when a write counts, one writer at a place, keeping a namespace in step, and the store API refusing writes.
* guides: what to watch in a federated swarmtv7 hours2-0/+47
| | | | | | Beside what every node needs watching: a version a node refused, a node without its store, the proposals and the version, the members, the events beyond the checkpoint, and the store's log lines at warn and error.
* guides: upgrades and the federation's numbertv7 hours2-0/+36
| | | | | | Upgrading the nodes of a federated swarm, each party its own, close together; what the federation's number names, fixed by vectors; a version of another federation refused, and moving to the next one by a version.
* guides: remakes under a federationtv7 hours2-0/+64
| | | | | | Compactions only, the electorate among the store's members, the snapshot holding the store read at the base, what a node puts again after a switch, the lower of two epochs, which epochs a node rejoins, and a swarm that never remakes.
* guides: refusals and dropstv7 hours2-0/+73
| | | | | | What `GET /events/refused` shows and of which kinds, the events a refused change carried, what the store file keeps across restarts, having a node drop events and take them back, and when an operator does.
* guides: a drop's answer as the node writes ittv7 hours1-1/+1
|
* guides: a node voting by itselftv7 hours2-0/+77
| | | | | | Setting up a node to vote for its party, its key and the party's one record, voting by hand through it, its rules for following, proposing checkpoints and voting `false` beside, what it keeps to, and what its log says.
* guides: a version begun from the current one leaves out its checkpointtv7 hours1-1/+3
| | | | | | The current version may name a checkpoint, whose heads are behind: a version naming them again is never written. Writing a version leaves it out unless the version moves the store on.
* guides: common changes to a federation's versiontv7 hours2-0/+111
| | | | | | The next version begun from the current one, and recipes as jq filters for letting a party in, taking one out, giving and taking back a place, zones and blocks, and keys named anew; what a party changes by itself; and a version that only moves the store on.
* guides: what a federation promisestv7 hours2-0/+63
| | | | | Who a party and the adversary are, the three promises in plain words, what isn't promised, and what that asks of a party, an operator and an application.
* guides: forking and following in a federationtv8 hours2-0/+80
| | | | | | | When a group forks, choosing the heads, the fork's version, its root as a node builds it, starting the fork's nodes and beginning a record there; what a node holding the history finds of a fork's root; and following a fork, coming back, and groups that parted coming together.
* guides: when things go wrong in a federationtv8 hours2-0/+83
| | | | | | | A version a node refused by what it took before, finding from the parties' records who voted twice, having a node drop one side's version and take the other's, answering by a fork, and what keeps a node from holding its store, syncing, taking an event, or starting.
* guides: checkpoints in a federationtv8 hours2-0/+80
| | | | | | | What a move to a checkpoint keeps and loses, a version only moving the store on and the heads to name, a node proposing checkpoints by its operator's rules, backing only heads that leave out nothing held for a while (which a node voting by itself checks and a party's client doesn't), signing again after a move, and nodes that weren't there.
* guides: a federated party's keystv8 hours2-0/+87
| | | | | | The keys a version names, kept apart with the party's record, and those of its key set, signing its writes; changing a set and signing again what should stay; changing the keys a version names; a stolen key of either kind; and the node key, which is no party's.
* guides: proposing and voting in a federationtv8 hours2-0/+118
| | | | | | | Writing a version from the current one, its `since`s and what makes one none, proposing it, voting through the party's client by its record and what the client refuses to cast, voting through a node that votes for its party, a lost record, and when a proposal passes or dies, with the counts for some numbers of parties.
* guides: writing and reading in a federationtv8 hours2-0/+114
| | | | | | Places and the rules naming their writers, a write through the party's client and what it may hold, what counts and what stops counting, the refusals a node names, signing again what a move refused, and what `GET /events/counts` shows.
* guides: running a node of a federationtv8 hours2-0/+111
| | | | | | | What a node of a federated swarm does otherwise than any: its store options and file, members syncing with members only, its API letting in whoever its operator lets in to do everything, the store API refusing writes, joining by ID and from a pinned checkpoint, and what it writes by itself.
* guides: getting started with a federationtv8 hours2-0/+197
| | | | | | | `docs/guides/federation/` holds the guides to a federated swarm, the design saying what the rules are and they how to live by them. The first: two parties start a federation, a node each, write, read, and let a third party in by their votes. The README points to them.
* federation.md, federation-tests.md: the stages end with remakesfederation-2-stage-5tv8 hours2-4/+1
| | | | | | What a federation is used for is read and written through a node's API: kartei's entries are signed in by their parties and read from what counts there, with no stage of their own.
* federation.md: kartei's files, identifiers and rules on a federated swarmtv8 hours1-11/+25
| | | | | | | | | The registry holds each kartei namespace in its party's, a place per file. What kartei's consumers read as one for all (host and user names, the names hosts go by, addresses and blocks in every net but `internet`) is shared, at places of its own, given by krebs's rules: a party's by its name, and what kartei gives it beyond them by a rule each in the first version. What kartei's consumers read is written out from what counts, but for what names an identifier the current version doesn't give its party.
* docs: the federation's test plan, built to stage 5tv16 hours1-5/+5
|
* federation: votes build on the events proposing what they vote ontv18 hours1-14/+16
| | | | | | | | | | A node voting by itself, and a party's client, signed a vote on the heads the node held: where those held what is beside a checkpoint's heads (a party's writes made while the swarm was parted, say), the vote wasn't above them, and a version event written on it was refused, so the checkpoint never moved, though it passed. Both now vote on the events proposing what they vote on, and a node proposes a checkpoint on the heads it names: so their votes are above those heads wherever the proposal is.
* docs: the vectors of the changes founding a swarm are fixedtv20 hours1-5/+5
|
* docs: the forks' tests are built, but for the genesis changes' vectorstv20 hours1-2/+2
|
* api: a fork's root made, and what a node finds of onetv20 hours1-0/+99
| | | | | | | | | `POST /admin/events/fork`: the root of the fork at the heads named by the version given, as the node's store builds it, with the events it keeps, as the file the fork's founders start its swarm from (`--store-root`). `POST /events/fork`: what the node finds of the fork whose root the body holds: whether it builds that root at its heads, and why not; what it holds that those heads lack; and the parties whose keys the fork's version gives otherwise than they had there (`federation::fork`).
* federation: a rule voting `false` on a checkpoint proposed beside one a node ↵tv20 hours1-2/+4
| | | | | | | | | | backs `--store-nay-beside`, for a node voting by itself: where its party backs a proposal on the current version that can still pass, by its record or by what it votes now, it votes `false` on every other proposal there that only moves to a checkpoint and can still pass, once. So, of two checkpoints proposed at once, the one it doesn't back dies, and its backers are free (`docs/federation.md`, Votes a node casts by itself).
* docs: the store's tests on Automerge are built, but for the genesis changes' ↵tv22 hours1-7/+8
| | | | | | | vectors `docs/federation-tests.md` says so, and that each attack table has a test of its own checking that every row has its test.
* docs: votes a node casts by itself are builttv23 hours1-4/+6
| | | | | | The federation's design says that votes a node casts by itself are built: following parties and proposing checkpoints, backing a checkpoint by the voters' rule, and its party voting by hand through it.
* api: a vote by hand, through the node that votes for its partytv23 hours1-0/+40
| | | | | | | | | | A party that has a node vote by itself votes by hand only through that node, which keeps its one record (`docs/federation.md`, Votes a node casts by itself): `POST /admin/events/vote`, `{"proposal": <hash>, "yes": <bool>}`, by the record and, with a `true`, by the voters' rule; signed with the party's key the node keeps, recorded, and put. Refused (`422`) where the record or the rule forbids it, or the node votes for no party. Putting an event through the API puts it into the document as the node's own votes are put (`held::write`).
* node: votes it casts by itself, for its partytv23 hours1-0/+14
| | | | | | | | | | | | | | | | | | | | | | A node may vote and propose for its party by itself, by its operator's rules (`docs/federation.md`, Votes a node casts by itself; `federation::vote`): * `--store-vote-key`: the party's key it signs with, an OpenSSH private key file, one the party's version names, kept on the node; * `--store-vote-record`: its party's one record of its votes, which it votes by, written before each vote is sent, begun where there is none on the version current then; * `--store-follow`, `--store-follow-any`: the parties it follows, by default only on a version that only moves to a checkpoint; * `--store-propose-events`, `--store-propose-every`: when it proposes a checkpoint, once it holds so many events beyond its checkpoint, or so long after its store moved there; * `--store-held-for` (10 minutes): how long it holds an event before it holds it for a while, for the heads it proposes and the voters' rule. Its store keeps when, by the node's own clock, it took each event, and when it moved to its checkpoint. Whenever the worker reads the store, the node decides what to sign (`Holding::act`), records it, writes the record, offers it to its store, and puts it into the document (`held::write`). A vote by hand through the node, by the record and the voters' rule, is `Holding::vote_by_hand`.
* docs: what of the federation is builttv23 hours1-7/+11
| | | | | | | The federation's design says what of it is built: the store in a swarm's document, members by the federation and the store at a node's API, as the store's design says; and a party's client, which signs its party's events, votes by its record, signs again what a move refused, and names a party that voted twice.
* api: what the store refused, by kindtv23 hours1-2/+9
| | | | | | `GET /events/refused` says of each refusal its kind (`none`, `judged`, `builtOn`, with the event it builds on, or `notAbove`), apart from why: a party's client signs again what a move refused, which it tells so.
* api: what counts names the proposals on the current version, and their votestv23 hours1-2/+18
| | | | | | | A party's client votes by the record it keeps, and keeps the votes that made its party's earlier proposal dead; it reads them from a node, and checks them itself, as each is signed. `GET /events/counts` names the proposals on the current version, by their hash, each with the events proposing it and the votes on it, by ID (`State::ballots`).
* continuum is a librarytv23 hours2-2/+3
| | | | | | | | Everything the node is moves from the binary into a library (`src/lib.rs`), so that other binaries can use it: a party's client of a federation next. The node's binary (`src/main.rs`) runs it (`continuum::run`), which wires things together as `main` did. The library's doc comments are prose, not examples to test (`doctest = false`); its tests are the library's, as `cargo quick` and `cargo sim` run them.
* docs: the store at a node's API is builttv23 hours1-10/+12
| | | | | The store's design says that the store at a node's API is built: putting events, and showing what counts, what it refused, and its operator's drops.
* api: a swarm holding a store at a node's APItv23 hours1-0/+230
| | | | | | | | | | | | | | | | | | | | | | Behind the `federation` feature, a node of a swarm holding a store has, at its API (`docs/store.md`, Members; `docs/openapi.yaml`, Events): * `GET /events`: its store's ID, its checkpoint's, its heads, and how many events it took after its checkpoint; * `POST /events`: an event put, whoever signed it, offered to the store and written into the document at its ID unless the store refuses it (`422`, with why): taken, held, or waiting for what it builds on; * `GET /events/{id}`: an event the store holds, or its checkpoint, as its bytes; * `GET /events/counts`: what counts as the store reads now: the current version, each party's keys and nodes, the values at places, the members; * `GET /events/refused`: what the store refused, its own refusals apart, its operator's drops, and the rest with why; * `POST /admin/events/drop` and `/admin/events/allow`: its operator has it drop what it took, and take it back. The events' endpoints are anyone's this node lets in, as the store's are; dropping and taking back need `write` on `_continuum`, as what operators do. While a node holds no store, they answer `404`.
* docs: members by the fold are builttv24 hours1-10/+12
| | | | | | The store's design says that members by the fold are built: each node of the party its operator names, syncing with members only, its neighbours among them and some among its own party's and those its operator names, and taking no token another node issued.
* api: in a swarm holding a store, a node takes no token another issuedtv24 hours1-1/+2
| | | | | | | | At its API, a node of a swarm holding a store takes no token another node issued (`docs/store.md`, Members): whoever its operator lets in may use it, and its operator lets in nobody through another node. A token every node of a swarm takes would let whoever another operator let in in here too. `token::issued_here` refuses such a token (`ElsewhereIssued`), behind the `federation` feature.
* topology: neighbours among the members of a node's own party, and of parties ↵tv24 hours1-0/+5
| | | | | | | | | | named A node of a swarm holding a store keeps some of its neighbours among the members of its own party and of the parties its operator names (`--store-neighbour-parties`), so that a party listing many nodes can't be all of them (`docs/store.md`, Members): its neighbours by the shared graph among those members alone, each as its entry names it, which every node of its party computes alike, with those among all members.
* node: the party a node of a swarm holding a store is oftv24 hours1-0/+5
| | | | | | | | | A node's group is its operator's, in its configuration (`docs/store.md`, Members): `--store-party NAME`, which `--store-root` and `--store-id` need, a party's name as the federation spells one. The node keeps it with its store (`Holding::party`), to name it in its entry and its handshakes. The options of a node of a swarm holding a store (`--store-file`, `--store-checkpoint`, `--store-party`) set without either are refused together.
* docs: what of the store on Automerge is builttv25 hours1-9/+14
| | | | | | | | The store's design says what of it is built: on Automerge, a swarm holding a store, started from its root or joined by its ID, each change judged by what it writes, and the store a node reads from its document, by what is its own, putting again what the document lacks, from a pinned checkpoint where there is one; not yet members by the fold, the store at the API, and remakes, of which such a swarm takes no records or acks.
* federation: a pinned checkpoint, found in the documenttv25 hours1-0/+6
| | | | | | | | | | | Once a store moved to a checkpoint, a node reading it from the root could take what was grown anew from the root since, by keys of versions long replaced: so its operator pins the checkpoint (`--store-checkpoint`, by its ID), and the node reads its store from there whenever it starts (`docs/store.md`, Pinned checkpoints). It finds it in its document: at heads a proposal's version names, built from their history read from the root, as any node builds the checkpoint it moves to (`Store::checkpoint_at`), the one whose ID is pinned. Until the document holds it, the node holds no store, and says so once.