// Package catalogue is what modules are, and what a node gets when it is assigned some. // // novox/hq ADR 0009: everything is a module, a module declares what it provides and requires, // and a module declares what it claims. This turns a set of assignments into the one declaration // a node is sent — which is the first thing the control plane decides rather than relays. package catalogue import ( "bytes" "encoding/json" "errors" "fmt" "regexp" "slices" "sort" "strconv" "strings" ) // Scopes a claim can have. // // Not everything singular is singular per machine: a seat is one per node, a DHCP server is one // per segment, and the hub is one per mesh. Scope says which, and it is the same idea the mesh // already enforces by hand for the hub. const ( ScopeNode = "node" ScopeSite = "site" ScopeMesh = "mesh" ) // Claim is a singular resource a module takes over. type Claim struct { Name string `json:"name"` // Scope defaults to the node, which is where nearly everything singular is singular. Scope string `json:"scope,omitempty"` // Serves names the seat's verbs this module implements for the role, when its own tools are // not the seat's (novox/hq ADR 0159, 0160): the store's `databases` is not postgres's // `postgres_list_databases`, and a holder may well serve both. The runtime serves an // implementation registered under the seat's name on the seat's subjects. Absent, the // module's own `tools` must list every verb the seat promises, which is how a module named // like its seat — the catalogue, the records — says they are one and the same. Serves []string `json:"serves,omitempty"` // Renders is how this holder writes each kind its seat receives as data, by kind: a Go // text/template over one piece — its fields and `module` — in the tool's own grammar (novox/hq ADR // 0255). The data is the mesh's, the format the holder's, as a module's facts template is. Renders map[string]string `json:"renders,omitempty"` // Kind is the kind this module holds a kinded bench as (novox/hq ADR 0234 §2, ADR 0259): `telegram`, // `desktop`. Refused on any other seat, and a second claim of one kind is refused. Kind string `json:"kind,omitempty"` // Capabilities are what a channel of this kind promises, from the fixed vocabulary // channel-capabilities/1 (novox/hq ADR 0234 §2): the router judges an answer by these, read from the // controller's record of this claim and never from the channel. Capabilities []string `json:"capabilities,omitempty"` } // ServesFor is what this claim offers a seat's protocol: the verbs it names, else the module's // own tools. func (c Claim) ServesFor(m Manifest) []string { if len(c.Serves) > 0 { return c.Serves } return m.Tools } // At is this claim's scope, with the default applied. func (c Claim) At() string { if c.Scope == "" { return ScopeNode } return c.Scope } // Modes an access may be granted at. // // **The grant states its extent, the way a listening port states its source** (the rule the // manifest already keeps for `listens.from`). Absent narrows to read — the safe default, because // the danger with an access is being given more than was meant, not less. const ( AccessRead = "read" AccessReadWrite = "read-write" ) // Access is a pre-existing path on the machine that this module is GRANTED USE OF, and does not // own. // // **The distinction this exists for** (novox/hq ADR 0051, 04-ISSUES/036): a `directory` resource // is a thing the mesh owns — it creates it, sets its owner and mode, and removes it when it is // empty and no longer declared ([ADR 0030](novox/hq)). Shared, pre-existing data is none of that. // A media library, a download spool, an ingest folder is the **operator's**: it existed before the // mesh, several modules read and write it at once, and the mesh must not create, chown, reconcile // or remove it. It mounts it and owns nothing about it. // // Written as its own field rather than a flag on a directory because the two are opposite on every // axis the host acts on, and 04-ISSUES/026 records what happens when *the directory my data lives // in* and *a facility I was granted* are spelled the same: the second gets created as root and the // ownership fields silently do not apply. Two modules may name the same access with no conflict — // that is the whole point of it — whereas two owning one path is the fault the resolver refuses. // // If the path is absent when a machine applies, the host refuses clearly rather than creating it: // the mesh does not own it, so conjuring it would be a lie the host then acts on. type Access struct { // ID is the name the module gives this access, which the assignment places // (`accesses: {: }`, novox/hq ADR 0112, issue 153) and the module's mounts name as // ${access:}. The shape a definition should use: it names no path of any machine. ID string `json:"id,omitempty"` // Path is the absolute path on the machine. A definition carrying one names an installation; // tolerated as the default the assignment may replace, for accesses declared before ids. Path string `json:"path,omitempty"` // Mode is "read" or "read-write". Absent narrows to read. Mode string `json:"mode,omitempty"` } // At is this access's mode, with the default applied. func (a Access) At() string { if a.Mode == "" { return AccessRead } return a.Mode } // Offer is something a module provides, and where the answer to it may live. // // **The distinction this exists for:** a shell, a display server and a private network have to be // on the machine that needs them. A database, an object store and an identity provider do not — // they run somewhere in the mesh and are reached over it. Treating the second as the first // installs PostgreSQL on every machine that runs a web application, which is what happened until // this field existed. // // Written as a bare string in the ordinary case, because nearly everything is node-scoped and // making every manifest say so would bury the few that are not: // // "provides": ["shell"] // "provides": [{"name": "postgres-database", "scope": "mesh"}] type Offer struct { Name string `json:"name"` // Scope defaults to the node, which is where most things must be to be usable. Scope string `json:"scope,omitempty"` // Credential, when set, says this provision's credential is one of the provider's own secrets, // shared by every consumer (novox/hq ADR 0158): software that holds one password or one key // cannot give each consumer a login of its own. The named secret must say how it is taken. Credential *OfferCredential `json:"credential,omitempty"` // Reach is ReachMachine for a provision usable only on the provider's own machine — a display // (novox/hq ADR 0208 §3). Node scope already keeps a provision off other machines; what this adds // is that a requirement for it is never answered by installing a provider: the display server is // a seat's holder gated by the machine's graphical session, and pulling one in for whatever asked // is the misassignment research 026 found. Unmet, the requirement is refused naming who could. Reach string `json:"reach,omitempty"` // Identity is the longest consumer identity this provision's backend keeps (novox/hq ADR 0225): // `{"max": 63, "in": "a PostgreSQL role"}`, or `false` for a provision that keeps no name derived // from its consumer. Unsaid, the mesh assumes the tightest backend it knows when the provider is // told its consumers, and no bound when it is not — see IdentityBoundOf. Identity *OfferIdentity `json:"identity,omitempty"` // KeepsConsumerData says whether this provision's provider keeps what its consumers write — a // database's rows, a bucket's objects, a client's settings — so that a consumer bound to it is // bound to its data, and moves only by a person (novox/hq ADR 0232). `false` for a provision any // provider answers alike, the mesh's resolver; unsaid, see KeepsConsumerData. KeepsConsumerData *bool `json:"keeps-consumer-data,omitempty"` // AnsweredBy says who answers this provision's consumers: AnsweredByHelper when the module runs the SDK's provider // helper for it, so a handed consumer's template may name what the provider tells it (`${bound::}`) // from the helper's entry on the bus (issue 792). It is separate from `moved`: it hands none of the module's own // files. Unsaid, the controller answers the consumer. AnsweredBy string `json:"answered-by,omitempty"` } // AnsweredByHelper is the only answerer an offer may name besides the controller. const AnsweredByHelper = "helper" // OfferIdentity is what an offer says about the names its backend keeps for its consumers. type OfferIdentity struct { // None is set by `"identity": false`: the provision keeps no name derived from its consumer. None bool // Max is the longest identity kept, in characters; zero with In set means no limit worth stating. Max int // In is what keeps it, for a refusal to quote. In string } // UnmarshalJSON accepts `false` or `{"max": N, "in": "..."}`. func (i *OfferIdentity) UnmarshalJSON(raw []byte) error { var flag bool if err := json.Unmarshal(raw, &flag); err == nil { if flag { return errors.New("an offer's identity is false (it keeps no name) or {max, in}; true says nothing") } *i = OfferIdentity{None: true} return nil } var full struct { Max int `json:"max,omitempty"` In string `json:"in"` } dec := json.NewDecoder(bytes.NewReader(raw)) dec.DisallowUnknownFields() if err := dec.Decode(&full); err != nil { return fmt.Errorf("an offer's identity is false or {max, in}: %w", typedUnknown(err)) } *i = OfferIdentity{Max: full.Max, In: full.In} return nil } // MarshalJSON writes it back in the form it was written. func (i OfferIdentity) MarshalJSON() ([]byte, error) { if i.None { return []byte("false"), nil } return json.Marshal(struct { Max int `json:"max,omitempty"` In string `json:"in"` }{i.Max, i.In}) } // IdentityBoundOf is the bound this module's offer of a provision puts on its consumers' identities // (novox/hq ADR 0225). // // **What an offer says, it gets.** Where it says nothing, the bound follows from whether the // provider can keep a name at all: a provider that receives the provision, or serves its consumers // a value built from their identity, is told who each consumer is and may create a name from it in // a backend nobody measured — so it keeps the old global bound, DefaultIdentityBound. One that does // neither is told nothing about its consumers and keeps nothing of them: no bound. The resolver // provision is that case, and its consumers paid an object store's limit until this (issue 263). func (m Manifest) IdentityBoundOf(provision string) IdentityBound { for _, o := range m.Provides { if o.Name != provision || o.Identity == nil { continue } if o.Identity.None { return IdentityBound{} } return IdentityBound{Max: o.Identity.Max, In: o.Identity.In} } if _, receives := m.Receives[provision]; receives { return DefaultIdentityBound } if served, err := json.Marshal(m.Serves[provision]); err == nil && bytes.Contains(served, []byte("${consumer:as")) { return DefaultIdentityBound } return IdentityBound{} } // KeepsConsumerData is whether a provision, by name, keeps its consumers' data across the // catalogue: true when any module providing it at the mesh's scope does. **A property of the name**, // as brokering is: two providers disagreeing would make the same binding sticky or free depending on // which one happened to answer it, and the safe reading of a disagreement is that it keeps data. func KeepsConsumerData(catalogue map[string]Manifest, provision string) bool { for _, m := range catalogue { for _, o := range m.Provides { if o.Name == provision && o.At() == ScopeMesh && m.KeepsConsumerData(provision) { return true } } } return false } // MachineReach is whether a provision is usable only on its provider's own machine. func (o Offer) MachineReach() bool { return o.Reach == ReachMachine } // OfferCredential names which of the provider's own secrets a provision's consumers receive — or, with // IssuedBy "outside", that only a person can give the provision's credential (novox/hq ADR 0337, issue 164) — or, // with IssuedBy "software", that the provider's software issues the provision's one credential itself (novox/hq ADR 0305, // issue 526): a media server's sign-in token from its vendor, which the mesh can neither make nor rotate. // Tool is then the provider's own tool that answers that value, sealed to a key made for the controller's // one call, and to the controller alone. type OfferCredential struct { Own string `json:"own,omitempty"` IssuedBy string `json:"issued-by,omitempty"` Tool string `json:"tool,omitempty"` // Form says, for an offer that names no own secret and no issuer, which it is: CredentialFormPair, a login of // each consumer's own, or CredentialFormNone, no credential at all (the lead, 2026-10-29, for novox/hq ADR 0570): // never left to a default. Form string `json:"form,omitempty"` } // IssuedBySoftware says a provision's credential is issued by its provider's software (novox/hq ADR 0305). const IssuedBySoftware = "software" // IssuedCredentialOf is the tool through which this module answers the credential its software issued for a // provision, and whether its offer says the software issues it (novox/hq ADR 0305). func (m Manifest) IssuedCredentialOf(provision string) (string, bool) { for _, o := range m.Provides { if o.Name == provision && o.Credential != nil && o.Credential.IssuedBy == IssuedBySoftware && o.Credential.Tool != "" { return o.Credential.Tool, true } } return "", false } // CredentialToolOf is the tool a plan names for a provision, set only where the offer says the provider's software // issues its credential (issue 928); empty otherwise. func (m Manifest) CredentialToolOf(provision string) string { tool, _ := m.IssuedCredentialOf(provision) return tool } // IssuedOutsideOf is whether this module's offer of a provision says only a person outside the mesh can give its // credential (novox/hq ADR 0337): the mesh never makes a value for it, and a consumer holds one only once a person // gave it with `secret accept`. func (m Manifest) IssuedOutsideOf(provision string) bool { for _, o := range m.Provides { if o.Name == provision && o.Credential != nil && o.Credential.IssuedBy == IssuedOutside { return true } } return false } // SharedCredentialOf is the own secret an offer of this module names as the provision's credential, // and whether it names one. func (m Manifest) SharedCredentialOf(provision string) (string, bool) { for _, o := range m.Provides { if o.Name == provision && o.Credential != nil && o.Credential.Own != "" { return o.Credential.Own, true } } return "", false } // The credential forms an offer declares (issue 768), as a consumer's plan names them for the vault, which makes // a first value in that form for a provider it holds no row of. const ( // CredentialFormShared is one of the provider's own secrets, shared by every consumer (novox/hq ADR 0158). CredentialFormShared = "shared" // CredentialFormPair is a login of its own for each consumer (novox/hq ADR 0048, ADR 0158 §11): the offer says // no credential. CredentialFormPair = "pair" // CredentialFormIssued is issued by the provider's software (novox/hq ADR 0305); the mesh never makes it. CredentialFormIssued = "issued" // CredentialFormGiven is given by a person (novox/hq ADR 0337): the offer's credential, or the own secret it // shares, is issued outside the mesh; the mesh never makes it. CredentialFormGiven = "given" // CredentialFormNone is an offer whose consumers present no credential: its outcome is the provider's have, and // the vault mints nothing for it. CredentialFormNone = "none" ) // CredentialForms is the one list of the credential forms a plan's entry may name (issue 774): every part that reads // a plan checks a form here, so a form added above reaches each of them at once. Each part kept its own copy before, // and a copy left without "none" refused every plan naming it. func CredentialForms() []string { return []string{CredentialFormShared, CredentialFormPair, CredentialFormIssued, CredentialFormGiven, CredentialFormNone} } // IsCredentialForm is whether form is one of CredentialForms. func IsCredentialForm(form string) bool { return slices.Contains(CredentialForms(), form) } // CredentialFormOf is the credential form this module's offer of a provision declares, read from the offer's // `credential` alone (issue 768): no new manifest field, since that field already says whether the provider shares // one of its own secrets, its software issues it, or a person gives it, and saying none is a login per consumer. // "" when the module does not offer the provision. func (m Manifest) CredentialFormOf(provision string) string { for _, o := range m.Provides { if o.Name != provision { continue } switch c := o.Credential; { case c == nil: return "" // undeclared: refused at the catalogue (CredentialFormProblems), never read as a pair case c.IssuedBy == IssuedOutside: return CredentialFormGiven case c.IssuedBy == IssuedBySoftware: return CredentialFormIssued case c.Own != "" && m.OwnSecrets[c.Own].IssuedBy == IssuedOutside: return CredentialFormGiven case c.Own != "": return CredentialFormShared } return o.Credential.Form } return "" } // ProvisionsSharing is every provision of this module whose credential is the named own secret. func (m Manifest) ProvisionsSharing(own string) []string { var out []string for _, o := range m.Provides { if o.Credential != nil && o.Credential.Own == own { out = append(out, o.Name) } } sort.Strings(out) return out } // At is this offer's scope, with the default applied. func (o Offer) At() string { if o.Scope == "" { return ScopeNode } return o.Scope } // UnmarshalJSON accepts a plain name as well as an object. func (o *Offer) UnmarshalJSON(raw []byte) error { var plain string if err := json.Unmarshal(raw, &plain); err == nil { o.Name, o.Scope = plain, "" return nil } var full struct { Name string `json:"name"` Scope string `json:"scope,omitempty"` Credential *OfferCredential `json:"credential,omitempty"` Reach string `json:"reach,omitempty"` Identity *OfferIdentity `json:"identity,omitempty"` Keeps *bool `json:"keeps-consumer-data,omitempty"` AnsweredBy string `json:"answered-by,omitempty"` } dec := json.NewDecoder(bytes.NewReader(raw)) dec.DisallowUnknownFields() if err := dec.Decode(&full); err != nil { return fmt.Errorf("a provided name is either a string or {name, scope, credential, reach, identity, "+ "keeps-consumer-data, answered-by}: %w", typedUnknown(err)) } if full.AnsweredBy != "" && full.AnsweredBy != AnsweredByHelper { return fmt.Errorf("%s says answered-by %q: the only answerer an offer names is %q", full.Name, full.AnsweredBy, AnsweredByHelper) } o.AnsweredBy = full.AnsweredBy o.Name, o.Scope, o.Credential, o.Reach, o.Identity = full.Name, full.Scope, full.Credential, full.Reach, full.Identity o.KeepsConsumerData = full.Keeps return nil } // MarshalJSON writes back the short form when there is nothing else to say, so a manifest that // went through the mesh comes out looking like the one that went in. func (o Offer) MarshalJSON() ([]byte, error) { if o.Scope == "" && o.Credential == nil && o.Reach == "" && o.Identity == nil && o.KeepsConsumerData == nil && o.AnsweredBy == "" { return json.Marshal(o.Name) } return json.Marshal(struct { Name string `json:"name"` Scope string `json:"scope,omitempty"` Credential *OfferCredential `json:"credential,omitempty"` Reach string `json:"reach,omitempty"` Identity *OfferIdentity `json:"identity,omitempty"` Keeps *bool `json:"keeps-consumer-data,omitempty"` AnsweredBy string `json:"answered-by,omitempty"` }{o.Name, o.Scope, o.Credential, o.Reach, o.Identity, o.KeepsConsumerData, o.AnsweredBy}) } // AnsweredByHelperFor is whether this module's offer of a provision says its consumers are answered by the provider // helper (issue 792). func (m Manifest) AnsweredByHelperFor(provision string) bool { for _, o := range m.Provides { if o.Name == provision && o.AnsweredBy == AnsweredByHelper { return true } } return false } // Manifest is everything a module says about itself. type Manifest struct { Module string `json:"module"` Version string `json:"version,omitempty"` // Slug is a short identifier the mesh uses in place of the module name when it derives a // consumer's login (novox/hq ADR 0049). Optional: a module with a short name needs none. It // exists because `mesh__` must fit the bound of every provision the module // requires — an S3 access key's 20 characters is the tightest — and a long module name would // overflow it (ADR 0225: the bound is the provision's own, and a keyless one has none). A person // choosing `kc` for keycloak keeps the identity legible where a hash would not. Slug string `json:"slug,omitempty"` // NeedsApproval marks tools the module serves (``), seat verbs it serves (`.`) and events it // emits that need the operator's approval first (design 46 *The approval mark* §1; design 34 every-event §32). Absent // is no mark. NeedsApproval []string `json:"needs-approval,omitempty"` // Provides are the names other modules may require. A module always provides its own name; // this is for the rest — `zsh` provides `shell`, `xorg` provides `display-server`. Provides []Offer `json:"provides,omitempty"` // Packages are the series of each mesh package this module accepts, by the package's name (novox/hq ADR 0606, // design 32): its fingerprint takes the newest version of that series, and a publish of another series moves it // not. A package it uses and does not name is accepted in DefaultSeries (AcceptedSeries). Packages map[string]string `json:"packages,omitempty"` // Requires are names that must be provided by something assigned to the same node. Requires []string `json:"requires,omitempty"` // OptionalRequires is which of Requires the module can run without (novox/hq ADR 0330): filled // by UnmarshalJSON from the long form of a `requires` entry, {name, optional}, or from the stored // form's `optional-requires` list; never written by hand. OptionalRequires map[string]bool `json:"-"` // RequireShares is who else may use the bucket a module requires, by requirement (BucketShare, novox/hq ADR 0468 // §8): filled from the long form's `shares`, or from the stored form's `requires-shares`; never written by hand. RequireShares map[string][]BucketShare `json:"-"` // BusState is what the module keeps on the bus, each entry asked for in `requires` in its typed long form // (BusStateEntry, novox/hq ADR 0595 §1); its local name is never in Requires, which names provisions. Stored // beside `requires` (BusStateField), which stays a plain list of names. BusState []BusStateEntry `json:"bus-state,omitempty"` // Emits are the events this module publishes, named **locally**: `order.placed`, not a subject // and not a routing key. The mesh derives where it lands (design 29 §1), so reorganising the // subject space leaves this manifest correct. Events are provisioning's lighter sibling — 1:many // and broadcast, no credential (novox/hq ADR 0041). // // A module publishes under its own name only. If the event is about a *role* rather than about // this module, it belongs on that seat, where the name outlives whoever holds it. // // **This said "dotted topic keys, e.g. module.umami.site.created" until 04-ISSUES/127**, which // is the old bus's routing key, and is why every manifest in the catalogue had the same mistake: // nobody was guessing, everybody followed this comment. Emits []string `json:"emits,omitempty"` // Consumes are the events this module reacts to, each naming its emitter and the event: // `billing.order.placed`. `*` stands for one name and `**` for the rest, so `*.download.completed` // is that event from any module and `**` is every event in the mesh. // // Spelled the mesh's way rather than the wire's, for the reason Emits is: the bus the mesh runs // on today spells these `*` and `#`, the one being built spells them `*` and `>`, and a manifest // naming either would stop being true when the wire changed. // // The runtime wires the subscription; the module ships the handler. A Consumes for an event // nothing on the mesh Emits is a dangling edge. Consumes []string `json:"consumes,omitempty"` // Claims are singular resources. Two modules claiming one thing within a scope cannot both // be assigned there — which is how exclusivity is expressed, rather than as a list of rivals // that every new module would force its predecessors to update. Claims []Claim `json:"claims,omitempty"` // DefinesSeats are the seats this module defines for itself, with their protocols // (novox/hq ADR 0121, ADR 0129). The control plane defines the system seats — `mesh-*` and // `node-*` — and a module may define its own, named outside that namespace, to coordinate its // own instances: the mesh enforces one-holder-per-scope for it without knowing what it means. A // module's declared seat is the only non-system name it may then claim; a claim to a name // neither the mesh nor the module defines is refused. // // **Two lines of work built this at once**, one calling it `Seats` with a protocol and one // `DefinesSeats` without. Same key in the file, so no manifest is affected: this is the trunk's // name with the richer type, because what a role accepts, emits and serves is what lets the mesh // check that a holder answers what its seat promises. DefinesSeats []SeatDeclaration `json:"seats,omitempty"` // Uses are seats this module sends to. It names the *seat*, never the module holding it, so // the implementation can be replaced under it and no caller changes. A caller gets publish // on that seat's inbound subjects and nothing else — not its outbound events, and not a // subscription to the queue it writes to (design 29 §2). Uses []string `json:"uses,omitempty"` // Prepares says this module has state that must be brought to the shape this version needs // before this version runs, and that the module's own code does it (novox/hq ADR 0135). // // **A word, not an arrangement.** The mesh runs the module's own program in its preparation // mode, in the module's own context — every binding, credential and setting its code receives, // because it *is* its code. Nothing here names a container, a command, a mount or a variable: // the module already said all of that once, and a second copy is a second thing to drift. // // **Declared, never inferred.** The control plane cannot read what is inside an artifact, so a // module that ships a migration and does not say this breaks on its first upgrade. That is // stated in the record rather than guarded here, because nothing mechanical can guard it. Prepares bool `json:"prepares,omitempty"` // Tools are the tools this module answers — request and reply, awaited. // // **New, and not `serves`**, which this manifest already uses for the facts a consumer needs // in order to reach a provision. Two meanings under one key would be a footgun in the one // file a module author reads most. Until now a module's tools were known only at runtime, // from MESH_TOOL_MODULES in its image; declaring them is what lets the mesh check that a // module claiming a seat answers what that seat's protocol promises (novox/hq ADR 0118). Tools []string `json:"tools,omitempty"` // Replaces says, for a tool of this module's own, the shell commands it is the mesh's way to do — // `{"docker_logs": ["docker logs"]}` — as a seat's verb says it in its definition (novox/hq ADR // 0241). A seat's verb carries its own: what a role replaces is the role's, so a module never says it // for a verb it serves under a claim. The console's search, the agent's instructions and the guard on // its shell are built from both. Replaces map[string][]string `json:"replaces,omitempty"` // Instances says whether this module's instances are the same anywhere — `interchangeable` — // so a call that names no machine may be answered by any of them (novox/hq ADR 0160). A fact // about the software, not about the bus: a stateless web tool says it; a database does not, // and its instances are then each addressed by machine, never confused for one another. Instances string `json:"instances,omitempty"` // Invokes are the tools this module calls, each `.` or a role's `seat:.`, // or the single entry `*` for every tool on the mesh (novox/hq ADR 0152, ADR 0154). // // **A grant, and only a grant.** The bus lets this module publish exactly those tool subjects // and nothing beside them — no event, no subscription, no seat. A module that declares none // calls nothing, which is every module but the console today. ADR 0095 made the control plane // the one caller and deferred this until a consumer asked; the console is that consumer, and a // person's account (design 25 §7) already had the same shape. Invokes []string `json:"invokes,omitempty"` // InvokeFields maps a verb of Invokes to the fields it names, read from an entry of `invokes` in its long form // {verb, fields}, which may stand beside `*` (design 47 G §617): Invokes keeps the verb, so none of its readers // changes. A long-form entry naming no field is a verb of Invokes alone. InvokeFields map[string][]string `json:"-"` // State is the current state this module keeps on the bus, by local name: each a key-value // bucket the controller creates, which every instance of the module writes and reads // (novox/hq ADR 0201). Not history — that is an event — and never a secret, sealed or not. State []StateDeclaration `json:"state,omitempty"` // Logs are the logs of operations this module keeps on the bus, by local name: each a stream the // controller creates and never removes, which every instance of the module appends to and reads // (novox/hq ADR 0297). A log is its owner's alone: no other module reads it. Logs []LogDeclaration `json:"logs,omitempty"` // Streams are the streams this module owns on the bus (novox/hq ADR 0363): each named locally, the // events it carries named as `emits` names them but with `*` and `**`, and bounded in age and size; the // controller creates each. One may be restricted by a trusted setting of this module, so a consumer // hears a part of it only where that setting's value names it. Streams []StreamDeclaration `json:"streams,omitempty"` // Objects are the object buckets this module owns on the bus (novox/hq ADR 0592 §5): each named locally and // bounded in size; the mesh creates each once, with no age limit, and refuses a new object when it is full. Only its // module writes it; another reads it only through a `reads` entry and the bucket's grant (ADR 0592 §9). Objects []ObjectsDeclaration `json:"objects,omitempty"` // Settings are the defaults this module gives its settings (novox/hq ADR 0262): each key a file, // a contribution or a served fact asks for as `${setting:}`, its default, and why that // default. Only a preference has one — a font size, a width, a number of workers — and a value // that is inherently the operator's (a domain, an identity, a secret) is declared nowhere here and // stays refused by name until a layer sets it. The mesh's layer, then the node's, override it. Settings map[string]SettingDeclaration `json:"settings,omitempty"` // forms is which of the two forms its config is written in, `config` or its alias `settings` (config.go, // novox/hq ADR 0348 §1): the config form is read into Settings, a mergeable file's takes-settings and // `${setting:}`, and written back as it was read. forms configForms // unknown is the first key this manifest has that this controller does not know, at any depth, when // it was read from the store (novox/hq ADR 0262): a manifest a newer controller registered. // ParseManifest refuses it; the store's catalogue still loads, and the module is left out of every // machine's declaration by name until the controller is updated (LeftOut). unknown string // predefined is the list of predefined keys it was judged against (predefined.go, novox/hq ADR 0348 §7): // read again — its templates filled from the tree — it is judged against the same list. predefined PredefinedList // BestEffort marks the view of a left-out module that only its backup lines are made from // (backupView, novox/hq ADR 0262): a line of it that cannot be placed is said in the plan's list of // what could not be placed, never an error that would cost the whole machine its declaration. BestEffort bool `json:"-"` // Data is every kind of data this module keeps — its own, by directory, and what it keeps for // its consumers, by provision — each with a class the mesh protects and watches it by (novox/hq // ADR 0233). One list: the backup holder's lines, the bindings that do not move, what an // unassignment retires and what the self-check measures are all derived from it. Data *Data `json:"data,omitempty"` // Upgrade is how this module's new builds reach its machines (novox/hq ADR 0236): rolled out one // machine first and gated when unsaid; `together`, or `record` — wait for a person's push — with // why. A person's choice through the `upgrade` verb stands over it. The bus says `record` itself. Upgrade *UpgradePolicy `json:"upgrade,omitempty"` // Unhealthy is how loud this module's unhealthy condition is (novox/hq ADR 0355): a warning when unsaid; // `urgent`, with why, for a module whose failure costs people something they rely on. Unhealthy *UnhealthyPolicy `json:"unhealthy,omitempty"` // Reads are other modules' state this module reads and watches, each `.` // (novox/hq ADR 0201). Read-only: only the owner's instances write. Reads []string `json:"reads,omitempty"` // Capabilities the machine must have. A different field from Requires because the remedy // differs: a missing module can be assigned, and a missing capability means the wrong // machine. Capabilities []string `json:"capabilities,omitempty"` // Resources are what this module puts on a node, in the host's own vocabulary. Resources []map[string]any `json:"resources,omitempty"` // Accesses are pre-existing, operator-owned paths this module is granted use of but does not // own — a shared media library, a download spool (novox/hq ADR 0051). Distinct from a // `directory` resource, which the mesh creates and owns: an access is mounted and nothing // about it is reconciled, and several modules may name the same one without conflict. Accesses []Access `json:"accesses,omitempty"` // Computed names something in the control plane that works this module's resources out per // node, instead of them being fixed here. // // Because some files cannot be written in advance. A machine's peer list on the private // network is derived from every other machine, so it differs on each one and changes when any // of them changes — there is nothing to put in a manifest. // // Being a module anyway is the point: it is assigned like anything else, so a machine that // should not be on the private network simply is not given it, and the network is worked out // over the machines that have it. Before this, connectivity was code beside the module system // doing the same job, and every machine with an address was on the network whether or not // anybody wanted it there. Computed string `json:"computed,omitempty"` // Contributes is what this module tells whatever answers a requirement. // // The other half of an edge. `requires` says a thing must be there; this says what to do with // it — a web application requiring a reverse proxy has to say *which name, which port*, and // until now there was nowhere to put that. Every module that needed it was reduced to // reaching into the control plane's database directly, which is how two of them came to hold // a credential to it permanently. // // Keyed by the requirement, because that is what the contribution is *about*. Contributing to // something is requiring it: asking to be published means a publisher must exist, and a // module that had to say both would eventually say one. Contributes map[string]map[string]any `json:"contributes,omitempty"` // ContributesMany is the same key, `contributes`, where a module tells one provider several // things under local names — `"route": {"api": {"label": "files-api", "port": 9000}, "console": // {"label": "files", "port": 9001}}` — because a module may answer one requirement more than // once: an object store with a data API and a console are two different public names, not one // (novox/hq ADR 0094's sibling for `contributes` rather than `secrets` — "a module may need more // than one value from a provider that gives one per pair" applies exactly as well to what a // module gives a provider as to what it keeps from one). Each local name is a contribution of // its own, reaching the provider as its own entry in the file it receives. // // Filled from the manifest's `contributes` object by UnmarshalJSON; never written by hand. ContributesMany map[string]map[string]map[string]any `json:"-"` // Receives is where this module wants its consumers' contributions written, per requirement // it provides. // // A file, in the mesh's own shape, replaced whenever the set changes. **The control plane // does not know what a reverse proxy is** and does not write one's configuration — it // delivers the facts, and the module turns them into whatever it runs. That boundary is why // swapping the proxy does not touch a single module that publishes through it. Receives map[string]string `json:"receives,omitempty"` // Serves is what a consumer needs to know in order to use something this module provides — a // port, a path, a realm. The module's half of the answer; the mesh adds the other half, which // is *which machine* and *where it is on the private network*. // // It does not carry a credential and cannot: a manifest is the same on every mesh, and a // secret is the one thing that must not be. Serves map[string]map[string]any `json:"serves,omitempty"` // Build says how this module's artifacts are produced from its source. // // The manifest in a repository names artifacts; the manifest the mesh holds names digests. // **They are not the same document**, and that is deliberate: a digest is not knowable until // something is built, and a repository that carried one would be a repository whose file is // wrong the moment anybody edits anything. Build *Build `json:"build,omitempty"` // Templates is the module's directory its template files are kept in, and its build packs into its templates // archive: files/ when it says none (DefaultTemplatesDir; novox/hq ADR 0349 §2, issue 731). A module whose files/ // is already an archive unpacked onto the machine names another, so its templates neither land beside what it // unpacks nor change that archive's digest. A word of the repository's manifest only, like Build: the manifest // the mesh holds carries each file's text and names no templates directory. Templates string `json:"templates,omitempty"` // Moved marks a module handed to the provisioner (novox/hq ADR 0349 §17, design 57 P6): each of its files that // names a template is filled on the node by the provisioner's client, and the controller fills nothing in it. // Handed is what its build kept for that (handed.go): written by Resolve, never in a repository. Moved bool `json:"moved,omitempty"` Handed *Handed `json:"handed,omitempty"` // TemplatesDigest is the digest of the archive a templated module's files were rendered from, "sha256:": written // by Resolve, never in a repository; the composition names it (design 47 G A-481, A-481a). TemplatesDigest string `json:"templates-digest,omitempty"` // Binds is where this module wants to be told about something it requires, per requirement. // // Because "this machine needs a database from the anchor" is useless to the program that // needs it unless the program is told. A file, like everything else — the host writes files // and knows nothing about provisions, which is what keeps this from needing anything new // down there. Binds map[string]string `json:"binds,omitempty"` // Secrets is where this module wants the credential for something it requires, per // requirement. The file holds the value and nothing else, so a program can read it without // parsing anything. // // **Its own file, separate from Binds, because the mesh cannot compose a document containing // it.** The value was sealed to this node when it was made and the plaintext discarded — so // there is nothing to interpolate into a larger file, and that is the property worth keeping // rather than an inconvenience to work around. It also means the readable half stays readable // in the declaration, and the secret half changes only when the secret does, which is what // makes `restart-on` precise. Secrets map[string]string `json:"secrets,omitempty"` // SecretsMany is the same key, `secrets`, where a requirement maps to SEVERAL files under local // names — `"secret": {"admin": "/…/admin", "token": "/…/token"}` — because a module may need // more than one value from a provider that gives one per pair (novox/hq 04-ISSUES/069, ADR // 0094). Each local name is a pair credential of its own, keyed on that name, delivered as its // own file, served to the provider as its own holder, and rotated with the others. Filled from // the manifest's `secrets` object by UnmarshalJSON; never written by hand. SecretsMany map[string]map[string]string `json:"-"` // OwnSecrets are secrets this module needs in order to be itself, and where to put them. // // **Named for whose they are, not how secret they are.** `secrets` above is a credential for // reaching something else, keyed by the provision it belongs to. These are keyed by a name the // module chose and belong to nobody else. Both were `map[string]string` of name to path, and // the field was called `needs` — so reaching for the wrong one parsed cleanly and failed // somewhere else entirely, which is the shape of fault this whole design exists to prevent. // // Not tied to a consumer. A database has a superuser password, a broker has an administrator, // a registry has an account — each is a secret the module needs in order to be itself, and // none of them is *for* anybody. Keyed by a name of the module's choosing, valued by the file // it lands in. // // **Generated per node and sealed to it**, like everything else the mesh hands out, so a // module running on three machines has three passwords and the mesh can read none of them. A // manifest carrying one instead would put the same secret on every machine that ever runs the // module, in a file anybody can read, for ever. // // **And how the module takes it** (novox/hq ADR 0114, issue 180): `"admin": ""` says // where and nothing else; `"admin": {"path": "", "taken": "at-start"}` says the module // reads the file when it starts, so the mesh may rotate it by making a new value and starting // the module again; `"taken": "applied"` says the module's own code applies it to a backend // that takes it only once, so a rotation must be staged beside the current value — the form the // mesh does not build yet, and refuses by name. A secret that says neither is not rotated by // the mesh: the one fault worse than an unrotated credential is a rotated one the software // never saw. `"issued-by": "outside"` says a party outside the mesh issues the value — an API // key, a bot token, a licence — so the mesh never puts one of its own in its place (novox/hq // ADR 0228); any other at-start secret given by hand lives only until the module's first good // start, and is then replaced. OwnSecrets OwnSecrets `json:"own-secrets,omitempty"` // ToolRunner says this module is the node's tool runner (issue 774): the one program on each node that loads every // assigned module's tools bundle, served by its runtime process. Said by // the module, never by a name in mesh-sdk. ToolRunner bool `json:"tool-runner,omitempty"` // CoreCredentials says this module's own secrets are the core's credentials (novox/hq ADR 0349 §16, issue 755): the // vault seals each to the machine, and the node-engine writes the vault's box into its file, never a value of its // own (Rendering.VaultSealed). Said by the module, never by a list in mesh-sdk (the operator, 2026-11-03: mesh-sdk names // no module): the bus and the provisioner and its client say it. CoreCredentials bool `json:"core-credentials,omitempty"` // SecretsOwner is who the files holding this module's secrets belong to on the machine — // `uid:gid`, or a name — when its process is not root. // // **A secret reaches a process as a file** (novox/hq ADR 0086), and a file the host writes at // 0600 as root is a file a container running as another account cannot read: the control // plane, `USER 65534` in a scratch image, crash-looped on `permission denied` the first time // its credentials were mounted instead of read from an env-file (which the daemon reads, as // root, on the host side — which is exactly why that shape hid the problem). Absent means // root, which is what a process that runs as root needs and what a process that does not // cannot use. SecretsOwner string `json:"secrets-owner,omitempty"` // RunsAs is the account this module's tools bundle runs as, in a runtime of its own on a bus account of // its own (novox/hq ADR 0259 §8): never the machine's runtime, which runs as the operator's account and // carries every module on the machine. The account is one the module makes (a `user` resource of that // name), owns its secrets (`secrets-owner`), and is neither root nor the operator's. Required of a module // that says a warrant, or speaks for a channel kind that proves its sender. RunsAs string `json:"runs-as,omitempty"` // RuntimeHealth is how the runtime of its own a module of its own account is served by is ready // (novox/hq ADR 0366): one `health` in the form a resource's takes (ADR 0240), put by the controller on // the process it writes for that runtime (`.own-runtime`). Refused without runs-as. RuntimeHealth any `json:"runtime-health,omitempty"` // Keeps is where this module wants every operator-sealed secret in the mesh written — the // vault's field, and so far nobody else's (novox/hq ADR 0085, amended). // // A directory. The mesh writes one file into it, `export.json`: every secret a module holds for // itself, sealed to the operator's key, with the key's public half and the list of what is NOT // in it. Ciphertext to the machine that holds it and to everything on the bus it crossed — // only the operator, holding the private half off the mesh, can open a line of it. That is // what lets a vault's disk stand in for the store when the store is gone: recovery needs the // export and the key, and the mesh holds neither in a form it can use. Keeps string `json:"keeps,omitempty"` // Listens is what this module accepts connections on, and from where. // // **A rule names its source** ([ADR 0007](novox/hq)). A port with no source is open to // everything that can reach the machine, and saying so is the difference between a manifest // that restricts something and one that appears to — which is the fault // [04-ISSUES/003](novox/hq) records, where five manifests carried a `scope:` nothing read. // // **Derived, not kept in step by hand.** A machine's open ports are a consequence of what runs // on it; the mesh gathers these and hands the whole set to whatever enforces them. Listens []Listening `json:"listens,omitempty"` // Filtering is where this module wants the node's whole computed rule set written. // // One module per node asks for it, and what it receives is derived from every module's // `listens` rather than from its own — a firewall is a property of the machine, and a module // that could only see its own ports would write a rule set that closed everything else. Filtering *Filtering `json:"filtering,omitempty"` // OwnsPaths is, for a module composed from what runs of it (compose.Carried: folded into its node's own composition // at a build of the old form, issue 1126, C5), the paths it owns: its manifest's (DeclaredPaths), as the controller // tells the holder of node-files them, in place of its resources', which are what runs (a directory placed at a // path its manifest leaves to the mesh, a binding). Nil for any other module. Never in a manifest's JSON. OwnsPaths []string `json:"-"` // Stubbed marks a module composed as its stub (compose.Stub: held on its node, issue 1126): none of its own // composition is applied, so what it hands the provisioner (a credential the vault keeps for it, its own secrets) // is left out of its plan as it runs, never refused for want of a plan. Never in a manifest's JSON. Stubbed bool `json:"-"` // Jails are the fail2ban jails this module declares for its own service (novox/hq to-be 31). // Written into whichever node runs the module, the same way `listens` become that node's rules. Jails []Jail `json:"jails,omitempty"` // Jailing marks the module that composes the node's fail2ban jails — the intrusion-prevention // holder. Like Filtering: one module per node gathers what every module declared and writes it. Jailing *Jailing `json:"jailing,omitempty"` // Environment is what this module adds to the operator account's environment: variables, and // entries on PATH (novox/hq ADR 0203). Facts, not lines of one shell's syntax — the holder of // node-environment places them, and the controller writes them in each reader's format. Like // Jails: any module contributes, gathered from every module on the node, written by the holder. Environment *Environment `json:"environment,omitempty"` // Shell is code this module adds to the login shell's startup, for a named shell in a named // slot (novox/hq ADR 0204). The controller never reads it: it is placed, in module order, where // the holder of node-login-shell put the slot's placeholder. Shell []ShellCode `json:"shell,omitempty"` // Contributions are configuration this module gives the holder of a seat it does not hold, in // that tool's own grammar (novox/hq ADR 0212): a seat, a kind the seat receives, and the text. The // holder places them; the module depends on the seat (ADR 0210 §3). Contributions []SeatContribution `json:"contributions,omitempty"` // Collections are the collections this module collects (novox/hq ADR 0349 §13, design 57 L1): each placed in a // file of its own as ${collected:}, filled on the node by the provisioner's client from every item of it // there. Items are what it contributes to others' collections, each a template of its own (collections.go). Collections []Collection `json:"collections,omitempty"` Items []Item `json:"items,omitempty"` // Guards are ports of this module's the mesh refuses on an adopted node except from the // private network and from the machine itself (novox/hq ADR 0100) — the store's port and the // broker's management port. The ports the software uses; the mesh guards where the machine // publishes them. On an adopted node the found firewall stays in force and the mesh loads no // filter of its own, so this is what keeps them unreachable from outside whatever that // firewall does. Ignored on a converged node, whose derived filter already closes them. Guards []int `json:"guards,omitempty"` // Facts are things only the mesh knows, written where this module asks for them — in the // module's own format. // // **The graph is the control plane's; the format is the module's.** The mesh knows which // machines exist, what they are called and where they are. Turning that into a name that // resolves, a peer that is reachable, a host a client trusts, is somebody's software — dnsmasq, // a resolver, a VPN, ssh — in its own configuration language, and the mesh has no business // knowing it. So a module gives a path and a template; the mesh renders the roster through it // and owns nothing of what the file says. // // This used to be a closed list of fact names, each formatted in Go in the control plane, so a // new consumer meant a new formatter here in the consumer's language. Now the data is the mesh's // and the format is the module's: the two built-in cases — the network module's `/etc/hosts` and // dnsmasq's zones — render through the same template path any module uses, and no format lives // in the control plane at all. See RosterFile for what a template sees. // // It replaces three modules that existed only because computed output needed somewhere to // live — they ran no software, could not be swapped for anything, and appeared in the graph as // modules while being a data channel wearing a costume. // // Keyed by a name the module chooses, which is the rendered file's id (`fact-`) — what a // `restart-on` names to restart when the roster changes. Facts map[string]RosterFile `json:"facts,omitempty"` // Zone is the zone of names this module answers itself, and the listen that answers it (novox/hq // ADR 0199). The mesh's resolver forwards the zone to it; nothing here names an address. Zone *Zone `json:"zone,omitempty"` // Certificate is where this module wants a certificate for its machine's name inside the // mesh, and where the key that goes with it can be found. // // **The key is named, not delivered.** The node generated it at enrolment and keeps it; the // mesh only ever signs the public half. So what arrives is a certificate, which is public, // and a path to a file the machine already has. // // Two authorities are kept apart on purpose (novox/hq 08-connectivity): this is the mesh's, // for names only the mesh knows. A name the outside world reaches is a different authority // and a different problem. Certificate *Certificate `json:"certificate,omitempty"` // Grants is a directory this module wants the credentials of its consumers written into, per // provision it offers — one file per consumer, named for it, holding the value alone. // // A directory rather than one document for the same reason as above: each value is sealed // separately and the mesh cannot open any of them to build a list. Grants map[string]string `json:"grants,omitempty"` // BusUsers is where this module wants the mesh's user list written, and it is only ever // answered for the module holding `mesh-broker`. // // **The mesh writes who may connect; the module owns everything else about its server** // (novox/hq design 25 §4, task 1.7). Ports, TLS paths and a store directory live in this // module's image and its mounts and change when it does, so the module's own configuration // carries them and includes this file. A controller that wrote the whole configuration would // have to be kept in step with a Dockerfile it never sees. // // **Asking for it is not enough to receive it.** This file holds every user's password hash, so // a module that could ask for it could read every credential on the bus — and the claim on // `mesh-broker` is what authorises it, checked from this manifest alone. BusUsers string `json:"bus-users,omitempty"` // Bundles are this module's compiled bundles as the build produced them: what each is called, // where it is, what it hashes to, what language it is in and which files a tool runtime loads // from it (novox/hq ADR 0175, to-be 38). // // **Derived, never written.** The manifest in a repository says `build.artifacts`; the manifest // the mesh holds says what came out, the way a resource naming an artifact comes to name a // digest. Kept here because a tools bundle is referenced by no resource of the module's own — // the node's runtime loads it, and the runtime is composed by the mesh — so without this the // resolved manifest would carry no trace of the one artifact the runtime needs. A repository // manifest that writes this beside a build is refused: it would be stating the build's output // by hand. Bundles []Bundle `json:"bundles,omitempty"` } // Bundle is one compiled bundle after it exists, as the resolved manifest carries it. type Bundle struct { Name string `json:"name"` // Source is where a machine fetches it, kept without the store's address like every reference // the mesh records (artifacts.go); Digest is what it must hash to. Source string `json:"source"` Digest string `json:"digest"` // Language is what it was compiled from, which is what says how it is run. Language string `json:"language,omitempty"` // Entrypoints are the compiled files it was built around, relative to its root. Entrypoints []string `json:"entrypoints,omitempty"` // Loads are the entrypoints a node's tool runtime imports from it: what the artifact said, or // every entrypoint for a module declaring tools that said nothing. Empty for a bundle that is // run rather than loaded. Loads []string `json:"loads,omitempty"` // Env is what the artifact said it is given (ADR 0192), as written; composed per machine. Env map[string]string `json:"env,omitempty"` // Launchers are the executables the build wrote beside its entrypoints, by entrypoint (novox/hq // ADR 0193). A bundle built before them has none, and is served as it was built. Launchers map[string]string `json:"launchers,omitempty"` // Binary is the executable a bundle compiled to a binary is, at its root (novox/hq ADR 0193): // what runs it, where an interpreted bundle names an interpreter and an entrypoint. Binary string `json:"binary,omitempty"` // Bus is the artifact's bus account, kept on the resolved manifest so the grant composition reads it (BusAccounts). Bus *ProcessBus `json:"bus,omitempty"` } // Build says how to produce this module's artifacts from its source. // // **Absent means nothing is built.** A module can be entirely configuration — a shell's rc file, // a set of firewall rules — and having to declare an empty build for it would be a field that // exists to be left blank. type Build struct { // Artifacts are what the source produces, each named so a resource can refer to it before // anybody knows its digest. Artifacts []Artifact `json:"artifacts,omitempty"` // On is what this module's own build stands on: another module's artifact, named rather than // pinned. // // **A module may not write down which copy of its base to use** (novox/hq issue 044). Every // module in a scripted toolchain is compiled inside one shared image, and a fingerprint typed // into a recipe names one particular copy of it — the copy on whichever machine the person // typing was using. On any other mesh that copy has never existed, so the build stops on its // first line. Naming the module instead lets the mesh answer with the copy *this* mesh has, // which is the only one it can fetch. // // It does not make the build edge declared. What this says is where to start; what the build // was actually built against is still read back out of the build itself (ADR 0009), and the // two can disagree — a recipe that names a base and then bakes in a second one is exactly the // drift that reading it back catches. On []BuildsOn `json:"on,omitempty"` } // BuildsOn is one base a build needs, and the name the recipe knows it by: another module's // artifact, or an image published elsewhere. type BuildsOn struct { // Arg is the build argument the recipe reads it from. Arg string `json:"arg"` // Module is whose artifact it is. Module string `json:"module,omitempty"` // Artifact is which of that module's artifacts, by its own name for it. Artifact string `json:"artifact,omitempty"` // Image is an image published elsewhere, pinned by digest, that the build copies out of — a // vendor's tool, a base nobody in the mesh builds. Declared, the mesh copies it into its own // registry before the build and hands the recipe the copy (novox/hq 04-ISSUES/064, ADR 0097); // a recipe fetching from a public registry on its own is refused. Image string `json:"image,omitempty"` } // ArtifactContext names the repository an image artifact's build context is cloned from, when // that is not this module's own repository. type ArtifactContext struct { // Repository is cloned fresh, the same way the module's own repository is — a working tree // nothing has touched, so what was built is reproducible from the two commits named rather // than from whatever a previous build happened to leave behind. A URL, or — with Seat — a // path on that seat's holder, `/`. Repository string `json:"repository"` // Seat is the seat the repository lives on: `git` for this mesh's own forge (novox/hq ADR 0111, // ADR 0155). A context written as a URL names one installation's forge and can be built // nowhere else; a path on the seat is composed by the mesh that builds it, whichever forge // holds the seat there. Seat string `json:"seat,omitempty"` // Ref is the branch, tag or commit of that repository to build. Empty means its own default // branch — the same meaning an empty module ref already has. Ref string `json:"ref,omitempty"` } // Artifact is one thing built from a module's source. type Artifact struct { // Name is how resources refer to it. Local to the module. Name string `json:"name"` // Kind is "image" or "archive". Kind string `json:"kind"` // From is what it is built from, relative to the repository root: a Dockerfile for an image, // a directory for an archive. From string `json:"from"` // Target is which stage of that Dockerfile to stop at, for a recipe that describes more than // one image. // // **One source, two images, and they are meant to differ.** A toolchain image carries a // compiler and everything a build needs; the image the same module *runs* in should carry // neither. Describing both in one recipe keeps them in step — they share a base, a library // version and an operating system — while letting each be built and published separately. // Empty means the whole recipe, which is what a module with one image says by saying nothing. Target string `json:"target,omitempty"` // Context names a second repository this image's build reaches into for its own source — the // recipe itself is still read from this module's own directory, at this module's own commit; // only the build context `docker build`'s final argument names comes from here instead. // // **Packaging and source are allowed to live apart.** A module that only ships the recipe for // source that lives elsewhere — the reference route-proxy in mesh-controller's own repository, // packaged as a module in the catalogue rather than vendored a second time the two copies // could drift from — names where that source actually is. Empty means the ordinary case: an // image built from this same module's own repository, the same as every other artifact. Context *ArtifactContext `json:"context,omitempty"` // Compiles is the Go package an image's recipe compiles, relative to the tree it is built in — its // context, or the module's directory (novox/hq ADR 0267 rule 1). // // **What a build is made from is derived, never listed.** The build seat reads the package's import // closure and hands the recipe that and nothing else, so a merge elsewhere in a shared repository is // no change to this image, and a recipe copying a file outside the closure fails by name instead of // building from something no merge is mapped onto. Empty for an image that compiles no Go: its whole // tree is its build source, as before. Compiles string `json:"compiles,omitempty"` // System is the operating system this artifact is compiled for, for a bundle whose output is a // binary rather than portable code (novox/hq ADR 0142). // // **Named by the artifact, not by the recipe.** A toolchain deliberately accepts nothing from // the module — anything a module could override there it would be writing a Dockerfile to // override — and yet a compiled binary is per operating system, pinned at link time so a host // refuses to touch a machine it was not built for (novox/hq ADR 0005). The way out is that the // target is a property of the artifact: one artifact declared per system, one build each, and // the recipe stays the mesh's. // // Empty for a bundle whose output runs anywhere, which is every interpreted language, and for // every other kind. A bundle in a language that compiles to a binary must say one, because // "compiled for whatever the build machine happened to be" is the fault this exists to prevent. System string `json:"system,omitempty"` // Language is what this module's code is written in, for a bundle. // // **Declared, never guessed.** Inferring it from what files happen to be present makes a // module's build depend on a directory listing, and a module that adds a stray file builds // differently for a reason nobody can see. It is also the only thing a bundle needs to say: // everything else about the toolchain — which compiler, which flags, which base — is the // mesh's, and a module that could override it would be writing a Dockerfile again. // // Empty for every other kind, which do not compile. Language string `json:"language,omitempty"` // Binary is what the compiled executable is called, for a bundle in a language that compiles to // one. Empty means the package's own name, which is what a compiler does by default. // // **Because the name a machine runs it by is not always the name of the package that built it.** // The host's command is `cmd/mesh-host` and every machine runs it as `nox-mesh-host` — the path // it is installed at, the name in its unit, and the name its launcher looks for inside a // delivered version. A bundle that carried the package's name was delivered correctly, reported // success, and was invisible to the launcher (novox/hq 04-ISSUES/142). Binary string `json:"binary,omitempty"` // Bus is a tools bundle's own bus account (novox/hq ADR 0564 Limits 4; the lead, 2026-10-29): read as a process's // (ProcessBus), a principal named after the bundle's binary (BusAccounts), its secret broker-. A tools bundle // is run by the node's tool runtime per call, so it declares its account here and runs no idle service for it. Bus *ProcessBus `json:"bus,omitempty"` // URL is where an archive's upstream file is fetched from, for an archive that is a release // somebody else published rather than a directory of this repository (novox/hq ADR 0316 §2, §6). // With it come SHA256 and Version, and From stays empty. // // **Pinned by the digest of what the vendor published, mirrored by the build seat.** A release of // about 80 MB copied into a repository is kept for ever in its history at every upgrade, and an // add-on whose licence forbids copying it to third parties may not be in a repository at all. So the // manifest names the file, the build seat fetches it, refuses it when its sha256 is not the pin's and // names both digests, and packs it as any archive is packed: what reaches a machine is the mesh's own // archive in the artifact store, fetched by digest like every other, and a machine never asks the // vendor. Upgrading is changing the pin, reviewed like any other change. URL string `json:"url,omitempty"` // SHA256 is the sha256 of the file at URL, as 64 lower-case hexadecimal characters. SHA256 string `json:"sha256,omitempty"` // Version is what the vendor calls the release pinned, said where a person reads the pin; the build // does not read it. Version string `json:"version,omitempty"` // File is the name an upstream file that is not an archive is kept under: the archive built from it // holds that one file (an add-on's xpi). Empty means the file is a tar archive (gzip, bzip2 or xz) // whose files are the artifact. File string `json:"file,omitempty"` // Within is the directory inside an upstream tar archive whose content is the artifact, for a // release that unpacks into a directory of its own name (`betterbird/`). An entry outside it refuses // the build. Empty means the archive's root. Within string `json:"within,omitempty"` // NamesOnPurpose are the names this artifact means to name, each with why: the vendor's host an upstream // file is fetched from, which the installation check judges like any name (InstallationProblems). NamesOnPurpose map[string]string `json:"names-on-purpose,omitempty"` // Entrypoints are the compiled files a tool host should load from this module, relative to the // bundle's root. // // **Named rather than derived from which files exist**, for the same reason as the language: // the module knows what it serves, and a build that guesses would change meaning when // somebody adds a helper. An empty list is a bundle that is run rather than loaded — a // provisioner or a step, named by whatever runs it. Entrypoints []string `json:"entrypoints,omitempty"` // Loads are the entrypoints of this bundle the node's tool runtime loads (novox/hq ADR 0175, // to-be 38): the module's tool code, each file registering its tools as it is imported. A // subset of Entrypoints, for a bundle that also carries things that are RUN — a daemon, a // step, a report — and must not have them imported into the runtime. // // Absent means every entrypoint, for a module that declares `tools`: a bundle holding the // module's tools and nothing else is the ordinary case and should not have to say the same // list twice. A module declaring no tools has nothing the runtime loads, whatever it compiles. Loads []string `json:"loads,omitempty"` // External are packages a TypeScript bundle keeps as imports rather than inlining — a native // addon, a package that reads its own files — and so carries the toolchain's node_modules for // (novox/hq ADR 0193). Absent for nearly every bundle, which is then one file per entrypoint. External []string `json:"external,omitempty"` // Paths are the files and directories, relative to the module's directory, a package or a bundle in a language // other than Go is built from (novox/hq ADR 0499 clause 1): with the module's manifest they are its build source, // and a module whose every artifact names them takes its fingerprint's tree from them alone (clause 2). Absent means // the module's directory, as before. // // **Named, because the build source of a package sharing a repository cannot be derived.** A Go program's is // (ADR 0267 clause 1), an archive's `from` names it and an image's is the context its manifest names, so each of those // refuses the word. A path stays inside the module's directory and is no pattern: a build source that could reach // out of it, or grow with a directory listing, would be one no fingerprint pins. Paths []string `json:"paths,omitempty"` // Env is what a tools bundle is given on a machine (novox/hq ADR 0192): words and their values, // paths and constants composed with ${dir:…} and ${port:…} exactly as a container's environment // is, never a secret's content. The node's runtime hands it to this bundle and to no other. Env map[string]string `json:"env,omitempty"` // Series is the series this artifact's versions are numbered in, `.` (novox/hq ADR 0606, design 32): // the builder numbers `.`, so a change of series is a change a user accepts by its own `packages`. // Said on a package, an image, a bundle or an archive; the judge refuses it on any other kind. Absent is // DefaultSeries (SeriesOf). Series string `json:"series,omitempty"` // Needs are the artifact references, `:`, of the catalog graph's edges this artifact has where no // other line of the manifest or of a seat's definition says them (design 47 G §47, §432). Read here so a reader // release keeps a manifest that names them whole (design 47 G §340, §409); the manifest validator checks their form. Needs []string `json:"needs,omitempty"` // Calls are the capability words (design 47 G §488, §605) a package's code calls of the tool runner: the delivery plan // derives, for each module whose build resolved a version of such a package, an ordering edge to the tool runner stating // those words on each node, so no manifest names the tool runner's module. Said on a package only; the manifest // validator checks their form. Calls []string `json:"calls,omitempty"` // States are the capability words (design 47 G §488) the tool runner's artifact states, the edge of a package's Calls // running to the module that states each (§545). Read here so the second reader release keeps a manifest that names // them (§621). States []string `json:"states,omitempty"` // GeneratedFrom marks a package of a contracts module (novox/hq ADR 0608 §5, design 26 *Contracts modules*): the // directory, relative to the module's, of the seat definitions every file of the package is generated from. A // module carrying it holds contracts only and claims no seat, which the judge refuses naming the seat; the build // modules' test step regenerates the package and fails on a file out of step. GeneratedFrom string `json:"generated-from,omitempty"` } // AcceptedSeries is the series of the package of that name this module accepts: the one Packages names, or else the // series of the package's first numbered version (design 32), the lowest of numbered, the series the package has a // numbered version in (the indexer's to say; a series is only ever raised); DefaultSeries while none is numbered. func (m Manifest) AcceptedSeries(name string, numbered ...string) string { if s := m.Packages[name]; s != "" { return s } first := "" for _, s := range numbered { if seriesOrder(s) != nil && (first == "" || compareSeries(s, first) < 0) { first = s } } if first == "" { return DefaultSeries } return first } // seriesOrder is a series' major and minor, or nil when it is no `.`. func seriesOrder(s string) []int { major, minor, ok := strings.Cut(s, ".") a, err1 := strconv.Atoi(major) b, err2 := strconv.Atoi(minor) if !ok || err1 != nil || err2 != nil || a < 0 || b < 0 { return nil } return []int{a, b} } // compareSeries orders two well-formed series by major, then minor. func compareSeries(a, b string) int { return slices.Compare(seriesOrder(a), seriesOrder(b)) } // DefaultSeries is the series of an artifact or an accepted package that names none (design 32). const DefaultSeries = "0.1" // SeriesOf is the series the artifact's versions are numbered in: its own, or DefaultSeries. func (a Artifact) SeriesOf() string { if a.Series == "" { return DefaultSeries } return a.Series } // Kinds an artifact may be. const ( // ArtifactImage is built from a Dockerfile in this repository. ArtifactImage = "image" // ArtifactArchive is a directory in this repository, packed. ArtifactArchive = "archive" // ArtifactBundle is this module's own code, COMPILED by a toolchain and then packed. // // **The one recipe that both builds and packs**, and the reason it exists is the authoring // burden. An `archive` packs a directory as it stands, so shipping compiled output means // compiling somewhere first — which means a Dockerfile, repeating the same incantation in // every module: two base arguments, a working directory chosen so the SDK resolves upward, the // compiler invoked by absolute path because the usual symlink is resolved away when the base is // assembled, a second stage, an environment variable naming the entrypoints. Most of the // catalogue is unconverted and that is why. // // A bundle says what the module is written in and nothing about how. The mesh knows what a // language implies, which is the whole of the difference: a Dockerfile is right for software // that needs a particular base, and wrong for "compile my module's code", which is the same // operation every time. ArtifactBundle = "bundle" // ArtifactUpstream is an image somebody else built, mirrored into the mesh's own registry and // pinned by the digest it lands with. // // **Because a module usually runs software it did not write.** A database module ships // configuration and a provisioner and does not build a database. It could name the upstream // reference directly, and then every machine needs a route to a public registry and the // reference is a tag somebody else can move — which is what pinning exists to prevent // (novox/hq ADR 0006). // // Mirroring is what the bootstrap already does by hand: the lab stocks upstream images into // the registry a first node pulls from. This makes that a thing a module can say. ArtifactUpstream = "upstream" // ArtifactPackage is this module's own code, compiled and published to the mesh's package // registry by version, for other modules to consume when they are built — the SDK above all // (novox/hq ADR 0076). Like a bundle it is built from the module's own directory and names a // language; unlike a bundle it is not a resource on any machine, it is a build input. It is // compiled on a PUBLIC base, never the mesh toolchain, because the toolchain is built from it. ArtifactPackage = "package" ) // ArtifactStoreProvision is the name the mesh's store for what modules ship (images, and archives, // which are directories from a repository packed as blobs) was offered under until the provision // retired (novox/hq ADR 0632 §2): no seat delivers it and no module provides it. It stays as the // scheme of the older reference form, artifact-store://, which done keys keep (ArtifactStoreScheme). const ArtifactStoreProvision = "artifact-store" // Listening is one endpoint a module serves: a port it accepts connections on, and what may be said // about that port from outside the module. type Listening struct { // Name is what this endpoint is called, so an assignment and a route can refer to it as one thing // (novox/hq ADR 0138). // // **Because a port number is not a name.** Three facts have to be said about an endpoint when a // module is assigned — which machine port it lands on, the subdomain a proxy serves it under, and // how far it reaches — and they were said in three places keyed by the port. A module with two // endpoints of different shapes, a web surface behind a proxy and a protocol port clients dial // directly, cannot be configured that way without a reader joining numbers by hand. // // The module's to choose, like the route's label: it names its own parts. Lowercase, and unique // within the module, so a reference to it is unambiguous. Empty is allowed and means an endpoint // nothing refers to by name, which is every endpoint in the catalogue until they are named. Name string `json:"name,omitempty"` Port int `json:"port"` // Protocol is "tcp" or "udp". Absent means tcp, which is what almost everything is — and a // field that had to be written every time would be written wrongly some of the time. Protocol string `json:"protocol,omitempty"` // From is who may reach it. Required, because a rule with no source is open and must say so // rather than appear to restrict something. From string `json:"from"` // Fixed means the protocol chose this number, so the machine must use it too. // // **The exception, and it is a real one** (novox/hq ADR 0038). Mail is 25, submission is 587, // IMAP over TLS is 993 — a mail system on a port the mesh picked is a mail system nothing can // deliver to. Everything else the mesh assigns, because a module cannot know what else is on // the machine it lands on. // // A fixed port is a **claim**: one holder per machine, and the second is refused by name when // it is assigned rather than by a container runtime when it is applied. Fixed bool `json:"fixed,omitempty"` // Why this port is open, for somebody reading a generated rule set and wondering. Why string `json:"why,omitempty"` } // Where a listening port may be reached from. const ( // FromMesh is any machine on the private network. What almost everything wants. FromMesh = "mesh" // FromEverywhere is the public internet. Deliberately spelled out: a port open to everything // should be legible as such in the manifest, not the consequence of an omission. FromEverywhere = "anywhere" // FromMachine is this machine only — a port bound for something else on the same host. FromMachine = "machine" // FromLocalNetwork is the private network and the networks this machine is directly attached to // through its uplink, as it reports them, and only those wholly in a private range (novox/hq ADR // 0340): a local service reached by devices that will never be nodes, said as exactly that rather // than as `anywhere`. A public subnet the machine sits on never counts, so it cannot open a port to // the internet. FromLocalNetwork = "local-network" ) // At is this port's protocol, with the default applied. func (l Listening) At() string { if l.Protocol == "" { return "tcp" } return l.Protocol } // Jail is a fail2ban jail a module declares for its own service (novox/hq to-be 31). // // **The module names no node and no path** (ADR 0112): it says what a break-in on its service looks // like — the failregex — and the jail's own keys (the port it watches, where it logs, how many // tries, how long to ban). The mesh writes it into whichever node's fail2ban runs the module, the // same way a module's `listens` become that node's firewall rules. A node not running the module // has no such jail. type Jail struct { // Name is the jail and its filter, e.g. "postgres-auth". One holder of the name per node. Name string `json:"name"` // Failregex is what a failed authentication looks like in the service's log — the filter. Failregex string `json:"failregex"` // Jail is the body of the jail's stanza: the keys under [] the module knows and the mesh // does not — the port it watches, its logpath and backend, maxretry, bantime. Jail string `json:"jail"` } // Jailing says a module composes the node's fail2ban jails — the intrusion-prevention holder. Like // Filtering for the firewall: one module gathers what every other module declared and writes it // where it owns. Into is the one jail file the stanzas are composed into (so the fail2ban service // can restart on a single resource); FilterInto is the directory each jail's filter file goes in. type Jailing struct { Into string `json:"into"` FilterInto string `json:"filter-into"` } // ComposedJailsID is the single jail file the mesh composes every declared jail into, so the // fail2ban service names one resource in its restart-on and a jail added or removed reaches it. func ComposedJailsID() string { return "composed-jails" } // Filtering says where a module wants the computed rule set. type Filtering struct { // Into is the path to write it to. Whatever loads it is this module's own business — an // action beside this field, ordinarily — because how a machine enforces rules is a fact about // the machine and the mesh has no business knowing it. Into string `json:"into"` } // Certificate says where a module wants what the mesh issued for its machine. type Certificate struct { // Into is where the certificate is written. Into string `json:"into"` // Authority is where the mesh's own certificate is written, so something connecting to this // machine can be told what to believe. Optional: a module that only serves does not need it. Authority string `json:"authority,omitempty"` } // CertificateID and AuthorityID are the resource identities of what the mesh issued. func CertificateID() string { return "certificate" } // ClaimsSeat says whether this manifest claims one named seat. func (m Manifest) ClaimsSeat(seat string) bool { for _, c := range m.Claims { if c.Name == seat { return true } } return false } // BusUsersID names the mesh's composed user list, so it is the same resource across every // declaration and a change to it is an update rather than a second file beside the old one — which // on a bus reading a directory would be two account lists, and the server would take both. func BusUsersID() string { return "bus-users" } func AuthorityID() string { return "certificate-authority" } // FilteringID names the computed rule set, so it is the same resource across every declaration // and a change to it is an update rather than an addition beside the old one. func FilteringID() string { return "filtering" } // NeedID is the resource identity of the file a module's own secret lands in. func NeedID(name string) string { return "needs-" + name } // SecretID is the resource identity of the file a module is given a credential in. func SecretID(requirement string) string { return "secret-" + requirement } // GrantID is the resource identity of one consumer's credential on the providing machine. func GrantID(provision, consumer string) string { return "grant-" + provision + "-" + consumer } // BoundID is the resource identity of the file a module is told about a provision in. func BoundID(requirement string) string { return "bound-" + requirement } // AccessID is the resource identity of an operator-owned path this module is granted use of. // // Derived from the path rather than a name the module chose, so two modules granted the same // access name the same identity within their own qualification — and neither has to invent a // label for something that is not theirs. func AccessID(path string) string { return "access-" + strings.TrimPrefix(path, "/") } // Wants is everything that must be provided on the same node: what this module requires, and what // it contributes to. func (m Manifest) Wants() []string { out := append([]string{}, m.Requires...) add := func(to string) { for _, r := range m.Requires { if r == to { return } } for _, already := range out { if already == to { return } } out = append(out, to) } for to := range m.Contributes { add(to) } for to := range m.ContributesMany { add(to) } sort.Strings(out) return out } // ReceivedID is the resource identity of the file a provider is given its contributions in. // // Named rather than positional so a module can point `restart-on` at it: a proxy that got a new // route and did not reload is a route that silently does not work, which is the same fault the // overlay had when a peer list changed under a running interface. func ReceivedID(requirement string) string { return "received-" + requirement } // ParseManifest reads a module manifest, refusing anything it cannot act on. // // Every problem is reported rather than the first, because somebody writing a manifest fixes // them in one pass or in four. // manifestFields is Manifest without its methods, so the JSON methods below can use the ordinary // field decoding for everything but `secrets`. type manifestFields Manifest // UnmarshalJSON reads `secrets` in both of its shapes — a path, or an object of local names to // paths (ADR 0094) — and everything else exactly as the fields declare. // // **An unknown key is kept aside, not refused here** (novox/hq ADR 0262). Registration and the module // check refuse it, through ParseManifest. Reading the catalogue the store already holds does not: a // manifest registered under a newer controller carries a field an older one does not know, and a // strict read there failed the whole catalogue, and with it every plan and every send, the moment a // controller was rolled back. UnknownField says what was set aside. func (m *Manifest) UnmarshalJSON(raw []byte) error { // The config form read into the settings form's fields, so both compose by one path (config.go). raw, forms := toSettingsForm(raw) var keys map[string]json.RawMessage if err := json.Unmarshal(raw, &keys); err != nil { return err } if settings, has := keys[SettingsField]; has && string(settings) != "null" { forms.settings = append(forms.settings, SettingsField) } if config, has := keys[ConfigField]; has { if string(config) != "null" { forms.config = append(forms.config, ConfigField) } if _, both := keys[SettingsField]; !both { keys[SettingsField] = config } // Beside `settings` it is refused by name (MixedFormProblems), never merged into it. delete(keys, ConfigField) } if err := consumesEntryProblem(keys["consumes"]); err != nil { return err } invokeFields, err := readInvokes(keys) if err != nil { return err } plain := map[string]string{} many := map[string]map[string]string{} if secrets, ok := keys["secrets"]; ok && string(secrets) != "null" { var byName map[string]json.RawMessage if err := json.Unmarshal(secrets, &byName); err != nil { return fmt.Errorf("secrets: an object of requirement to path, or to {local name: path}: %w", err) } for to, v := range byName { switch { case len(v) > 0 && v[0] == '"': var path string if err := json.Unmarshal(v, &path); err != nil { return err } plain[to] = path case len(v) > 0 && v[0] == '{': var paths map[string]string if err := json.Unmarshal(v, &paths); err != nil { return fmt.Errorf("secrets.%s: an object of local name to path: %w", to, err) } many[to] = paths default: return fmt.Errorf("secrets.%s: a path, or an object of local name to path, not %s", to, v) } } delete(keys, "secrets") } contributesPlain := map[string]map[string]any{} contributesMany := map[string]map[string]map[string]any{} if contributes, ok := keys["contributes"]; ok && string(contributes) != "null" { var byTo map[string]json.RawMessage if err := json.Unmarshal(contributes, &byTo); err != nil { return fmt.Errorf("contributes: an object of requirement to values, or to {local name: values}: %w", err) } for to, v := range byTo { // Both shapes are JSON objects, unlike secrets' path-vs-object split, so the shapes are // told apart by what is INSIDE: an ordinary contribution's fields are scalars (a label, // a port); the several-instance shape is an object of local names, each itself an // object of fields. Confirmed against the whole catalogue before relying on it — no // contribution anywhere has an object-valued field. var fields map[string]json.RawMessage if err := json.Unmarshal(v, &fields); err != nil { return fmt.Errorf("contributes.%s: an object of values, or of local name to values: %w", to, err) } many := len(fields) > 0 for _, field := range fields { trimmed := bytes.TrimSpace(field) if len(trimmed) == 0 || trimmed[0] != '{' { many = false break } } if many { var locals map[string]map[string]any if err := json.Unmarshal(v, &locals); err != nil { return fmt.Errorf("contributes.%s: an object of local name to values: %w", to, err) } contributesMany[to] = locals continue } var values map[string]any if err := json.Unmarshal(v, &values); err != nil { return fmt.Errorf("contributes.%s: an object of values: %w", to, err) } contributesPlain[to] = values } delete(keys, "contributes") } var optionalRequires map[string]bool var requireShares map[string][]BucketShare var busState []BusStateEntry var busStateAside []string if requires, ok := keys["requires"]; ok && string(requires) != "null" { read, err := readRequires(requires) if err != nil { return err } plainNames, err := json.Marshal(read.names) if err != nil { return err } keys["requires"] = plainNames optionalRequires = read.optional requireShares = read.shares busState, busStateAside = read.busState, read.aside } // The stored form's shares (RequireSharesKey). if stored, ok := keys[RequireSharesKey]; ok { if string(stored) != "null" { stood, err := readRequireShares(stored) if err != nil { return err } for requirement, shares := range stood { if requireShares == nil { requireShares = map[string][]BucketShare{} } requireShares[requirement] = shares } } delete(keys, RequireSharesKey) } // The stored form: `requires` plain, and which are optional beside it (OptionalRequiresKey). if stored, ok := keys[OptionalRequiresKey]; ok { if string(stored) != "null" { optional, err := readOptionalRequires(stored) if err != nil { return err } for name := range optional { if optionalRequires == nil { optionalRequires = map[string]bool{} } optionalRequires[name] = true } } delete(keys, OptionalRequiresKey) } rest, err := json.Marshal(keys) if err != nil { return err } decoder := json.NewDecoder(bytes.NewReader(rest)) decoder.DisallowUnknownFields() var fields manifestFields unknown := "" if err := decoder.Decode(&fields); err != nil { if asUnknownField(err) == nil { return err } // Read without it, at whatever depth it is (prunedFields): the module is left out of every // declaration by name (LeftOut), and still provides what it provides, and still has its data // copied, so nothing that requires it is refused and nothing it holds goes uncopied. unknown = err.Error() var pruned []string var perr error if fields, pruned, perr = prunedFields(keys); perr != nil { // Not read past: the manifest keeps its name and version alone. It is left out and raised // all the same, and one manifest never fails the whole catalogue. fields = manifestFields{} _ = json.Unmarshal(keys["module"], &fields.Module) _ = json.Unmarshal(keys["version"], &fields.Version) unknown += " " + readNoFurther + perr.Error() + ")" } else { unknown += " (read without " + strings.Join(pruned, ", ") + ")" } } *m = Manifest(fields) m.unknown = setAsideAlso(unknown, busStateAside) // A bus-state entry of `requires`, beside those of the stored form (BusStateField). m.BusState = append(m.BusState, busState...) m.forms = forms m.OptionalRequires = optionalRequires m.RequireShares = requireShares m.InvokeFields = invokeFields if len(plain) > 0 { m.Secrets = plain } if len(many) > 0 { m.SecretsMany = many } if len(contributesPlain) > 0 { m.Contributes = contributesPlain } if len(contributesMany) > 0 { m.ContributesMany = contributesMany } if err := m.checkSharesNotContributed(); err != nil { return err } return nil } // invokeLongForm is an entry of `invokes` in its long form: the verb, and the fields of its answer the caller relies on // (design 47 G §617). type invokeLongForm struct { Verb string `json:"verb"` Fields []string `json:"fields,omitempty"` } // readInvokes reads `invokes` whose entries are verbs or, in their long form, {verb, fields}: it puts the verbs back in // keys as plain names and answers the fields each long-form entry names. func readInvokes(keys map[string]json.RawMessage) (map[string][]string, error) { raw, ok := keys["invokes"] if !ok || string(raw) == "null" { return nil, nil } var entries []json.RawMessage if err := json.Unmarshal(raw, &entries); err != nil { return nil, nil // not a list: the field's own decoder says so } var verbs []string var fields map[string][]string for i, e := range entries { trimmed := bytes.TrimSpace(e) if len(trimmed) == 0 || trimmed[0] != '{' { var verb string if err := json.Unmarshal(trimmed, &verb); err != nil { return nil, fmt.Errorf("invokes[%d]: a verb, or {verb, fields}: %w", i, err) } verbs = append(verbs, verb) continue } var long invokeLongForm dec := json.NewDecoder(bytes.NewReader(trimmed)) dec.DisallowUnknownFields() if err := dec.Decode(&long); err != nil { return nil, fmt.Errorf("invokes[%d]: a verb, or {verb, fields}: %w", i, err) } if long.Verb == "" { return nil, fmt.Errorf("invokes[%d]: a long-form entry names its verb", i) } verbs = append(verbs, long.Verb) if len(long.Fields) > 0 { if fields == nil { fields = map[string][]string{} } fields[long.Verb] = long.Fields } } plain, err := json.Marshal(verbs) if err != nil { return nil, err } keys["invokes"] = plain return fields, nil } // checkSharesNotContributed refuses a module whose own `contributes` to s3-bucket names `shares` (ADR 0468 §8). func (m Manifest) checkSharesNotContributed() error { if len(m.RequireShares[BucketRequirement]) == 0 { return nil } if _, named := m.Contributes[BucketRequirement][SharesValue]; named { return fmt.Errorf("contributes.%s names `shares` and so does its requirement; keep one, the requirement's (novox/hq ADR 0468 §8)", BucketRequirement) } return nil } // consumesEntryProblem refuses a consumes entry that is more than an event's name. **No manifest word asks where a // consumer starts** (novox/hq ADR 0443 §4): the controller makes every module's consumer from now, and the first module // that needs a stream's history brings a decision that adds the word. An entry carrying a key such as from, start or // deliver would otherwise be read as a bare "cannot unmarshal object", which says nothing of why. func consumesEntryProblem(raw json.RawMessage) error { var entries []json.RawMessage if len(raw) == 0 || json.Unmarshal(raw, &entries) != nil { return nil // not an array: the ordinary decoding says so } for i, e := range entries { var obj map[string]json.RawMessage if json.Unmarshal(e, &obj) != nil { continue } keys := make([]string, 0, len(obj)) for k := range obj { keys = append(keys, strconv.Quote(k)) } sort.Strings(keys) return fmt.Errorf("consumes entry %d carries the key %s: an entry is an event's name alone, and no word asks where a "+ "consumer starts, because the controller makes every module's consumer from now (novox/hq ADR 0443 §4)", i, strings.Join(keys, ", ")) } return nil } // MarshalJSON writes `secrets` and `contributes` back in the shape they were read: single values, // and objects of local names; and its config in the form it was read in (config.go). func (m Manifest) MarshalJSON() ([]byte, error) { raw, err := m.marshalFields() if err != nil || !m.DeclaresConfig() { return raw, err } return toConfigForm(raw) } func (m Manifest) marshalFields() ([]byte, error) { raw, err := json.Marshal(manifestFields(m)) if err != nil { return nil, err } if len(m.SecretsMany) == 0 && len(m.ContributesMany) == 0 && len(m.OptionalRequires) == 0 && len(m.RequireShares) == 0 && len(m.InvokeFields) == 0 { return raw, nil } var keys map[string]json.RawMessage if err := json.Unmarshal(raw, &keys); err != nil { return nil, err } if len(m.InvokeFields) > 0 { // Each verb that names fields is written back in its long form (design 47 G §617). entries := make([]any, 0, len(m.Invokes)) for _, verb := range m.Invokes { if fields, named := m.InvokeFields[verb]; named { entries = append(entries, invokeLongForm{Verb: verb, Fields: fields}) continue } entries = append(entries, verb) } listed, err := json.Marshal(entries) if err != nil { return nil, err } keys["invokes"] = listed } if optional := optionalRequiresList(m); len(optional) > 0 { // Beside `requires`, never inside it: an older controller reads `requires` as plain names, and one // manifest it cannot read stops the whole catalogue (OptionalRequiresKey). listed, err := json.Marshal(optional) if err != nil { return nil, err } keys[OptionalRequiresKey] = listed } if len(m.RequireShares) > 0 { listed, err := json.Marshal(m.RequireShares) if err != nil { return nil, err } keys[RequireSharesKey] = listed } if len(m.ContributesMany) > 0 { mergedContributes := map[string]any{} for to, values := range m.Contributes { mergedContributes[to] = values } for to, locals := range m.ContributesMany { mergedContributes[to] = locals } contributes, err := json.Marshal(mergedContributes) if err != nil { return nil, err } keys["contributes"] = contributes } if len(m.SecretsMany) == 0 { return json.Marshal(keys) } merged := map[string]any{} for to, path := range m.Secrets { merged[to] = path } for to, paths := range m.SecretsMany { merged[to] = paths } secrets, err := json.Marshal(merged) if err != nil { return nil, err } keys["secrets"] = secrets return json.Marshal(keys) } // CredentialProvisionPrefix starts the name of a provision's credential, the vault's provision beside it (novox/hq ADR // 0570 clause 6): `secret-`. const CredentialProvisionPrefix = "secret-" // SecretFile is one file a module is given a credential in: the local name it goes by inside // the module (empty for the ordinary one-file case, where the requirement's name serves) and where. type SecretFile struct { Local string Path string } // SecretFiles is every file a module wants the credential for one requirement in, in a stable // order: the plain path as one entry with no local name, or one entry per local name. func (m Manifest) SecretFiles(to string) []SecretFile { if path, ok := m.Secrets[to]; ok { return []SecretFile{{Path: path}} } paths := m.SecretsMany[to] out := make([]SecretFile, 0, len(paths)) for _, local := range sortedKeys(paths) { out = append(out, SecretFile{Local: local, Path: paths[local]}) } return out } // SecretRequirements is every requirement this module wants a credential file for, sorted. func (m Manifest) SecretRequirements() []string { seen := map[string]bool{} for to := range m.Secrets { seen[to] = true } for to := range m.SecretsMany { seen[to] = true } return sortedKeys(seen) } // SecretLocal is the name a credential goes by inside the module: the local name where the // requirement maps to several, else the requirement itself. It is what `${secret:}` says. func SecretLocal(to, local string) string { if local == "" { return to } return local } // UnknownField is the first key a leniently read manifest had that this controller does not know, as // the JSON decoder words it, or "" when it had none (novox/hq ADR 0262). func (m Manifest) UnknownField() string { return m.unknown } // Offers is everything this module can satisfy: its own name, and what it provides. func (m Manifest) Offers() []string { out := []string{m.Module} for _, p := range m.Provides { out = append(out, p.Name) } sort.Strings(out) return out } // OffersAt is what this module provides at one scope, with its own name counted as node-scoped: // a module is only ever itself on the machine it is installed on. func (m Manifest) OffersAt(scope string) []string { var out []string if scope == ScopeNode { out = append(out, m.Module) } for _, p := range m.Provides { if p.At() == scope { out = append(out, p.Name) } } sort.Strings(out) return out } // MachineSide says where a module's declared port reaches this machine, and whether the mesh is // free to choose it. // // **The mesh may only move a port it actually publishes** (novox/hq ADR 0038). A container's // mapping is the thing that translates, so where there is one the mesh can put the machine side // anywhere it likes. Where there is not, the software binds what it binds: assigning a port then // does not move the service, it just opens the wrong number in the rule set and leaves the real // one shut — a firewall that reports success and blocks the thing it was asked to admit. // // Three cases, and only the first belongs to the mesh: // // - a container publishes it in short form — the mesh chooses // - a container publishes it as host:container — the manifest already chose // - nothing publishes it — whatever binds it, binds it // // Either side of a long mapping counts as naming it, and the host side is what comes back. A // module may reasonably read `listens` as the port its software uses or as the port the machine // exposes, and both readings have the same right answer here. func (m Manifest) MachineSide(port int) (at int, mayAssign bool) { for _, r := range m.Resources { if fmt.Sprint(r["type"]) != "container" { continue } listed, ok := r["ports"].([]any) if !ok { continue } for _, entry := range listed { written := strings.TrimSpace(fmt.Sprint(entry)) // "8080", "8080:80", or "127.0.0.1:8080:80" when an address was named — the machine // side is always the second-from-last part, the same reading the host applies. The // first shape said only the software's port, so the mesh may choose; the others chose. parts := strings.Split(written, ":") if len(parts) == 1 { if n, err := strconv.Atoi(written); err == nil && n == port { return port, true } continue } outer, err := strconv.Atoi(strings.TrimSpace(parts[len(parts)-2])) if err != nil { continue } inner, err := strconv.Atoi(strings.TrimSpace(parts[len(parts)-1])) if err == nil && (outer == port || inner == port) { return outer, false } } } return port, false } // EndpointPort is the port of the endpoint a module calls this, and whether it has one. func EndpointPort(m Manifest, name string) (int, bool) { want := strings.TrimSpace(name) if want == "" { return 0, false } for _, l := range m.Listens { if strings.TrimSpace(l.Name) == want { return l.Port, true } } return 0, false } // MaxReplaced is the longest command a tool may say it replaces: a command's name and the words that // make it this command, never a script. const MaxReplaced = 80 // How a module takes one of its own secrets (ADR 0114): read from the file when it starts, or // applied by its own code to a backend that takes it once. const ( TakenAtStart = "at-start" TakenApplied = "applied" ) // IssuedOutside says a value was issued by a party outside the mesh — a vendor's API key, a bot's // token, a licence — so no value the mesh makes would work in its place (novox/hq ADR 0228). const IssuedOutside = "outside" // OwnSecret is where one of a module's own secrets lands, how the module takes it, and — for a // value only an outside party can issue — that it is one. type OwnSecret struct { Path string Taken string IssuedBy string // Prompt is the one line the desk asks for this secret as, in place of its bare name (novox/hq // issue 789): at most PromptMax characters, one line, holding only the {member} placeholder — a // family's member suffix, filled where the secret is asked for. Optional; reviewed in the // module's pull request like the rest of the manifest. Prompt string // Owner is the account this secret's files belong to on the machine, in place of the module's // secrets-owner (novox/hq ADR 0436 §1): an account the module makes (a `user` resource of that // name), never root and never the operator account. Empty means the module's secrets-owner, or // root where that is absent too. Owner string } // MeshMayMake says the mesh may put a value it makes in place of the one the secret holds: the // module reads it as it starts, and nobody outside the mesh issued it (novox/hq ADR 0228). A value // given to the mesh for such a secret lives only until the module's first good start under the // mesh; anything else given stays as given. func (s OwnSecret) MeshMayMake() bool { return s.Taken == TakenAtStart && s.IssuedBy != IssuedOutside } // PromptMax is the longest an own secret's prompt may be (novox/hq issue 789): one line, short enough that the // desk's prompt reads at a glance. const PromptMax = 120 // OwnSecrets is a module's own secrets by name. On the wire each is a path, or an object naming // the path and how it is taken; written back the way it was read, so a manifest the mesh holds // keeps its bytes. type OwnSecrets map[string]OwnSecret func (o *OwnSecrets) UnmarshalJSON(raw []byte) error { var entries map[string]json.RawMessage if err := json.Unmarshal(raw, &entries); err != nil { return err } out := make(OwnSecrets, len(entries)) for name, body := range entries { var path string if err := json.Unmarshal(body, &path); err == nil { out[name] = OwnSecret{Path: path} continue } var long struct { Path string `json:"path"` Taken string `json:"taken,omitempty"` IssuedBy string `json:"issued-by,omitempty"` Prompt string `json:"prompt,omitempty"` Owner string `json:"owner,omitempty"` } dec := json.NewDecoder(bytes.NewReader(body)) dec.DisallowUnknownFields() if err := dec.Decode(&long); err != nil { return fmt.Errorf("own-secrets.%s: a path, or {\"path\", \"taken\", \"issued-by\", \"prompt\", \"owner\"}: %w", name, typedUnknown(err)) } out[name] = OwnSecret{Path: long.Path, Taken: long.Taken, IssuedBy: long.IssuedBy, Prompt: long.Prompt, Owner: long.Owner} } *o = out return nil } func (o OwnSecrets) MarshalJSON() ([]byte, error) { entries := make(map[string]any, len(o)) for name, s := range o { if s.Taken == "" && s.IssuedBy == "" && s.Prompt == "" && s.Owner == "" { entries[name] = s.Path continue } long := map[string]string{"path": s.Path} if s.Taken != "" { long["taken"] = s.Taken } if s.IssuedBy != "" { long["issued-by"] = s.IssuedBy } if s.Prompt != "" { long["prompt"] = s.Prompt } if s.Owner != "" { long["owner"] = s.Owner } entries[name] = long } return json.Marshal(entries) } // A secret family (novox/hq ADR 0283): an own secret declared under a name ending in FamilySuffix is one // member per part the module's settings name — `smb-password-*` holds `smb-password-games`, // `smb-password-library` — each given by its full name, placed at the family's path with its one `*` replaced // by what follows the prefix. The mesh never makes a member: a family is issued outside the mesh, and a member // not given is no file. const FamilySuffix = "-*" // memberRest is what may follow a family's prefix: a name's characters. var memberRest = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*$`) // IsFamily says an own secret's declared name is a family's. func IsFamily(name string) bool { return strings.HasSuffix(name, FamilySuffix) } // FamilyPrefix is what every member of a family begins with: the declared name without its `*`. func FamilyPrefix(family string) string { return strings.TrimSuffix(family, "*") } // Lookup resolves an own secret by the name it is given under: declared by that name, or a member of a family // (the longest prefix that fits), with the family's path filled for the member. family is the family's // declared name, or "" for a secret declared by name. func (o OwnSecrets) Lookup(name string) (s OwnSecret, family string, ok bool) { if s, ok := o[name]; ok && !IsFamily(name) { return s, "", true } for declared, f := range o { if !IsFamily(declared) { continue } prefix := FamilyPrefix(declared) rest := strings.TrimPrefix(name, prefix) if !strings.HasPrefix(name, prefix) || !memberRest.MatchString(rest) { continue } if family == "" || len(declared) > len(family) { s, family, ok = OwnSecret{Path: strings.Replace(f.Path, "*", rest, 1), Taken: f.Taken, IssuedBy: f.IssuedBy, Prompt: f.Prompt, Owner: f.Owner}, declared, true } } return s, family, ok } // Plain is every own secret declared by its own name: what the mesh makes when not given, and places by // name. A family is not one, and is never made. func (o OwnSecrets) Plain() OwnSecrets { out := make(OwnSecrets, len(o)) for name, s := range o { if !IsFamily(name) { out[name] = s } } return out } // Families is every family's declared name, sorted. func (o OwnSecrets) Families() []string { var out []string for name := range o { if IsFamily(name) { out = append(out, name) } } sort.Strings(out) return out } // Paths is each own secret's path by name — the shape every placement and file walk reads. func (o OwnSecrets) Paths() map[string]string { out := make(map[string]string, len(o)) for name, s := range o { out[name] = s.Path } return out } // InstancesInterchangeable is the one value of a definition's `instances`: the module is the same // on every machine, so any instance may answer for the module. const InstancesInterchangeable = "interchangeable" // WhileStopped is the resource key naming the containers a scheduled step holds still while it // runs (novox/hq ADR 0189). Carried to the host unchanged, like `schedule`. const WhileStopped = "while-stopped" // InvokedVerbs is the verbs of a manifest's `invokes` in either form, a verb or {verb, fields} (design 47 G §558, A-275): the // one reader of the field for a part that holds no Manifest. An entry of neither form is an error, never none. func InvokedVerbs(raw json.RawMessage) ([]string, error) { keys := map[string]json.RawMessage{"invokes": raw} if _, err := readInvokes(keys); err != nil { return nil, err } var verbs []string if err := json.Unmarshal(keys["invokes"], &verbs); err != nil { return nil, fmt.Errorf("invokes: a list of verbs, or of {verb, fields}: %w", err) } return verbs, nil }