Files
inbuxa-installer/internal/topology/topology.go
T
jcoffey-dev 15fdb171fe
ci / test (pull_request) Successful in 1m28s
Add inbuxa cluster join: configure a node into a cluster
Topology version 2 adds an optional cluster block to a server machine:
where this node reaches the shared SQL store, the coordinator and the
blob store, what role it takes, and what it must start after. Every
address in it is the operator's; the installer bakes in none of its own,
and a file with no cluster block is read exactly as before.

inbuxa cluster join -f FILE acts on this machine's block: it installs the
secrets every node reads from disk, points the server at the shared store
(keeping the old config.json aside for rollback), writes the hostname,
role and boot-order drop-ins, and restarts. --dry-run prints every file
it would write and stops. It is the node's half only; the shared registry
that names the blob store and coordinator is set up once per cluster, not
by each node that joins.
2026-11-12 07:02:19 -07:00

321 lines
12 KiB
Go

// SPDX-FileCopyrightText: 2026 Coffey Labs LLC
// SPDX-License-Identifier: AGPL-3.0-or-later
// Package topology is the description of a whole installation: which machine
// runs what, under which names, reachable from where.
//
// One file, however many machines. Each machine reads the same file and acts
// on its own part of it -- so the file is the thing an operator keeps, diffs
// and reviews, and no machine ever reaches another. That is the whole design:
// the designer, whatever draws it, emits this; `inbuxa apply -f` on each
// machine is the only thing with privileges.
//
// Version 1 described front ends scaled out across machines, not a clustered
// mail server: one server, as many webmails and consoles as there are machines
// to put them on. Version 2 adds the second case without a new file: a machine
// that runs the server may carry a cluster block, which says where this node's
// shared store, coordinator and blob store are and what role it takes. The
// addresses in it are the operator's; nothing in the file is specific to any
// one cluster. A file with no cluster block is still a version 1 file in every
// way that matters, and this installer reads both.
package topology
import (
"encoding/json"
"fmt"
"os"
"sort"
"strings"
)
// Topology is the file.
type Topology struct {
Version int `json:"version"`
Domain string `json:"domain"`
MailHost string `json:"mail_host,omitempty"`
ConsoleHost string `json:"console_host,omitempty"`
WebmailHost string `json:"webmail_host,omitempty"`
ACMEEmail string `json:"acme_email,omitempty"`
Machines []Machine `json:"machines"`
}
// Machine is one host, named by the operator. The name is how a machine
// recognises its own part of the file; it defaults to the hostname, which is
// what most people will call it anyway.
type Machine struct {
Name string `json:"name"`
Components []Component `json:"components"`
Proxy string `json:"proxy,omitempty"` // caddy, snippets, none
Dir string `json:"dir,omitempty"`
Cluster *ClusterNode `json:"cluster,omitempty"` // version 2: this node's place in a cluster
}
// Component is one program on one machine.
type Component struct {
Kind string `json:"kind"` // server, console, webmail
Shape string `json:"shape"` // container, host
}
// ClusterNode is a server machine's membership in a clustered install: the
// shared data store this node reads and writes, the coordinator and blob store
// every node reaches, the node's role, and what it must start after. Every
// address in it is the operator's; the installer bakes in none of its own.
//
// What a joining node needs on disk is a store it can reach and the secrets
// the shared registry's File references point at. The coordinator and blob
// store are named here so the file is complete and so their secrets are placed
// beside the store's; the registry that points the cluster at them is set up
// once, as its own step, not by every node that joins.
type ClusterNode struct {
Store ClusterStore `json:"store"` // this node's shared data store (required)
Coordinator *ClusterService `json:"coordinator,omitempty"` // the message coordinator every node reads
BlobStore *ClusterBlob `json:"blob_store,omitempty"` // the blob store every node reads
Role string `json:"role,omitempty"` // the node's cluster role; empty on the node that carries every task
Hostname string `json:"hostname,omitempty"` // what the node calls itself (INBUXA_HOSTNAME); the machine name by default
After []string `json:"after,omitempty"` // units this node must start after, so it reaches the store at boot
}
// ClusterStore is the shared store a node points its server at, in place of
// the single-node built-in store. It is a SQL store: the one kind more than
// one server can share.
type ClusterStore struct {
Type string `json:"type"` // the server store type, e.g. "PostgreSql"
Host string `json:"host"` // where this node reaches the store
Port int `json:"port"` //
Database string `json:"database"` //
User string `json:"user"` // the database user
SecretFile string `json:"secret_file"` // the file the server reads the password from
SecretFrom string `json:"secret_from,omitempty"` // a source to install that file from, 0400; empty means it is already there
TLS bool `json:"tls,omitempty"` //
PoolMax int `json:"pool_max,omitempty"` // connections in the pool; a sensible default when zero
}
// ClusterService is the coordinator (the message bus nodes agree through): the
// address the registry names, and the secret each node reads from a local file.
type ClusterService struct {
Addr string `json:"addr"` // host:port
User string `json:"user,omitempty"` //
SecretFile string `json:"secret_file"` // the file the server reads the secret from
SecretFrom string `json:"secret_from,omitempty"` // a source to install it from, 0400; empty means already there
}
// ClusterBlob is the blob store (where message bodies live): the endpoint the
// registry names, and the secret each node reads from a local file.
type ClusterBlob struct {
Endpoint string `json:"endpoint"` // the S3 endpoint, host:port or URL
Bucket string `json:"bucket,omitempty"` //
Region string `json:"region,omitempty"` //
SecretFile string `json:"secret_file"` // the file the server reads the secret key from
SecretFrom string `json:"secret_from,omitempty"` // a source to install it from, 0400; empty means already there
}
// Clustered says whether this machine carries cluster configuration.
func (m Machine) Clustered() bool { return m.Cluster != nil }
const Version = 2
var kinds = map[string]bool{"server": true, "console": true, "webmail": true}
var shapes = map[string]bool{"container": true, "host": true}
// Load reads a topology file and checks that it describes something that
// could exist. A file that cannot be installed should fail here, where the
// message can name the line's subject, rather than half way through an apply.
func Load(path string) (*Topology, error) {
b, err := os.ReadFile(path)
if err != nil {
return nil, err
}
var t Topology
dec := json.NewDecoder(strings.NewReader(string(b)))
dec.DisallowUnknownFields()
if err := dec.Decode(&t); err != nil {
return nil, fmt.Errorf("%s: %w", path, err)
}
if err := t.Validate(); err != nil {
return nil, fmt.Errorf("%s: %w", path, err)
}
return &t, nil
}
// Validate is the rules. They are few on purpose: this describes front ends
// spread over machines, and the interesting refusals are about arrangements
// that cannot work rather than about syntax.
func (t *Topology) Validate() error {
if t.Version < 1 || t.Version > Version {
return fmt.Errorf("version %d: this installer reads versions 1 to %d", t.Version, Version)
}
if t.Domain == "" {
return fmt.Errorf("no domain")
}
t.Defaults()
if len(t.Machines) == 0 {
return fmt.Errorf("no machines")
}
seen := map[string]bool{}
servers, clustered := 0, 0
for _, m := range t.Machines {
if m.Name == "" {
return fmt.Errorf("a machine has no name")
}
if seen[m.Name] {
return fmt.Errorf("two machines are called %q", m.Name)
}
seen[m.Name] = true
if len(m.Components) == 0 {
return fmt.Errorf("machine %q runs nothing", m.Name)
}
kindsHere := map[string]bool{}
for _, c := range m.Components {
if !kinds[c.Kind] {
return fmt.Errorf("machine %q: %q is not a component (server, console, webmail)", m.Name, c.Kind)
}
if !shapes[c.Shape] {
return fmt.Errorf("machine %q: %q is not a shape (container, host)", m.Name, c.Shape)
}
if kindsHere[c.Kind] {
// Two webmails on one machine would need two ports and two
// names, and nothing here says which. Two machines is the
// supported way to have two.
return fmt.Errorf("machine %q runs two %ss; put the second on another machine", m.Name, c.Kind)
}
kindsHere[c.Kind] = true
if c.Kind == "server" {
servers++
}
}
if m.Cluster != nil {
if t.Version < 2 {
return fmt.Errorf("machine %q has a cluster block, which needs version 2", m.Name)
}
if !kindsHere["server"] {
return fmt.Errorf("machine %q has a cluster block but runs no mail server; only a server joins a cluster", m.Name)
}
if err := m.Cluster.validate(m.Name); err != nil {
return err
}
clustered++
}
}
switch {
case servers == 0:
return fmt.Errorf("no machine runs the mail server")
case servers == 1:
// One server, clustered or not, is always allowed.
case clustered == servers:
// Every mail node carries cluster configuration: a clustered install.
default:
return fmt.Errorf("%d machines run the mail server but %d carry a cluster block: "+
"a clustered install needs one on every mail node, or run a single server", servers, clustered)
}
return nil
}
// validate checks a cluster node describes a store the installer can point a
// server at and secrets it can place. The addresses themselves are the
// operator's to get right; what it refuses is a block that cannot be acted on.
func (c *ClusterNode) validate(machine string) error {
fail := func(f string, a ...any) error {
return fmt.Errorf("machine %q cluster: %s", machine, fmt.Sprintf(f, a...))
}
s := c.Store
switch {
case s.Type == "":
return fail("the store needs a type, e.g. \"PostgreSql\"")
case s.Host == "":
return fail("the store needs a host")
case s.Port <= 0 || s.Port > 65535:
return fail("the store port %d is not a port", s.Port)
case s.Database == "":
return fail("the store needs a database name")
case s.User == "":
return fail("the store needs a user")
case s.SecretFile == "":
return fail("the store needs a secret_file: where the server reads the password")
}
if c.Coordinator != nil {
if c.Coordinator.Addr == "" {
return fail("the coordinator needs an addr")
}
if c.Coordinator.SecretFile == "" {
return fail("the coordinator needs a secret_file")
}
}
if c.BlobStore != nil {
if c.BlobStore.Endpoint == "" {
return fail("the blob store needs an endpoint")
}
if c.BlobStore.SecretFile == "" {
return fail("the blob store needs a secret_file")
}
}
return nil
}
// Defaults fills in the names that follow from the domain.
func (t *Topology) Defaults() {
if t.MailHost == "" {
t.MailHost = "mail." + t.Domain
}
if t.ConsoleHost == "" {
t.ConsoleHost = "admin." + t.Domain
}
if t.WebmailHost == "" {
t.WebmailHost = "webmail." + t.Domain
}
if t.ACMEEmail == "" {
t.ACMEEmail = "postmaster@" + t.Domain
}
for i := range t.Machines {
if t.Machines[i].Dir == "" {
t.Machines[i].Dir = "/var/lib/inbuxa"
}
if t.Machines[i].Proxy == "" {
t.Machines[i].Proxy = "caddy"
}
}
}
// Machine finds one by name.
func (t *Topology) Machine(name string) (Machine, bool) {
for _, m := range t.Machines {
if m.Name == name {
return m, true
}
}
return Machine{}, false
}
// Others is every machine but this one, for the part of a plan that says what
// has to be run elsewhere. Nothing here reaches them: it prints the command
// and leaves it to the operator, which is the point.
func (t *Topology) Others(name string) []Machine {
var out []Machine
for _, m := range t.Machines {
if m.Name != name {
out = append(out, m)
}
}
sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
return out
}
// Shape is what this machine runs a component as, or "" for not at all.
func (m Machine) Shape(kind string) string {
for _, c := range m.Components {
if c.Kind == kind {
return c.Shape
}
}
return ""
}
// Save writes a topology file, formatted to be read and diffed by people.
func (t *Topology) Save(path string) error {
b, err := json.MarshalIndent(t, "", " ")
if err != nil {
return err
}
return os.WriteFile(path, append(b, '\n'), 0o644)
}