mesh-sdk/go/buscompose/users.go

package buscompose

import "git.novox.be/novox/mesh-sdk/go/catalogue"

// Declared is one module on one node, as composing its authority needs it.
type Declared struct {
	Module   string
	Emits    []string
	Consumes []string
	Serves   []string
	// Served are the config keys its served values and zone name fill from its settings (catalogue.ServedSettings): what
	// every node may read of its resolved values where it runs (Principal.ServedReads, issue 1126).
	Served []string
	// Holds are the seats this module claims, with the protocol each seat declares. A seat the
	// mesh defines for itself declares no protocol, so holding one grants nothing on the bus —
	// which is right: those seats are about who does a job, not about who may say what.
	Holds []Seat
	// Uses are the seats this module sends to.
	Uses []Seat
	// Issued are the tools that answer a credential its software issued, one per offer that says so (novox/hq
	// ADR 0305): the controller is granted to ask each in its own name, and no other tool so.
	Issued []string
	// Watches are the seats whose events it consumes.
	Watches []Seat
	// Invokes are the tools it calls, `<module>.<tool>` or `*` (novox/hq ADR 0152).
	Invokes []string
	// Waits are the event families a session may wait on through the tool runner, the tool runner's module's
	// alone (novox/hq ADR 0367 §2): its account subscribes them for a call, through no consumer.
	Waits []Wait
	// State is the state it keeps, each a bucket its instances write (novox/hq ADR 0201).
	State []Bucket
	// Logs are the logs it keeps, each a stream its instances append to (novox/hq ADR 0297).
	Logs []Log
	// Streams are the streams it owns, each its events' one place (novox/hq ADR 0363).
	Streams []ModuleStream
	// Queues are its own work-queue streams and the one process each is the consumer of (novox/hq ADR 0436
	// §1, §2, §6): one durable consumer per entry, named `<node>_<module>_<process id>`.
	Queues []QueueOwner
	// Hears are the module streams it hears on this machine, each with the subjects it was granted
	// (novox/hq ADR 0363 §5); HearsAStream says its `consumes` names a module that owns a stream, granted
	// or not, so its membership is issued again when a grant changes.
	Hears        []Heard
	HearsAStream bool
	// Reads are other modules' state it reads, each `<module>.<name>` (novox/hq ADR 0201).
	Reads []string
	// ReadsRefused are the reads its manifest names that the owner's announcement does not make readable (novox/hq ADR
	// 0495 clause 3, issue 1790): granted nothing, kept to be said.
	ReadsRefused []string
	// ReadLogs are, of its reads, those naming another module's log (`<module>.<log>`, novox/hq ADR 0571 clause 1): filled
	// by Users and PlacementsOf from the logs the modules placed anywhere declare, never by a caller.
	ReadLogs []string
	// KeyedReads are keys of other modules' state it reads, each one key alone: what a seat's holder is
	// granted for the pieces the modules beside it offer (novox/hq ADR 0260).
	KeyedReads []KeyedRead
	// NoAccount says the module declares no own secret named broker, so no account could ever be
	// delivered to it and nothing can connect as it (novox/hq issue 195). Said in the negative so a
	// record that does not say is composed as it always was.
	NoAccount bool
	// SnapshotsTheBus says the module holds mesh-broker — it is the bus — and so is the one module
	// granted the snapshot API, to copy the bus's streams for the night's backup (novox/hq ADR 0235).
	SnapshotsTheBus bool
	// Checks are the module's own tools its health asks, each `<module>.<tool>` (novox/hq ADR 0240, to-be
	// 48 §3): the machine's node-engine asks them of its own node tools, and is granted that and no more.
	Checks []string
	// Loads says the module has a compiled bundle whose entrypoints the machine's tool runtime loads and runs
	// (novox/hq ADR 0175; issue 1329): a helper that reaches the bus on the runner's account, so the runner
	// must carry the module although it declares no tools.
	Loads bool
	// RunsAs is the account the module runs as in a runtime of its own (novox/hq ADR 0259 §8): it is never
	// carried by the machine's runtime, and reaches the bus on its own account.
	RunsAs string
	// ProvisionsNode says the module runs the machine's provisioner client: it claims NodeProvisionerSeat and
	// declares the own secret ProvisionerSecret its account is delivered in (novox/hq ADR 0349 clause 11, design 57
	// P3). The client is given a bus account of its own, never the module's or the tool runner's.
	ProvisionsNode bool
	// Processes are this module's own processes that declare bus (novox/hq ADR 0436 §1), each getting a
	// principal of its own: granted exactly what its bus says, and nothing of this module's other grants —
	// composed whether or not the module itself has an account (NoAccount), because a process account is
	// delivered in its own secret, broker-<process id>, never the module's `broker`.
	Processes []ProcessPrincipal
}

// ProcessPrincipal is one process of a module that declares bus (novox/hq ADR 0436 §1, §2), as the broker
// composes its own account from: its own emits, its own work-queue consumers, its own state, whether it
// reads the router's records of its module's own asks, and the tools and seat verbs it calls.
type ProcessPrincipal struct {
	// Process is the process resource's id, naming the account <node>.<module>.<process id>.
	Process string
	// Emits are the events this process may publish, named as the module's own Emits are.
	Emits []string
	// Queues are the module's own work-queue streams this process is the one consumer of.
	Queues []QueueOwner
	// Removes are what its account may remove from the bus, as its bus declares them (the indexer's judge refuses any other; novox/hq
	// ADR 0564 Limits 4): a tools bundle's account, whose whole authority is then BusRemovalGrants.
	Removes []string
	// State is the module's own state, by local name, this process reads and writes.
	State []string
	// Asks says whether this process reads the records of its module's own asks (novox/hq ADR 0259 §3), on
	// whichever seats the module uses that keep them (the router's, operator-channel, among others).
	Asks bool
	// Invokes are the tools and seat verbs this process calls, each <module>.<tool> or a role's
	// seat:<seat>.<verb>, or * for every tool on the mesh.
	Invokes []string
}

// VaultSeat is the vault's seat: its holder alone asks the desks and the issuing providers in its own name.
const VaultSeat = catalogue.VaultSeat