mesh-controller/internal/catalogue/seats.go

package catalogue

import (
	"fmt"
	"sort"
	"strings"
)

// The seats a mesh can have (novox/hq ADR 0110).
//
// **A closed set, defined here rather than by whoever claims one.** Until this, a well-formed name
// became a seat by being claimed, so nothing could say which seats a mesh has or who fills them:
// `the-showcase` and `the-build-machine` were each invented by the module claiming it. The set is
// what a person reads to learn what a mesh can have, so an entry nobody argued for is an entry
// nobody can explain — the same reason every shape in the host's vocabulary names its decision.
//
// A seat is held by a module assignment. What the mesh knows about a holder is what it knows about
// that assignment; nothing about holders is kept here or anywhere else.

// Seat is one role the mesh defines.
type Seat struct {
	// Name is what a manifest claims.
	Name string
	// Scope is where there may be only one holder.
	Scope string
	// Delivers is the provision the seat's holder answers for, or empty. A seat that delivers a
	// provision may only be held by a module providing it at the seat's scope, and its holder is
	// what a requirement for that provision resolves to when several modules provide it.
	Delivers string
	// Decision is the record that made it a seat.
	Decision string
}

// seats is the whole set, in the order a person reads it: the mesh's own, then a node's.
var seats = []Seat{
	{Name: "mesh-controller", Scope: ScopeMesh, Decision: "novox/hq ADR 0079"},
	{Name: "mesh-store", Scope: ScopeMesh, Delivers: "postgres-database", Decision: "novox/hq ADR 0079"},
	// What holding this delivers is the mesh's own bus (novox/hq ADR 0120): a module that speaks
	// to the mesh requires `mesh-bus` and receives an address, a sealed credential and the trust
	// to verify the server. A module that requires nothing gets no account at all — 23 of the
	// catalogue's 72 never speak, and an ambient connection would mint a credential for each.
	//
	// Corrected twice in one day, which is worth the comment. It read `amqp`, which was the old
	// broker's interface and not this seat's; ADR 0117 emptied it, reasoning that a bus cannot be
	// provisioned; and it is neither. The bus's accounts are composed by the controller rather
	// than created by a provisioner, so nothing waits on a bus account in order to make one —
	// which is a fact about the *mechanism*, not a reason the connection cannot be required.
	//
	// `mesh-bus` is the mesh's own; `nats` is a private NATS server a module may provide as a
	// backing service, the way `amqp` is provided (ADR 0119). Never the same name.
	{Name: "mesh-broker", Scope: ScopeMesh, Delivers: "mesh-bus", Decision: "novox/hq ADR 0079"},
	{Name: "the-artifact-store", Scope: ScopeMesh, Delivers: "artifact-store", Decision: "novox/hq ADR 0075"},
	{Name: "the-catalogue", Scope: ScopeMesh, Decision: "novox/hq ADR 0110"},
	{Name: "npm-package-registry", Scope: ScopeMesh, Delivers: "npm-package-registry", Decision: "novox/hq ADR 0109"},
	{Name: "git", Scope: ScopeMesh, Delivers: "git", Decision: "novox/hq ADR 0111"},
	{Name: "the-build-machine", Scope: ScopeNode, Decision: "novox/hq ADR 0110"},
	{Name: "the-dns-port", Scope: ScopeNode, Decision: "novox/hq ADR 0110"},
	{Name: "the-intrusion-prevention", Scope: ScopeNode, Decision: "novox/hq ADR 0110"},
	{Name: "the-packet-filter", Scope: ScopeNode, Decision: "novox/hq ADR 0110"},
	{Name: "the-private-network", Scope: ScopeNode, Decision: "novox/hq ADR 0110"},
	{Name: "the-resolver-configuration", Scope: ScopeNode, Decision: "novox/hq ADR 0110"},
	{Name: "the-showcase", Scope: ScopeNode, Decision: "novox/hq ADR 0110"},
}

// Seats is every seat the mesh defines, in reading order.
func Seats() []Seat {
	return append([]Seat(nil), seats...)
}

// SeatNamed is the seat a claim names, if the mesh defines one.
func SeatNamed(name string) (Seat, bool) {
	for _, s := range seats {
		if s.Name == name {
			return s, true
		}
	}
	return Seat{}, false
}

// SeatDelivering is the seat whose holder answers for a provision, if there is one.
func SeatDelivering(provision string) (Seat, bool) {
	if provision == "" {
		return Seat{}, false
	}
	for _, s := range seats {
		if s.Delivers == provision {
			return s, true
		}
	}
	return Seat{}, false
}

// claimProblems is what is wrong with a manifest's claims against the set.
//
// Three refusals, each naming the seat: a seat the mesh does not define, a seat claimed at another
// scope, and a seat that delivers a provision claimed by a module that does not provide it — which
// would make the module the mesh's answer for something it cannot answer.
func claimProblems(m Manifest) []string {
	var problems []string
	for _, c := range m.Claims {
		seat, known := SeatNamed(c.Name)
		if !known {
			problems = append(problems, fmt.Sprintf(
				"%s claims %q, which is not a seat this mesh defines (novox/hq ADR 0110) — "+
					"the seats are: %s", m.Module, c.Name, seatNames()))
			continue
		}
		if c.At() != seat.Scope {
			problems = append(problems, fmt.Sprintf(
				"%s claims %s at scope %q, and %s is a %s seat",
				m.Module, c.Name, c.At(), c.Name, seat.Scope))
		}
		if seat.Delivers != "" && !providesAt(m, seat.Delivers, seat.Scope) {
			problems = append(problems, fmt.Sprintf(
				"%s claims %s, whose holder answers for %q, and %s does not provide %q at %s scope",
				m.Module, c.Name, seat.Delivers, m.Module, seat.Delivers, seat.Scope))
		}
	}
	return problems
}

func providesAt(m Manifest, provision, scope string) bool {
	for _, o := range m.Provides {
		if o.Name == provision && o.At() == scope {
			return true
		}
	}
	return false
}

func seatNames() string {
	names := make([]string, 0, len(seats))
	for _, s := range seats {
		names = append(names, s.Name)
	}
	sort.Strings(names)
	return strings.Join(names, ", ")
}

// HolderAmong is which of several providers of a provision holds the seat that delivers it.
//
// Found by the (node, module) pair, because a provider is identified by both (novox/hq to-be 23):
// two modules on one node could both provide a provision, and only the one holding the seat
// answers for it. Nothing when no seat delivers the provision, when nobody holds
// it, or when the holder is not among the providers offered.
func HolderAmong(provision string, providers []Provider, held []Held) (Provider, bool) {
	seat, delivered := SeatDelivering(provision)
	if !delivered {
		return Provider{}, false
	}
	for _, h := range held {
		if h.Claim != seat.Name || h.Scope != seat.Scope {
			continue
		}
		for _, p := range providers {
			if p.Node == h.Node && p.Module == h.Module {
				return p, true
			}
		}
	}
	return Provider{}, false
}