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 seven verbs (ADR 0567 §10).
const (
	PlacementVerbPlacement = "placement"
	PlacementVerbProposals = "proposals"
	PlacementVerbPropose   = "propose"
	PlacementVerbWithdraw  = "withdraw"
	PlacementVerbAgain     = "again"
	PlacementVerbAdopt     = "adopt"
	PlacementVerbHandBack  = "hand-back"
)

// 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)",
		"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.",
			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,
				}}},
		{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"})},
		{Name: PlacementVerbAdopt, Optional: true, Description: "Take placement over from the controller: its " +
			"placement-export is proposed whole as the seed, every node's key, which every node must answer as the same. " +
			"Its Approve is the take-over; at the warrant the export is read again and a changed one is proposed anew.",
			Input: schema(map[string]string{"why": "why, shown to the operator"}, []string{"why"})},
		{Name: PlacementVerbHandBack, Optional: true, Description: "The operator's alone, recorded as a hand act: " +
			"delete every placement key, the history kept, so every node returns to the controller's compositions. " +
			"Refused after the lease write.",
			Input: schema(map[string]string{"why": "why, recorded with the hand act"}, []string{"why"})},
	}
}