{ "format": 1, "seat": "mesh-broker", "scope": "mesh", "grain": "whole", "domain": "Core", "decision": "novox/hq ADR 0079", "delivers": "mesh-bus", "description": "The mesh's bus, and the bus state modules ask of it in requires (design 25 § 12). create, apply, recreate and drop are granted to the bus module's own credential alone.", "verbs": [ { "name": "list", "description": "Every entry the bus module created, its template, its settings and its fill against its cap.", "callers": "any caller whose role grants it", "input": { "type": "object", "properties": { "module": { "type": "string", "description": "one module (optional)" } } }, "answer": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/defs/Held" }, "description": "every entry" } }, "required": [ "entries" ] }, "optional": true }, { "name": "show", "description": "One entry, its template, settings and fill.", "callers": "any caller whose role grants it", "input": { "$ref": "#/defs/Named" }, "answer": { "$ref": "#/defs/Held" }, "optional": true }, { "name": "check", "description": "Compare what the bus holds with what was asked, entry by entry; a difference that only grows is said as such.", "callers": "any caller whose role grants it", "input": { "type": "object", "properties": { "module": { "type": "string", "description": "one module (optional)" } } }, "answer": { "type": "object", "properties": { "differences": { "type": "array", "items": { "type": "object", "properties": { "module": { "type": "string", "description": "the module" }, "local-name": { "type": "string", "description": "the entry" }, "asked": { "type": "object", "description": "asked" }, "held": { "type": "object", "description": "held" }, "grows": { "type": "boolean", "description": "the difference only grows: apply may act on it" } }, "required": [ "module", "local-name" ] }, "description": "every difference" } }, "required": [ "differences" ] }, "optional": true }, { "name": "orphans", "description": "Entries the bus holds that no manifest asks for; never one whose manifest the judge refused or outgrew, nor one of the foundation's old sections.", "callers": "any caller whose role grants it", "input": { "type": "object", "properties": {}, "description": "no arguments" }, "answer": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/defs/Held" }, "description": "every orphan" } }, "required": [ "entries" ] }, "optional": true }, { "name": "create", "description": "Create one entry now.", "callers": "the bus module's own process only", "input": { "$ref": "#/defs/Entry" }, "answer": { "$ref": "#/defs/Held" }, "optional": true }, { "name": "apply", "description": "Apply a difference that only grows: a larger cap, a longer age.", "callers": "the bus module's own process only", "input": { "$ref": "#/defs/Named" }, "answer": { "$ref": "#/defs/Held" }, "optional": true }, { "name": "recreate", "description": "Rebuild an entry whose settings differ in a way that cannot grow, from its data where the storage type allows, after a stream snapshot.", "callers": "the bus module's process, on the operator's warrant", "input": { "$ref": "#/defs/Warranted" }, "answer": { "$ref": "#/defs/Held" }, "optional": true }, { "name": "drop", "description": "Remove one orphan, after a stream snapshot.", "callers": "the bus module's process, on the operator's warrant", "input": { "$ref": "#/defs/Warranted" }, "answer": { "type": "object", "properties": { "dropped": { "type": "boolean", "description": "it is gone" }, "snapshot": { "type": "string", "description": "the snapshot taken first" } }, "required": [ "dropped" ] }, "optional": true } ], "events": [ { "name": "created", "body": { "$ref": "#/defs/Said" } }, { "name": "refused", "body": { "$ref": "#/defs/Said" } }, { "name": "drifted", "body": { "$ref": "#/defs/Said" } }, { "name": "drift-cleared", "body": { "$ref": "#/defs/Said" } }, { "name": "full", "body": { "$ref": "#/defs/Said" } }, { "name": "full-cleared", "body": { "$ref": "#/defs/Said" } }, { "name": "orphaned", "body": { "$ref": "#/defs/Said" } }, { "name": "recreated", "body": { "$ref": "#/defs/Said" } }, { "name": "dropped", "body": { "$ref": "#/defs/Said" } } ], "family": { "name": "mesh-broker.events", "max-age-days": 7 }, "provisions": [ { "name": "bus-state", "form": { "$ref": "#/defs/Binding" } } ], "defs": { "Entry": { "type": "object", "properties": { "module": { "type": "string", "description": "the module asking it" }, "local-name": { "type": "string", "description": "its local name in the module's manifest" }, "storage-type": { "type": "string", "enum": [ "stream", "key-value", "object-store", "ledger" ], "description": "how the bus keeps it" }, "template": { "type": "string", "enum": [ "state", "events", "work-queue", "log", "objects", "ledger", "" ], "description": "its template; empty for a configuration of its own" }, "options": { "type": "object", "description": "the template's options the module set, within their bounds" }, "configuration": { "type": "object", "description": "its own configuration, where no template fits" } }, "required": [ "module", "local-name", "storage-type" ], "description": "one piece of bus state as a manifest asks it" }, "Fill": { "type": "object", "properties": { "count": { "type": "integer", "description": "messages, keys or objects held" }, "bytes": { "type": "integer", "description": "bytes held" }, "cap": { "type": "integer", "description": "its cap in bytes" } }, "required": [ "count", "bytes", "cap" ] }, "Held": { "type": "object", "properties": { "module": { "type": "string", "description": "the module asking it" }, "local-name": { "type": "string", "description": "its local name in the module's manifest" }, "storage-type": { "type": "string", "enum": [ "stream", "key-value", "object-store", "ledger" ], "description": "how the bus keeps it" }, "template": { "type": "string", "enum": [ "state", "events", "work-queue", "log", "objects", "ledger", "" ], "description": "its template; empty for a configuration of its own" }, "options": { "type": "object", "description": "the template's options the module set, within their bounds" }, "configuration": { "type": "object", "description": "its own configuration, where no template fits" }, "bus-name": { "type": "string", "description": "its name on the bus, _" }, "settings": { "type": "object", "description": "the settings the bus holds" }, "fill": { "$ref": "#/defs/Fill" }, "state": { "type": "string", "enum": [ "held", "refused", "waiting", "drifted", "full", "orphaned" ], "description": "the entry's state: held as asked, refused, waiting to be made, drifted from what is asked, full, or orphaned (no manifest asks it)" }, "why": { "type": "string", "description": "why it is in its state, in plain words; empty when held as asked" } }, "required": [ "module", "local-name", "storage-type", "bus-name" ], "description": "one entry as the bus holds it" }, "Said": { "type": "object", "properties": { "module": { "type": "string", "description": "the module asking it" }, "local-name": { "type": "string", "description": "its local name in the module's manifest" }, "storage-type": { "type": "string", "enum": [ "stream", "key-value", "object-store", "ledger" ], "description": "how the bus keeps it" }, "template": { "type": "string", "enum": [ "state", "events", "work-queue", "log", "objects", "ledger", "" ], "description": "its template; empty for a configuration of its own" }, "options": { "type": "object", "description": "the template's options the module set, within their bounds" }, "configuration": { "type": "object", "description": "its own configuration, where no template fits" }, "bus-name": { "type": "string", "description": "its name on the bus" }, "asked": { "type": "object", "description": "the settings asked" }, "held": { "type": "object", "description": "the settings held" }, "why": { "type": "string", "description": "why: a refusal's cause, a drift's difference, a drop's or recreate's reason" }, "fill": { "$ref": "#/defs/Fill" }, "snapshot": { "type": "string", "description": "the stream snapshot taken before a recreate or drop" }, "binding": { "$ref": "#/defs/Binding" }, "revision": { "type": "integer", "description": "the indexer's revision of the verdict the bus module acted on (ADR 0622 §2), so a reader orders what it hears" } }, "required": [ "module", "local-name", "bus-name" ], "description": "the body of every event of the seat" }, "Named": { "type": "object", "properties": { "module": { "type": "string", "description": "the module" }, "local-name": { "type": "string", "description": "the entry's local name" } }, "required": [ "module", "local-name" ] }, "Warranted": { "type": "object", "properties": { "module": { "type": "string", "description": "the module" }, "local-name": { "type": "string", "description": "the entry's local name" }, "warrant": { "type": "string", "description": "the operator's warrant, as the operator channel decided it (ADR 0259 §6)" }, "why": { "type": "string", "description": "why, kept in the record" } }, "required": [ "module", "local-name", "warrant", "why" ] }, "Binding": { "type": "object", "properties": { "bus-name": { "type": "string", "description": "the entry's name on the bus" }, "storage-type": { "type": "string", "description": "how the bus keeps it" }, "template": { "type": "string", "description": "its template" }, "subjects": { "type": "array", "items": { "type": "string" }, "description": "its subjects, for a stream" } }, "required": [ "bus-name", "storage-type" ], "description": "the binding a module receives in its membership for one entry (ADR 0595 §1, §7)" } } }