jschoubben
b72b71a989
031: a window of unacknowledged declarations is drained to the newest; the rest are set aside and reported as superseded. 035: a file resource may say create-once — written when absent, kept untouched when present (ADR 0087). 054: the bundle installs nftables and loads a base ruleset before the store and broker, in the table the filter module later replaces (ADR 0088).
89 lines
4.3 KiB
Go
89 lines
4.3 KiB
Go
package link
|
|
|
|
// The wire formats shared with the control plane, which defines them separately because this
|
|
// binary requires nothing present and does not import it. A test on each side asserts the field
|
|
// names, so a rename breaks both at once rather than on a real machine months later.
|
|
|
|
// Routing keys a node may publish. Its broker account is scoped to this exchange and its own
|
|
// queue, so it can say these things and nothing else.
|
|
const (
|
|
KeyReport = "report"
|
|
KeyAlive = "alive"
|
|
)
|
|
|
|
// Alive is a node saying nothing except that it is there.
|
|
//
|
|
// novox/hq 09-the-node-lifecycle: *how long it has been disconnected is a fact the mesh must
|
|
// hold, and nothing holds it today. Without it, a node running last month's assignments looks
|
|
// exactly like one that is current.*
|
|
//
|
|
// Separate from a report because the two happen at completely different rates: a node is alive
|
|
// constantly and applies something rarely, and reading one as the other would make a quiet node
|
|
// look like a stale one.
|
|
type Alive struct {
|
|
Node string `json:"node"`
|
|
}
|
|
|
|
// Signed is a declaration and the signature over it.
|
|
//
|
|
// novox/hq ADR 0004: the transport is verified once at connect, and **each declaration is
|
|
// verified by its signature, every time**. The two are different questions — a node connects to
|
|
// the broker and takes instruction from the control plane behind it, and pinning only the first
|
|
// would make the second transitive.
|
|
//
|
|
// The signature is over Declaration exactly as it arrived, bytes unchanged. Re-encoding before
|
|
// verifying would mean checking a signature over something other than what was sent, and any
|
|
// difference in key order or spacing would break it — so the raw message is what is signed and
|
|
// what is checked.
|
|
type Signed struct {
|
|
Declaration []byte `json:"declaration"`
|
|
Signature []byte `json:"signature"`
|
|
}
|
|
|
|
// Report is what a node says after applying, and it is a statement rather than a write.
|
|
//
|
|
// A node states; the context that owns the data writes (novox/hq ADR 0006). The difference is the
|
|
// security boundary: something that can write cannot be prevented from writing anything, and
|
|
// something that can only state has its blast radius bounded by what this struct can say.
|
|
type Report struct {
|
|
Node string `json:"node"`
|
|
|
|
// Applied is what this machine now owns, by resource id.
|
|
Applied []string `json:"applied,omitempty"`
|
|
|
|
// Failed says what could not be applied, and why, in words for a person.
|
|
Failed map[string]string `json:"failed,omitempty"`
|
|
|
|
// Refused is set when the declaration was rejected whole rather than applied in part.
|
|
Refused string `json:"refused,omitempty"`
|
|
|
|
// Superseded names the newer declaration this one was set aside for, unapplied.
|
|
//
|
|
// A machine asked to be five successive things becomes the last one (novox/hq issue 031):
|
|
// when several declarations are waiting, the host applies the newest and acknowledges the
|
|
// rest without applying them. Each of those is still reported, because silence reads as a
|
|
// machine that ignored an instruction and "applied" would be a lie — this is the third word.
|
|
Superseded string `json:"superseded,omitempty"`
|
|
|
|
// Carried are the machine's ports held by what this host raised from its own bundle.
|
|
//
|
|
// **So the mesh can assign around what it did not put here** (novox/hq ADR 0038). A node
|
|
// raises its foundation before any mesh exists, so the control plane has never heard of the
|
|
// store or the broker — and would hand a module a port one of them holds, discovering it only
|
|
// when a container runtime refused to start.
|
|
//
|
|
// A node *states* and the mesh writes, which is the whole shape of this message: this is the
|
|
// machine saying what is true of it, not asking for anything.
|
|
Carried []int `json:"carried,omitempty"`
|
|
|
|
// Declared is the digest of the declaration this report is about — sha256 of the exact bytes
|
|
// the mesh sent, which the mesh recorded when it sent them.
|
|
//
|
|
// **Which declaration, not when.** The mesh compared its send time to this report's arrival
|
|
// to decide whether a machine had caught up, and lost the race it invited: an apply started
|
|
// under the previous declaration finishes after the next one is sent, its report lands newer
|
|
// than the send, and the machine reads as caught up with words it has not read yet. Clocks
|
|
// cannot answer "which"; the digest is the answer itself.
|
|
Declared string `json:"declared,omitempty"`
|
|
}
|