cluster: introduce NodeID and ZoneID types

Signed-off-by: Alejandro Mery <amery@jpi.io>

cmd/jpictl/dns.go

@@ -52,7 +52,7 @@ func populateDNSManager(mgr *dns.Manager, m *cluster.Cluster) error {
 
 	m.ForEachZone(func(z *cluster.Zone) bool {
 		z.ForEachMachine(func(p *cluster.Machine) bool {
-			err = mgr.AddHost(ctx, z.Name, p.ID, p.IsActive(), p.PublicAddresses...)
+			err = mgr.AddHost(ctx, z.Name, int(p.ID), p.IsActive(), p.PublicAddresses...)
 			return err != nil
 		})
 

cmd/jpictl/gateway.go

@@ -4,7 +4,6 @@ import (
 	"bytes"
 	"fmt"
 	"os"
-	"strconv"
 	"strings"
 
 	"github.com/spf13/cobra"
@@ -128,7 +127,7 @@ func gatewayListAll(zi cluster.ZoneIterator) error {
 			return false
 		}
 		for _, i := range ids {
-			sIDs = append(sIDs, strconv.Itoa(i))
+			sIDs = append(sIDs, i.String())
 		}
 		b.WriteString(strings.Join(sIDs, ", "))
 		b.WriteString("\n")

pkg/cluster/cluster_import.go

@@ -45,7 +45,7 @@ func (m *Cluster) initZones(opts *ScanOptions) error {
 
 func (m *Cluster) initZone(z *Zone, _ *ScanOptions) error {
 	var hasMissing bool
-	var lastMachineID int
+	var lastMachineID NodeID
 
 	z.zones = m
 	z.logger = m
@@ -58,7 +58,7 @@ func (m *Cluster) initZone(z *Zone, _ *ScanOptions) error {
 		case p.ID == 0:
 			hasMissing = true
 		case p.ID > lastMachineID:
-			lastMachineID = z.ID
+			lastMachineID = p.ID
 		}
 
 		return false

pkg/cluster/cluster_scan.go

@@ -114,7 +114,7 @@ func (m *Cluster) scanMachines(opts *ScanOptions) error {
 
 func (m *Cluster) scanZoneIDs(_ *ScanOptions) error {
 	var hasMissing bool
-	var lastZoneID int
+	var lastZoneID ZoneID
 
 	m.ForEachZone(func(z *Zone) bool {
 		switch {

pkg/cluster/env.go

@@ -35,8 +35,8 @@ func (m *Cluster) Env(export bool) (*Env, error) {
 }
 
 // Zones returns the list of Zone IDs
-func (m *Env) Zones() []int {
+func (m *Env) Zones() []ZoneID {
-	var zones []int
+	var zones []ZoneID
 
 	m.ForEachZone(func(z *Zone) bool {
 		zones = append(zones, z.ID)
@@ -70,8 +70,8 @@ func (m *Env) WriteTo(w io.Writer) (int64, error) {
 		m.writeEnvVar(&buf, m.cephFSID, "FSID")
 	}
 
-	m.writeEnvVarStrings(&buf, m.Regions(), "REGIONS")
+	m.writeEnvVar(&buf, genEnvStrings(m.Regions()), "REGIONS")
-	m.writeEnvVarInts(&buf, m.Zones(), "ZONES")
+	m.writeEnvVar(&buf, genEnvInts(m.Zones()), "ZONES")
 
 	m.ForEachZone(func(z *Zone) bool {
 		m.writeEnvZone(&buf, z)
@@ -92,7 +92,7 @@ func (m *Env) writeEnvZone(w io.Writer, z *Zone) {
 
 	// ZONE{zoneID}_GW
 	gateways, _ := z.GatewayIDs()
-	m.writeEnvVarInts(w, gateways, "ZONE%v_%s", zoneID, "GW")
+	m.writeEnvVar(w, genEnvInts(gateways), "ZONE%v_%s", zoneID, "GW")
 
 	// ZONE{zoneID}_REGION
 	m.writeEnvVar(w, genEnvZoneRegion(z), "ZONE%v_%s", zoneID, "REGION")
@@ -107,32 +107,6 @@ func (m *Env) writeEnvZone(w io.Writer, z *Zone) {
 	m.writeEnvVar(w, genEnvZoneCephMonIDs(monitors), "MON%v_%s", zoneID, "ID")
 }
 
-func (m *Env) writeEnvVarInts(w io.Writer, value []int, name string, args ...any) {
-	var buf bytes.Buffer
-
-	for _, v := range value {
-		if buf.Len() > 0 {
-			_, _ = fmt.Fprint(&buf, " ")
-		}
-		_, _ = fmt.Fprintf(&buf, "%v", v)
-	}
-
-	m.writeEnvVar(w, buf.String(), name, args...)
-}
-
-func (m *Env) writeEnvVarStrings(w io.Writer, value []string, name string, args ...any) {
-	var buf bytes.Buffer
-
-	for _, v := range value {
-		if buf.Len() > 0 {
-			_, _ = fmt.Fprint(&buf, " ")
-		}
-		_, _ = fmt.Fprintf(&buf, "%s", v)
-	}
-
-	m.writeEnvVar(w, buf.String(), name, args...)
-}
-
 func (m *Env) writeEnvVar(w io.Writer, value string, name string, args ...any) {
 	var prefix string
 
@@ -155,6 +129,23 @@ func (m *Env) writeEnvVar(w io.Writer, value string, name string, args ...any) {
 	}
 }
 
+func genEnvInts[T ~int | ~uint](values []T) string {
+	var buf bytes.Buffer
+
+	for _, v := range values {
+		if buf.Len() > 0 {
+			_, _ = buf.WriteRune(' ')
+		}
+		_, _ = buf.WriteString(fmt.Sprintf("%v", v))
+	}
+
+	return buf.String()
+}
+
+func genEnvStrings(values []string) string {
+	return strings.Join(values, " ")
+}
+
 func genEnvZoneNodes(z *Zone) string {
 	if n := z.Len(); n > 0 {
 		s := make([]string, 0, n)
@@ -164,7 +155,7 @@ func genEnvZoneNodes(z *Zone) string {
 			return false
 		})
 
-		return strings.Join(s, " ")
+		return genEnvStrings(s)
 	}
 	return ""
 }

pkg/cluster/machine.go

@@ -12,7 +12,7 @@ type Machine struct {
 	zone   *Zone
 	logger `json:"-" yaml:"-"`
 
-	ID   int
+	ID   NodeID
 	Name string `json:"-" yaml:"-"`
 
 	Inactive        bool         `json:"inactive,omitempty"     yaml:"inactive,omitempty"`
@@ -74,7 +74,7 @@ func (m *Machine) SetGateway(enabled bool) error {
 }
 
 // Zone indicates the [Zone] this machine belongs to
-func (m *Machine) Zone() int {
+func (m *Machine) Zone() ZoneID {
 	return m.zone.ID
 }
 

pkg/cluster/machine_rings.go

@@ -223,7 +223,7 @@ func (m *Machine) applyWireguardPeerConfig(ring int, pc wireguard.PeerConfig) er
 	}
 }
 
-func (m *Machine) applyZoneNodeID(zoneID, nodeID int) error {
+func (m *Machine) applyZoneNodeID(zoneID ZoneID, nodeID NodeID) error {
 	switch {
 	case zoneID == 0:
 		return fmt.Errorf("invalid %s", "zoneID")

pkg/cluster/machine_scan.go

@@ -65,7 +65,7 @@ func (m *Machine) setID() error {
 		return err
 	}
 
-	m.ID = int(id)
+	m.ID = NodeID(id)
 	return nil
 }
 

pkg/cluster/rings.go

@@ -81,8 +81,8 @@ func canMergeKeyPairs(p1, p2 wireguard.KeyPair) bool {
 type RingAddressEncoder struct {
 	ID     int
 	Port   uint16
-	Encode func(zoneID, nodeID int) (netip.Addr, bool)
+	Encode func(zoneID ZoneID, nodeID NodeID) (netip.Addr, bool)
-	Decode func(addr netip.Addr) (zoneID, nodeID int, ok bool)
+	Decode func(addr netip.Addr) (zoneID ZoneID, nodeID NodeID, ok bool)
 }
 
 var (
@@ -110,7 +110,7 @@ var (
 // ValidZoneID checks if the given zoneID is a valid 4 bit zone number.
 //
 // 0 is reserved, and only allowed when composing CIDRs.
-func ValidZoneID(zoneID int) bool {
+func ValidZoneID(zoneID ZoneID) bool {
 	switch {
 	case zoneID < 0 || zoneID > MaxZoneID:
 		return false
@@ -122,7 +122,7 @@ func ValidZoneID(zoneID int) bool {
 // ValidNodeID checks if the given nodeID is a valid 8 bit number.
 // nodeID is unique within a Zone.
 // 0 is reserved, and only allowed when composing CIDRs.
-func ValidNodeID(nodeID int) bool {
+func ValidNodeID(nodeID NodeID) bool {
 	switch {
 	case nodeID < 0 || nodeID > MaxNodeID:
 		return false
@@ -133,19 +133,19 @@ func ValidNodeID(nodeID int) bool {
 
 // ParseRingZeroAddress extracts zone and node ID from a wg0 [netip.Addr]
 // wg0 addresses are of the form `10.0.{{zoneID}}.{{nodeID}}`
-func ParseRingZeroAddress(addr netip.Addr) (zoneID int, nodeID int, ok bool) {
+func ParseRingZeroAddress(addr netip.Addr) (zoneID ZoneID, nodeID NodeID, ok bool) {
 	if addr.IsValid() {
 		a4 := addr.As4()
 
 		if a4[0] == 10 && a4[1] == 0 {
-			return int(a4[2]), int(a4[3]), true
+			return ZoneID(a4[2]), NodeID(a4[3]), true
 		}
 	}
 	return 0, 0, false
 }
 
 // RingZeroAddress returns a wg0 IP address
-func RingZeroAddress(zoneID, nodeID int) (netip.Addr, bool) {
+func RingZeroAddress(zoneID ZoneID, nodeID NodeID) (netip.Addr, bool) {
 	switch {
 	case !ValidZoneID(zoneID) || !ValidNodeID(nodeID):
 		return netip.Addr{}, false
@@ -157,13 +157,13 @@ func RingZeroAddress(zoneID, nodeID int) (netip.Addr, bool) {
 
 // ParseRingOneAddress extracts zone and node ID from a wg1 [netip.Addr]
 // wg1 addresses are of the form `10.{{zoneID << 4}}.{{nodeID}}`
-func ParseRingOneAddress(addr netip.Addr) (zoneID int, nodeID int, ok bool) {
+func ParseRingOneAddress(addr netip.Addr) (zoneID ZoneID, nodeID NodeID, ok bool) {
 	if addr.IsValid() {
 		a4 := addr.As4()
 
 		if a4[0] == 10 && a4[2] == 0 {
-			zoneID = int(a4[1] >> 4)
+			zoneID = ZoneID(a4[1] >> 4)
-			nodeID = int(a4[3])
+			nodeID = NodeID(a4[3])
 			return zoneID, nodeID, true
 		}
 	}
@@ -171,7 +171,7 @@ func ParseRingOneAddress(addr netip.Addr) (zoneID int, nodeID int, ok bool) {
 }
 
 // RingOneAddress returns a wg1 IP address
-func RingOneAddress(zoneID, nodeID int) (netip.Addr, bool) {
+func RingOneAddress(zoneID ZoneID, nodeID NodeID) (netip.Addr, bool) {
 	switch {
 	case !ValidZoneID(zoneID) || !ValidNodeID(nodeID):
 		return netip.Addr{}, false

pkg/cluster/types.go

@@ -0,0 +1,25 @@
+package cluster
+
+import "strconv"
+
+type (
+	// ZoneID is the identifier of a [Zone]
+	ZoneID int
+	// NodeID is the identifier of a [Machine]
+	NodeID int
+)
+
+func (z ZoneID) String() string {
+	return idString(int(z))
+}
+
+func (n NodeID) String() string {
+	return idString(int(n))
+}
+
+func idString(v int) string {
+	if v > 0 {
+		return strconv.Itoa(v)
+	}
+	return ""
+}

pkg/cluster/zones.go

@@ -19,7 +19,7 @@ type Zone struct {
 	zones  *Cluster
 	logger `json:"-" yaml:"-"`
 
-	ID      int
+	ID      ZoneID
 	Name    string
 	Regions []string `json:",omitempty" yaml:",omitempty"`
 
@@ -31,7 +31,7 @@ func (z *Zone) String() string {
 }
 
 // SetGateway configures a machine to be the zone's ring0 gateway
-func (z *Zone) SetGateway(gatewayID int, enabled bool) error {
+func (z *Zone) SetGateway(gatewayID NodeID, enabled bool) error {
 	var err error
 	var found bool
 
@@ -56,8 +56,8 @@ func (z *Zone) SetGateway(gatewayID int, enabled bool) error {
 }
 
 // GatewayIDs returns the list of IDs of machines that act as ring0 gateways
-func (z *Zone) GatewayIDs() ([]int, int) {
+func (z *Zone) GatewayIDs() ([]NodeID, int) {
-	var out []int
+	var out []NodeID
 	z.ForEachMachine(func(p *Machine) bool {
 		if p.IsGateway() {
 			out = append(out, p.ID)

pkg/rings/encode.go

@@ -1,145 +0,0 @@
-package rings
-
-import "net/netip"
-
-// RingZeroPrefix represents the backbone that connects gateways
-// of the different Ring 1 networks.
-//
-// The ring 0 network corresponds to what would be ring 2 for region_id 0.
-// 10.0.0.0-10.0.255.255
-func RingZeroPrefix(region RegionID, zone ZoneID) (cidr netip.Prefix, err error) {
-	switch {
-	case !region.Valid():
-		err = ErrOutOfRange(region, "region")
-	case !zone.Valid():
-		err = ErrOutOfRange(zone, "zone")
-	default:
-		addr := unsafeRingZeroAddress(region, zone, 0)
-		cidr = netip.PrefixFrom(addr, RingZeroBits)
-	}
-
-	return cidr, err
-}
-
-// RingZeroAddress returns a Ring 0 address for a particular node.
-//
-// A ring 0 address looks like 10.0.(region_id << 4 + zone_id).(node_id)/20
-func RingZeroAddress(region RegionID, zone ZoneID, node NodeID) (addr netip.Addr, err error) {
-	switch {
-	case !region.Valid():
-		err = ErrOutOfRange(region, "region")
-	case !zone.Valid():
-		err = ErrOutOfRange(zone, "zone")
-	case !node.ValidZero():
-		err = ErrOutOfRange(node, "node")
-	default:
-		addr = unsafeRingZeroAddress(region, zone, node)
-	}
-
-	return addr, err
-}
-
-// RingOnePrefix represents a (virtual) local network of a zone.
-//
-// Ring 1 is `10.(region_id).(zone_id << 4).(node_id)/20` network
-// grouped under what would be Ring 2 for region_id 0.
-// There are 12 bits worth of nodes but nodes under 255 are special
-// as they also get a slot on Ring 0.
-func RingOnePrefix(region RegionID, zone ZoneID) (cidr netip.Prefix, err error) {
-	switch {
-	case !region.Valid():
-		err = ErrOutOfRange(region, "region")
-	case !zone.Valid():
-		err = ErrOutOfRange(zone, "zone")
-	default:
-		addr := unsafeRingOneAddress(region, zone, 0)
-		cidr = netip.PrefixFrom(addr, RingOneBits)
-	}
-	return cidr, err
-}
-
-// RingOneAddress returns a Ring 1 address for a particular node.
-//
-// A ring 1 address is `10.(region_id).(zone_id << 4).(node_id)/20`
-// but the node_id can take up to 12 bits.
-func RingOneAddress(region RegionID, zone ZoneID, node NodeID) (addr netip.Addr, err error) {
-	switch {
-	case !region.Valid():
-		err = ErrOutOfRange(region, "region")
-	case !zone.Valid():
-		err = ErrOutOfRange(zone, "zone")
-	case !node.Valid():
-		err = ErrOutOfRange(node, "node")
-	default:
-		addr = unsafeRingOneAddress(region, zone, node)
-	}
-	return addr, err
-}
-
-// RingTwoPrefix represents the services of a cluster
-//
-// Ring 2 subnets are of the form `10.(region_id).0.0/20`,
-// using the address space that would belong to the ring 3
-// region_id 0.
-func RingTwoPrefix(region RegionID) (cidr netip.Prefix, err error) {
-	switch {
-	case !region.Valid():
-		err = ErrOutOfRange(region, "region")
-	default:
-		addr := unsafeRingTwoAddress(region, 0)
-		cidr = netip.PrefixFrom(addr, RingTwoBits)
-	}
-	return cidr, err
-}
-
-// RingThreePrefix returns the subnet corresponding to
-// the pods of a cluster.
-//
-// Ring 3 is a `10.(region_id << 4).0.0/12` network
-func RingThreePrefix(region RegionID) (subnet netip.Prefix, err error) {
-	switch {
-	case !region.Valid():
-		err = ErrOutOfRange(region, "region")
-	default:
-		addr := unsafeRingThreeAddress(region, 0)
-		subnet = netip.PrefixFrom(addr, RingThreeBits)
-	}
-	return subnet, err
-}
-
-func unsafeRingZeroAddress(region RegionID, zone ZoneID, node NodeID) netip.Addr {
-	r := uint(region)
-	z := uint(zone)
-	n := uint(node)
-
-	return AddrFrom4(10, 0, r<<4+z, n)
-}
-func unsafeRingOneAddress(region RegionID, zone ZoneID, node NodeID) netip.Addr {
-	r := uint(region)
-	z := uint(zone)
-	n := uint(node)
-
-	n1 := n >> 8
-	n0 := n >> 0
-
-	return AddrFrom4(10, r, z<<4+n1, n0)
-}
-
-func unsafeRingTwoAddress(region RegionID, n uint) netip.Addr {
-	r := uint(region)
-
-	n1 := n >> 8
-	n0 := n >> 0
-
-	return AddrFrom4(10, r, n1, n0)
-}
-
-func unsafeRingThreeAddress(region RegionID, n uint) netip.Addr {
-	r := uint(region)
-
-	n2 := n >> 16
-	n1 := n >> 8
-	n0 := n >> 0
-
-	return AddrFrom4(10, r<<4+n2, n1, n0)
-}

pkg/rings/encode_test.go

@@ -1,63 +0,0 @@
-package rings
-
-import (
-	"fmt"
-	"net/netip"
-	"testing"
-)
-
-func TestRingZeroAddress(t *testing.T) {
-	RZNTest(t, "RingZeroAddress", RingZeroAddress, []RZNTestCase{
-		{1, 1, 50, MustParseAddr("10.0.17.50")},
-		{1, 2, 50, MustParseAddr("10.0.18.50")},
-		{2, 3, 1, MustParseAddr("10.0.35.1")},
-		{2, 3, 300, netip.Addr{}},
-	})
-}
-
-func TestRingOneAddress(t *testing.T) {
-	RZNTest(t, "RingOneAddress", RingOneAddress, []RZNTestCase{
-		{1, 1, 50, MustParseAddr("10.1.16.50")},
-		{1, 2, 50, MustParseAddr("10.1.32.50")},
-		{2, 3, 300, MustParseAddr("10.2.49.44")},
-		{1, 20, 50, netip.Addr{}},
-	})
-}
-
-type RZNTestCase struct {
-	region RegionID
-	zone   ZoneID
-	node   NodeID
-	addr   netip.Addr
-}
-
-func RZNTest(t *testing.T,
-	fnName string, fn func(RegionID, ZoneID, NodeID) (netip.Addr, error),
-	cases []RZNTestCase) {
-	//
-	for i, tc := range cases {
-		s := fmt.Sprintf("%s(%v, %v, %v)", fnName,
-			tc.region,
-			tc.zone,
-			tc.node,
-		)
-
-		addr, err := fn(tc.region, tc.zone, tc.node)
-
-		switch {
-		case !tc.addr.IsValid():
-			// expect error
-			if err != nil {
-				t.Logf("[%v/%v]: %s → %s", i, len(cases), s, err)
-			} else {
-				t.Errorf("ERROR: [%v/%v]: %s → %s (expected %s)", i, len(cases), s, addr, "error")
-			}
-		case err != nil:
-			t.Errorf("ERROR: [%v/%v]: %s → %s (expected %s)", i, len(cases), s, err, tc.addr)
-		case addr.Compare(tc.addr) != 0:
-			t.Errorf("ERROR: [%v/%v]: %s → %s (expected %s)", i, len(cases), s, addr, tc.addr)
-		default:
-			t.Logf("[%v/%v]: %s → %s", i, len(cases), s, addr)
-		}
-	}
-}

pkg/rings/rings.go

@@ -1,60 +1,3 @@
 // Package rings provides logic to work with the four rings
 // of a cluster
 package rings
-
-import (
-	"syscall"
-
-	"darvaza.org/core"
-)
-
-const (
-	// RegionMax indicates the highest number that can be used for a [RegionID].
-	RegionMax = (1 << 4) - 1
-	// ZoneMax indicates the highest number that can be used for a [ZoneID].
-	ZoneMax = (1 << 4) - 1
-	// NodeMax indicates the highest number that can be used for a [NodeID].
-	NodeMax = (1 << 12) - 1
-	// NodeZeroMax indicates the highest number that can be used for a [NodeID]
-	// when its a gateway connected to Ring 0 (backbone).
-	NodeZeroMax = (1 << 8) - 1
-
-	// RingZeroBits indicates the size of the prefix on the ring 0 (backbone) network.
-	RingZeroBits = 16
-	// RingOneBits indicates the size of the prefix on the ring 1 (lan) network.
-	RingOneBits = 20
-	// RingTwoBits indicates the size of the prefix on the ring 2 (services) network
-	// of all kubernetes clusters.
-	RingTwoBits = 20
-	// RingThreeBits indicates the size of the prefix on the ring 3 (pods) network
-	// of the kubernetes cluster of a region.
-	RingThreeBits = 12
-)
-
-// RegionID is the identifier of a region, valid between 1 and [RegionMax].
-type RegionID int
-
-// Valid tells a [RegionID] is within the valid range.
-func (n RegionID) Valid() bool { return n > 0 && n <= RegionMax }
-
-// ZoneID is the identifier of a zone within a region, valid between 1 and [ZoneMax].
-type ZoneID int
-
-// Valid tells a [ZoneID] is within the valid range.
-func (n ZoneID) Valid() bool { return n > 0 && n <= ZoneMax }
-
-// NodeID is the identifier of a machine within a zone of a region, valid between
-// 1 and [NodeMax], but between 1 and [NodeZeroMax] if it will be a zone gateway.
-type NodeID int
-
-// Valid tells a [NodeID] is within the valid range.
-func (n NodeID) Valid() bool { return n > 0 && n <= NodeMax }
-
-// ValidZero tells a [NodeID] is within the valid range for a gateway.
-func (n NodeID) ValidZero() bool { return n > 0 && n <= NodeZeroMax }
-
-// ErrOutOfRange is an error indicating the value of a field
-// is out of range.
-func ErrOutOfRange[T ~int | ~uint32](value T, field string) error {
-	return core.Wrap(syscall.EINVAL, "%s out of range (%v)", field, value)
-}