mesh-sdk/go/catalogue/placement_seat.go

package catalogue

// The seat of placement (novox/hq ADR 0567): which module runs on which node, with its host ports, bindings, the
// node's pins and holdings, the config placement and values, and what a person decides of the node, is state on the
// bus held by this seat, changed only by a proposal the nodes it touches answer and the operator approves. Held once
// for the mesh by the assigner (mesh-delivery-assigner), beside its wants. Its states are named after the holding
// module, as every module state is (delivery.PlacementBucket, PlacementProposalsBucket, PlacementCandidatesBucket);
// they are the seat's contract, so every reader takes their names from mesh-sdk, and a change of holder is a migration
// the new holder's record decides (ADR 0567 §1). Its events are the holder's too, carried on the holder's stream
// (delivery.PlacementStream): the names are in delivery (PlacementProposedEvent and the rest).

// PlacementSeat is the seat the assigner holds for placement.
const PlacementSeat = "mesh-placement"

// The seat's five verbs (ADR 0567 §10).
const (
	PlacementVerbPlacement = "placement"
	PlacementVerbProposals = "proposals"
	PlacementVerbPropose   = "propose"
	PlacementVerbWithdraw  = "withdraw"
	PlacementVerbAgain     = "again"
)

// placementVerbs are the seat's verbs: what reads all it keeps and does by hand all it does by itself (ADR 0567 §10).
// Optional while the holder that serves them is not yet on every node (design 33 §7): the seat is new in the same
// delivery as its holder.
func placementVerbs() []Verb {
	changes := map[string]any{"type": "array", "minItems": 1, "description": "the changes, each an object with `op`: " +
		"place (node, module, ports, bindings), take-off (node, module), pin (node, provision, provider {node, module}), " +
		"unpin (node, provision), hold (node, module, claim, scope, kind, site), unhold (node, module, claim), decide " +
		"(node, field, value: a decided field of the node, its address among them), config (node, module, mesh-wide, " +
		"layer, mesh-wide-values, values), add-node (node, decided, keys: a joining node, mesh-enrolment's alone, the " +
		"proposal's one change, with the enrolment's warrant, its tunnel key alone at the operator's yes; ADR 0587 §7), " +
		"remove-node (node: a joining node never confirmed, taken off when its enrolment ends; mesh-enrolment's alone, " +
		"on the same warrant)",
		"items": map[string]any{"type": "object", "required": []string{"op", "node"}}}
	return []Verb{
		{Name: PlacementVerbPlacement, Optional: true, Description: "Read placement: one node's key, the nodes one " +
			"module is placed on, or every key, each with its revision, and how full the state is against its cap. With " +
			"history, one node's or one module's changes in order: a revision the state keeps whole, an older one as the " +
			"proposal's changes from its placement-changed event.",
			Input: schema(map[string]string{"node": "one node", "module": "one module: the nodes it is placed on",
				"history": "\"true\": the changes in order, from the stream and the state's revisions",
				// ADR 0571 clause 4: who holds which seat on which node, from the state seat-holders.
				"seats": "\"true\": who holds each seat, and on which node (the state seat-holders); with node, that node's"},
				nil, "history", "seats")},
		{Name: PlacementVerbProposals, Optional: true, Description: "Every open proposal of placement: its changes, " +
			"the revision of each key it was laid over, its candidates, every node's answer, the differences computed and " +
			"answered, its verdict and its ask. Narrowed to one by id.",
			Input: schema(map[string]string{"id": "one proposal's id"}, nil)},
		{Name: PlacementVerbPropose, Optional: true, Description: "Propose a change of placement, with why: laid over " +
			"the current keys and refused at once, naming every finding, when the result cannot be placed (two modules " +
			"on one host port, a provider not placed, a seat held once held twice, two nodes with one address, two " +
			"hubs, a module the indexer does not hold, a node with no record). Otherwise the nodes it touches compose " +
			"it in shadow and answer, and on a passing verdict the operator is asked to approve it. Who proposes is the " +
			"caller, as the runtime proves it. An add-node from mesh-enrolment, whose warrant names its node and address, " +
			"is written with no ask of its own: its Approve is the enrolment's (ADR 0587 §7).",
			Input: map[string]any{"type": "object", "additionalProperties": false, "required": []string{"why", "changes"},
				"properties": map[string]any{
					"why":     map[string]any{"type": "string", "description": "why, shown to the operator with the proposal"},
					"changes": changes,
					// ADR 0587 §7: an add-node carries the warrant of the enrolment that issued the node's token, whose
					// Approve is the proposal's; the holder writes it with no ask of its own.
					"warrant": map[string]any{"type": "object", "description": "for an add-node alone: the enrolment's " +
						"warrant {node, address, ask, warrant}, naming the change's node and address",
						"required": []string{"node", "address", "ask", "warrant"}},
				}}},
		{Name: PlacementVerbWithdraw, Optional: true, Description: "Withdraw an open proposal: its key and its " +
			"candidates are deleted and placement-withdrawn carries it whole. With why.",
			Input: schema(map[string]string{"id": "the proposal's id", "why": "why, kept in the event"}, []string{"id", "why"})},
		{Name: PlacementVerbAgain, Optional: true, Description: "Judge an open proposal now with the answers that " +
			"stand, and raise its ask again when its verdict passes and the operator's channel does not hold the ask. " +
			"Nothing more: the recovery of a proposal whose judgement or ask was lost.",
			Input: schema(map[string]string{"id": "the proposal's id"}, []string{"id"})},
	}
}