// Package membership is what the mesh issues an assignment to serve and to reach (novox/hq ADR 0160), as a // process reads it from the bus: the Membership shape, the one subject it is published on, the stream that // holds it, and the bus address helpers a reader needs. The controller composes it and the route proxy reads // it; both use this one definition, so there is no second copy to drift (novox/hq issue 1633). package membership import ( "encoding/json" "slices" "sort" "git.novox.be/novox/mesh-sdk/go/catalogue" ) // AssignmentsStream holds every assignment's membership, the newest per subject. const AssignmentsStream = "ASSIGNMENTS" // Subject is the one address a runtime derives for itself: where its own membership is published, from // the two names its credential carries. Everything else is in the membership. func Subject(node, module string) string { return "mesh.assignment." + node + "." + module } // DirectGetSubject is the subject-addressed direct get of a membership from its stream: the one request an // account may make of the stream. func DirectGetSubject(node, module string) string { return "$JS.API.DIRECT.GET." + AssignmentsStream + "." + Subject(node, module) } // Membership is one assignment's subjects: what this instance of a module on this machine serves, // and what it may reach. type Membership struct { Node string `json:"node"` Module string `json:"module"` // Serves is every address a tool of this instance answers on. `{tool}` stands for the tool's // own name. An address with a queue is shared with the module's other instances. Serves []Served `json:"serves"` // Seats is every verb of a seat this instance holds, at the subject the seat's callers use. Seats []SeatServed `json:"seats,omitempty"` // Emits is where an event of this module lands; `{event}` stands for the event's name. Emits string `json:"emits"` // Reaches is each tool this module may call, `.`, to the subjects that reach it. Reaches map[string][]string `json:"reaches,omitempty"` // Tools is where this instance answers what it serves. Tools string `json:"tools"` // Receives is what this assignment is given for each requirement it receives, by requirement (novox/hq // ADR 0167): kept as JSON because the catalogue owns the shape of a contribution. Receives map[string]json.RawMessage `json:"receives,omitempty"` // Mesh is every machine's address on the private network (novox/hq ADR 0167). Mesh []string `json:"mesh,omitempty"` // State is every bucket this module's code may reach, and whether it may write it (novox/hq ADR 0201). State []StateIssued `json:"state,omitempty"` // Objects maps the name of each old `objects` section of a foundation part to its object store, as State maps its // buckets (design 47 G §619). Objects map[string]string `json:"objects,omitempty"` // Logs is every log this module's code may reach (novox/hq ADR 0297). Logs []LogIssued `json:"logs,omitempty"` // SeatTraffic is what this module's code may submit, say, hear, take, ask, answer and read on seats // that name their caller or their kind (novox/hq ADR 0259 §3). SeatTraffic *SeatTraffic `json:"seat-traffic,omitempty"` // Streams are this module's own streams, Hears the module streams it hears (novox/hq ADR 0363). Streams []StreamIssued `json:"streams,omitempty"` Hears []HeardIssued `json:"hears,omitempty"` // Bindings are the module's bus state as the bus module created it, one per entry its manifest asks for in // `requires` (novox/hq ADR 0595 §1, §7): written by the grants part when it hears the bus module's `created`. Bindings []BusBinding `json:"bindings,omitempty"` } // BusBinding is one bus-state entry's names on the bus, by the local name its module asks for it by (novox/hq ADR 0595 // §1, design 25 § 12.2): the module names only locally, and reaches its own entries, and only those, through these. // Which names are set follows the storage type: a stream's Stream and Subject, a key-value bucket's Bucket, an object // store's ObjectStore, and a ledger's History, State, Indexes and Snapshot. type BusBinding struct { Local string `json:"local"` // Storage and Template are the entry's storage type and template (catalogue.Storage…, catalogue.Template…). Storage string `json:"storage"` Template string `json:"template,omitempty"` // Stream and Subject are a stream's name and the subject its messages are on; Subject is also a ledger's history's. Stream string `json:"stream,omitempty"` Subject string `json:"subject,omitempty"` // Bucket is a key-value bucket's name. Bucket string `json:"bucket,omitempty"` // Objects is the bus name of a state's `-objects` store (design 47 G §399, §642); the module's sent store is a // binding entry of its own, the local name `sent-objects`, its ObjectStore. Objects string `json:"objects,omitempty"` // ObjectStore is an object store's name. ObjectStore string `json:"object-store,omitempty"` // Ledger, for the storage type ledger: its history stream (one subject per instance), its state bucket, each // declared index's bucket by index name, and the subject of the instances' snapshots (ADR 0597 §1, §4, §8). History string `json:"history,omitempty"` State string `json:"state,omitempty"` Indexes map[string]string `json:"indexes,omitempty"` Snapshot string `json:"snapshot,omitempty"` // Types are a ledger's types, copied by the grants part from the entry the manifest-accepted event carries, so the // tool runner checks an operation against its type without reading another part's state (ADR 0596, ADR 0597 §1). Types []catalogue.LedgerType `json:"types,omitempty"` } // Served is one address a tool is answered on. type Served struct { Subject string `json:"subject"` Queue string `json:"queue,omitempty"` } // SeatServed is one verb of a held seat, where its callers ask. type SeatServed struct { Seat string `json:"seat"` Verb string `json:"verb"` Subject string `json:"subject"` } // StateIssued is one bucket an assignment may reach, by the name its module uses for it (novox/hq ADR 0201). // Key, when set, names the machine whose keys it may reach (novox/hq ADR 0260; design 46 7-approval-mark §13): that key and the // keys below it (buscompose.PerMachineKeys), no other machine's. // // PerNode says the state is kept one bucket per node (novox/hq ADR 0593 §6: `composed-`): Bucket is then the // buckets' prefix, each bucket the prefix and a node's name, and a key's first part names its node and so its bucket. // The runtime reads it as one state (as process.NodeFamily does): a key from its node's bucket, the keys and a watch over // every bucket of the family, one created later included. Read only: PerNode is never issued with Writes. type StateIssued struct { Name string `json:"name"` Bucket string `json:"bucket"` Writes bool `json:"writes,omitempty"` Key string `json:"key,omitempty"` PerNode bool `json:"per-node,omitempty"` } // LogIssued is one log an assignment may reach, by the name its module uses for it (novox/hq ADR 0297). type LogIssued struct { Name string `json:"name"` Stream string `json:"stream"` Subject string `json:"subject"` Writes bool `json:"writes"` } // Worker is one durable consumer a holder pulls a seat's work from. type Worker struct { Stream string Consumer string Filter string } // SeatTraffic is one module's seat traffic beyond tools. Publish and Subscribe are subject patterns, in the // server's wildcards. type SeatTraffic struct { Publish []string `json:"publish,omitempty"` Subscribe []string `json:"subscribe,omitempty"` Answers []string `json:"answers,omitempty"` Workers []Worker `json:"workers,omitempty"` Records []string `json:"records,omitempty"` Kinds []KindHeld `json:"kinds,omitempty"` } // KindHeld is one kind of a kinded bench and who holds it. type KindHeld struct { Seat string `json:"seat"` Kind string `json:"kind"` Module string `json:"module"` Node string `json:"node"` Capabilities []string `json:"capabilities,omitempty"` } // StreamIssued is one of a module's own streams as its membership names it (ADR 0363 §2). type StreamIssued struct { Stream string `json:"stream"` Events []string `json:"events"` Subject string `json:"subject"` } // HeardIssued is one module stream an assignment hears (ADR 0363 §8). type HeardIssued struct { Stream string `json:"stream"` Consumer string `json:"consumer"` } // StateIssued is the state this membership issues its module's code by a local name, and whether it does: what every // runtime that serves a module's state calls reads, so no reader keeps a second copy of the rule (novox/hq issue 1966). // An entry of the old `state` list wins (ADR 0201); otherwise a binding of a key-value entry the module asks for in // `requires` is issued by its local name, as its own and written (ADR 0595 §1, §11: a moved module keeps its local // names), on the bucket the bus module named. func (m Membership) StateIssued(name string) (StateIssued, bool) { for _, s := range m.State { if s.Name == name { return s, true } } for _, b := range m.Bindings { if b.Local == name && b.Storage == catalogue.StorageKeyValue && b.Bucket != "" { return StateIssued{Name: b.Local, Bucket: b.Bucket, Writes: true}, true } } return StateIssued{}, false } // StateNames are the local names StateIssued answers, the old list's and the key-value bindings', sorted, once each: // what a refusal names as issued. func (m Membership) StateNames() []string { var out []string for _, s := range m.State { out = append(out, s.Name) } for _, b := range m.Bindings { if b.Storage == catalogue.StorageKeyValue && b.Bucket != "" { out = append(out, b.Local) } } sort.Strings(out) return slices.Compact(out) }