mesh-sdk/go/compose/input.go

// Package compose is the controller's composition of a machine, as a function over a plain input (novox/hq ADR 0453
// clause 3, ADR 0446 clause 4): what the rest of the mesh offers and holds, the private network's generator, one
// node's resolution and, in the issues after, its rendering and its declaration.
//
// **It never allocates, makes, writes, logs or raises.** The controller composes with a store behind it; this
// package is its Reading and Foreseeing modes over data. Everything the controller reads from its store is a field of
// Input, and everything a send would make or record (a port, a credential, a seat passed on, a node left out) is
// returned for the caller to act on, never done. Input is never changed by a call. No field holds a secret value
// the composition needs: sealed values are optional inputs, and without them the composition uses stand-ins named
// foreseen. The logic is the controller's, ported from mesh-controller cmd/mesh-controller at commit
// 6c2a8d62100cb7d491f8eb9a623e1eeea5ec0de1 (plan.go, network.go, holdings.go, seat_pass.go), in the same order, with the
// same refusals in the same words, so that a comparison node for node is a fair one.
//
// It imports the standard library and mesh-sdk's own packages only.
package compose

import (
	"errors"
	"fmt"
	"sort"
	"strings"

	"git.novox.be/novox/mesh-sdk/go/catalogue"
)

// Input is everything the composition reads. Each field is what one read of the controller's inventory answers, named
// beside it; the controller's adapter fills it from its stores and the assigner from the mesh's facts and buckets
// (ADR 0446 clause 2).
type Input struct {
	// Catalogue is the shelf: every module's manifest by name (inv.Catalogue), as it is to be composed. A recorded
	// module kept at the build a machine runs (keepRecorded) is already in it, put there by the caller.
	Catalogue map[string]catalogue.Manifest
	// Nodes is every node the mesh has (inv.Nodes and inv.Overlays together, one row per node).
	Nodes []Node
	// Holdings is every seat whose holder is on record (inv.Holdings).
	Holdings []catalogue.Held
	// Licences is every licence the mesh holds, with the machines that use it (open.Licences); none for a mesh with no
	// licence.
	Licences []Licence

	// OverlayCIDR is the range the mesh allocates from when no tunnel was adopted, as genesis was told it (the
	// controller's OverlayCIDRVar); empty means DefaultOverlayCIDR. The package reads no environment.
	OverlayCIDR string
	// Tunnels is, by node name, the found tunnel whose key is the node's overlay key (inv.Tunnels).
	Tunnels map[string]FoundTunnel
	// Adopted is the hub's found tunnel and the hub's name, whether or not the hub took it (inv.AdoptedTunnel); nil
	// when no hub has one.
	Adopted *AdoptedTunnel
	// CarriedPeers is every peer of the adopted tunnel (inv.CarriedPeers).
	CarriedPeers []CarriedPeer
	// Joining is the nodes that hold a live enrolment token (inv.NodesWithALiveToken).
	Joining []string
}

// Node is one node of the mesh and what the composition reads about it.
type Node struct {
	Name string
	// Place is where it is on the private network (inv.Overlays).
	Place Place
	// Assigned is the modules assigned to it, in the order the controller reads them (inv.Assigned).
	Assigned []string
	// Capabilities are the ones present on it (inv.ProfileOf).
	Capabilities map[string]bool
	// PublicDomain is the domain it composes its routed names under (inv.PublicDomainOf).
	PublicDomain string
	// Account, AccountHome, AgentAccount and AgentAccountHome are its operator and agent logins (inv.NodeByName).
	Account, AccountHome, AgentAccount, AgentAccountHome string
	// Adopted is whether it is adopted rather than converged.
	Adopted bool
	// Pins is the provider each provision was pinned to for it (inv.PinsFor).
	Pins map[string]catalogue.Chosen
	// Bound is where each of its consumers of a provision that keeps data was last sent (inv.BindingsFor), by consumer
	// module and provision.
	Bound map[string]map[string]catalogue.Chosen
	// Settings is its settings layers by module (inv.SettingsFor); a module with none is absent.
	Settings map[string][]catalogue.Layer
	// Ports is the machine port each module's software port was given on it (inv.PortsFor), by module then port.
	Ports map[string]map[int]int
}

// Place is where a node is, as its placement says (inv.Overlay).
type Place struct {
	Key      string
	Endpoint string
	Site     string
	Hub      bool
	Address  string
}

// Reachable says whether the node can be dialled.
func (p Place) Reachable() bool { return strings.TrimSpace(p.Endpoint) != "" }

// Tunnel is a tunnel found on a node (inv.Tunnel).
type Tunnel struct {
	Interface string
	Unit      string
	Config    string
	Port      int
	MTU       int
	// Address is the interface's own address with its prefix length, Range the network that prefix names.
	Address   string
	Range     string
	PublicKey string
	Peers     []TunnelPeer
}

// TunnelPeer is one peer of a found tunnel.
type TunnelPeer struct {
	PublicKey string
	Address   string
}

// FoundTunnel is a node's tunnel and whether the node is adopted (inv.FoundTunnel).
type FoundTunnel struct {
	Tunnel
	NodeAdopted bool
}

// AdoptedTunnel is the hub's tunnel, the hub's name, and whether the hub's overlay key is the tunnel's, which is
// whether the private network took the tunnel over.
type AdoptedTunnel struct {
	Tunnel  Tunnel
	Hub     string
	Adopted bool
}

// CarriedPeer is a peer of the adopted tunnel (inv.CarriedPeer).
type CarriedPeer struct {
	PublicKey  string
	Address    string
	EnrolledAs string
	Named      string
}

// Licence is one licence the mesh holds: its name, what a consumer may know of it, and the machines and modules
// that use it.
type Licence struct {
	Name    string
	Serves  map[string]any
	Holders []Holder
}

// Holder is a module on a node that uses a licence.
type Holder struct {
	Node   string
	Module string
}

// ErrNoSuchNode is what the controller's inventory answers for a node it does not have.
var ErrNoSuchNode = errors.New("no node of that name")

// node is the node of that name, or the refusal the controller's inventory gives for one it does not have.
func (in Input) node(name string) (Node, error) {
	for _, n := range in.Nodes {
		if n.Name == name {
			return n, nil
		}
	}
	return Node{}, fmt.Errorf("%w: %s", ErrNoSuchNode, name)
}

// sorted is the nodes by name, the order the controller reads them in.
func (in Input) sorted() []Node {
	out := append([]Node(nil), in.Nodes...)
	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
	return out
}