{ "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.", "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" }, "caps": { "type": "object", "description": "the sum of the bus's caps against its limits, in MiB; an absent limit is unlimited (design 47 G 547, 661)", "properties": { "sum-mib": { "type": "integer", "minimum": 0 }, "account-limit-mib": { "type": "integer", "minimum": 0 }, "server-limit-mib": { "type": "integer", "minimum": 0 } }, "required": [ "sum-mib" ] } }, "required": [ "entries" ] }, "optional": true }, { "name": "show", "description": "One entry, its template, settings and fill.", "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.", "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.", "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.", "input": { "$ref": "#/defs/Entry" }, "answer": { "$ref": "#/defs/Held" }, "optional": true, "class": "act" }, { "name": "apply", "description": "Apply a difference that only grows: a larger cap, a longer age.", "input": { "$ref": "#/defs/Named" }, "answer": { "$ref": "#/defs/Held" }, "optional": true, "class": "act" }, { "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.", "input": { "$ref": "#/defs/Warranted" }, "answer": { "$ref": "#/defs/Held" }, "optional": true, "class": "warrant" }, { "name": "drop", "description": "Remove one orphan, after a stream snapshot.", "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, "class": "warrant" } ], "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" }, "binding": { "$ref": "#/defs/Binding", "description": "the binding a module receives for the entry, as created and recreated carry it; present on an entry whose objects the bus holds, absent on one it does not (design 25 bindings-first-view §2)" } }, "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": { "local": { "type": "string", "description": "the entry's local name in the module's manifest" }, "storage": { "type": "string", "description": "how the bus keeps it: the entry's storage type" }, "template": { "type": "string", "description": "its template" }, "stream": { "type": "string", "description": "a stream's name on the bus" }, "subject": { "type": "string", "description": "the subject a stream's messages are on; also a ledger's history's" }, "bucket": { "type": "string", "description": "a key-value bucket's name" }, "object-store": { "type": "string", "description": "an object store's name" }, "objects": { "type": "string", "description": "the bus name of the state's -objects, where its large values go (design 47 G 58, 399)" }, "history": { "type": "string", "description": "a ledger's history stream" }, "state": { "type": "string", "description": "a ledger's state bucket" }, "indexes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "a ledger's index buckets, by index name" }, "snapshot": { "type": "string", "description": "the subject of a ledger's instances' snapshots" }, "types": { "type": "array", "items": { "type": "object" }, "description": "a ledger's types, as its manifest declares them" } }, "required": [ "local", "storage" ], "description": "the binding a module receives in its membership for one entry (ADR 0595 §1, §7): the names on the bus of the entry's objects, one form in the events, in list, show and orphans, and in the membership" } } }