rings: DecodeRingZeroAddress() and DecodeRingOneAddress()

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

Makefile

@@ -15,8 +15,7 @@ TMPDIR ?= .tmp
 REVIVE ?= $(GOBIN)/revive
 REVIVE_CONF ?= $(TOOLSDIR)/revive.toml
 REVIVE_RUN_ARGS ?= -config $(REVIVE_CONF) -formatter friendly
-REVIVE_VERSION ?= v1.3.7
+REVIVE_INSTALL_URL ?= github.com/mgechev/revive@master
-REVIVE_INSTALL_URL ?= github.com/mgechev/revive@$(REVIVE_VERSION)
 
 GO_INSTALL_URLS = \
 	$(REVIVE_INSTALL_URL) \

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, int(p.ID), p.IsActive(), p.PublicAddresses...)
+			err = mgr.AddHost(ctx, z.Name, p.ID, p.IsActive(), p.PublicAddresses...)
 			return err != nil
 		})
 

cmd/jpictl/gateway.go

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

pkg/cluster/cluster_import.go

@@ -6,18 +6,16 @@ import (
 	"os"
 
 	"gopkg.in/yaml.v3"
-
-	"git.jpi.io/amery/jpictl/pkg/rings"
 )
 
 func (m *Cluster) init(opts *ScanOptions) error {
 	for _, fn := range []func(*ScanOptions) error{
 		m.initZones,
-		m.initRegions,
 		m.scanZoneIDs,
 		m.scanSort,
 		m.scanGateways,
 		m.initCephMonitors,
+		m.initRegions,
 	} {
 		if err := fn(opts); err != nil {
 			return err
@@ -47,7 +45,7 @@ func (m *Cluster) initZones(opts *ScanOptions) error {
 
 func (m *Cluster) initZone(z *Zone, _ *ScanOptions) error {
 	var hasMissing bool
-	var lastMachineID rings.NodeID
+	var lastMachineID int
 
 	z.zones = m
 	z.logger = m
@@ -60,7 +58,7 @@ func (m *Cluster) initZone(z *Zone, _ *ScanOptions) error {
 		case p.ID == 0:
 			hasMissing = true
 		case p.ID > lastMachineID:
-			lastMachineID = p.ID
+			lastMachineID = z.ID
 		}
 
 		return false

pkg/cluster/cluster_scan.go

@@ -7,8 +7,6 @@ import (
 	"strings"
 
 	"darvaza.org/core"
-
-	"git.jpi.io/amery/jpictl/pkg/rings"
 )
 
 const (
@@ -25,9 +23,9 @@ func (m *Cluster) scan(opts *ScanOptions) error {
 	for _, fn := range []func(*ScanOptions) error{
 		m.scanDirectory,
 		m.scanMachines,
-		m.initRegions,
 		m.scanZoneIDs,
 		m.scanSort,
+		m.initRegions,
 		m.scanGateways,
 		m.scanCephMonitors,
 	} {
@@ -116,7 +114,7 @@ func (m *Cluster) scanMachines(opts *ScanOptions) error {
 
 func (m *Cluster) scanZoneIDs(_ *ScanOptions) error {
 	var hasMissing bool
-	var lastZoneID rings.ZoneID
+	var lastZoneID int
 
 	m.ForEachZone(func(z *Zone) bool {
 		switch {

pkg/cluster/env.go

@@ -6,8 +6,6 @@ import (
 	"io"
 	"sort"
 	"strings"
-
-	"git.jpi.io/amery/jpictl/pkg/rings"
 )
 
 // Env is a shell environment factory for this cluster
@@ -37,8 +35,8 @@ func (m *Cluster) Env(export bool) (*Env, error) {
 }
 
 // Zones returns the list of Zone IDs
-func (m *Env) Zones() []rings.ZoneID {
+func (m *Env) Zones() []int {
-	var zones []rings.ZoneID
+	var zones []int
 
 	m.ForEachZone(func(z *Zone) bool {
 		zones = append(zones, z.ID)
@@ -53,7 +51,7 @@ func (m *Env) Regions() []string {
 	var regions []string
 
 	m.ForEachRegion(func(r *Region) bool {
-		if r.IsPrimary() {
+		if r.Cluster != nil {
 			regions = append(regions, r.Name)
 		}
 
@@ -72,8 +70,8 @@ func (m *Env) WriteTo(w io.Writer) (int64, error) {
 		m.writeEnvVar(&buf, m.cephFSID, "FSID")
 	}
 
-	m.writeEnvVar(&buf, genEnvStrings(m.Regions()), "REGIONS")
+	m.writeEnvVarStrings(&buf, m.Regions(), "REGIONS")
-	m.writeEnvVar(&buf, genEnvInts(m.Zones()), "ZONES")
+	m.writeEnvVarInts(&buf, m.Zones(), "ZONES")
 
 	m.ForEachZone(func(z *Zone) bool {
 		m.writeEnvZone(&buf, z)
@@ -94,7 +92,7 @@ func (m *Env) writeEnvZone(w io.Writer, z *Zone) {
 
 	// ZONE{zoneID}_GW
 	gateways, _ := z.GatewayIDs()
-	m.writeEnvVar(w, genEnvInts(gateways), "ZONE%v_%s", zoneID, "GW")
+	m.writeEnvVarInts(w, gateways, "ZONE%v_%s", zoneID, "GW")
 
 	// ZONE{zoneID}_REGION
 	m.writeEnvVar(w, genEnvZoneRegion(z), "ZONE%v_%s", zoneID, "REGION")
@@ -109,6 +107,32 @@ 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
 
@@ -131,23 +155,6 @@ 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)
@@ -157,16 +164,24 @@ func genEnvZoneNodes(z *Zone) string {
 			return false
 		})
 
-		return genEnvStrings(s)
+		return strings.Join(s, " ")
 	}
 	return ""
 }
 
 func genEnvZoneRegion(z *Zone) string {
-	if z != nil && z.region != nil {
+	var region string
-		return z.region.Name
+
-	}
+	z.ForEachRegion(func(r *Region) bool {
-	return ""
+		if r.Cluster != nil {
+			region = r.Name
+			return true
+		}
+
+		return false
+	})
+
+	return region
 }
 
 func genEnvZoneCephMonNames(m Machines) string {

pkg/cluster/machine.go

@@ -3,8 +3,6 @@ package cluster
 import (
 	"net/netip"
 	"strings"
-
-	"git.jpi.io/amery/jpictl/pkg/rings"
 )
 
 // revive:disable:line-length-limit
@@ -14,7 +12,7 @@ type Machine struct {
 	zone   *Zone
 	logger `json:"-" yaml:"-"`
 
-	ID   rings.NodeID
+	ID   int
 	Name string `json:"-" yaml:"-"`
 
 	Inactive        bool         `json:"inactive,omitempty"     yaml:"inactive,omitempty"`
@@ -76,7 +74,7 @@ func (m *Machine) SetGateway(enabled bool) error {
 }
 
 // Zone indicates the [Zone] this machine belongs to
-func (m *Machine) Zone() rings.ZoneID {
+func (m *Machine) Zone() int {
 	return m.zone.ID
 }
 

pkg/cluster/machine_rings.go

@@ -8,7 +8,6 @@ import (
 
 	"darvaza.org/core"
 
-	"git.jpi.io/amery/jpictl/pkg/rings"
 	"git.jpi.io/amery/jpictl/pkg/wireguard"
 )
 
@@ -224,7 +223,7 @@ func (m *Machine) applyWireguardPeerConfig(ring int, pc wireguard.PeerConfig) er
 	}
 }
 
-func (m *Machine) applyZoneNodeID(zoneID rings.ZoneID, nodeID rings.NodeID) error {
+func (m *Machine) applyZoneNodeID(zoneID, nodeID int) error {
 	switch {
 	case zoneID == 0:
 		return fmt.Errorf("invalid %s", "zoneID")

pkg/cluster/machine_scan.go

@@ -9,7 +9,6 @@ import (
 	"time"
 
 	"darvaza.org/core"
-	"git.jpi.io/amery/jpictl/pkg/rings"
 )
 
 // LookupNetIP uses the DNS Resolver to get the public addresses associated
@@ -66,7 +65,7 @@ func (m *Machine) setID() error {
 		return err
 	}
 
-	m.ID = rings.NodeID(id)
+	m.ID = int(id)
 	return nil
 }
 

pkg/cluster/regions.go

@@ -3,8 +3,6 @@ package cluster
 import (
 	"bytes"
 	"path/filepath"
-
-	"git.jpi.io/amery/jpictl/pkg/rings"
 )
 
 var (
@@ -26,15 +24,8 @@ type Region struct {
 	zones []*Zone
 
 	Name    string
-	ID      rings.RegionID `json:",omitempty" yaml:",omitempty"`
+	Cluster *string  `json:",omitempty" yaml:",omitempty"`
-	Cluster *string        `json:",omitempty" yaml:",omitempty"`
+	Regions []string `json:",omitempty" yaml:",omitempty"`
-	Regions []string       `json:",omitempty" yaml:",omitempty"`
-}
-
-// IsPrimary indicates the region is primary and corresponds
-// to a kubernetes cluster.
-func (r *Region) IsPrimary() bool {
-	return r != nil && r.Cluster != nil
 }
 
 // ForEachRegion calls a function for each Region of the cluster
@@ -101,8 +92,6 @@ func (m *Cluster) initRegions(_ *ScanOptions) error {
 	}
 
 	m.sortRegions()
-	m.scanRegionID()
-	m.computeZonesRegion()
 	return nil
 }
 
@@ -221,92 +210,6 @@ func (m *Cluster) finishRegion(r *Region) {
 	r.Regions = sub
 }
 
-// revive:disable:cognitive-complexity
-func (m *Cluster) scanRegionID() {
-	// revive:enable:cognitive-complexity
-	var max rings.RegionID
-	var missing bool
-
-	// check IDs
-	ids := make(map[rings.RegionID]bool)
-	fn := func(r *Region) bool {
-		var term bool
-
-		switch {
-		case !r.IsPrimary():
-			// secondary, no ID.
-			r.ID = 0
-		case !r.ID.Valid():
-			// primary without ID
-			missing = true
-		case ids[r.ID]:
-			// duplicate
-			m.error(nil).WithField("region", r.Name).Print("duplicate ID")
-			missing = true
-			r.ID = 0
-		default:
-			ids[r.ID] = true
-
-			if r.ID > max {
-				max = r.ID
-			}
-		}
-
-		return term
-	}
-	m.ForEachRegion(fn)
-
-	if missing {
-		// assign missing IDs
-		fn := func(r *Region) bool {
-			var term bool
-
-			switch {
-			case !r.IsPrimary():
-				// ignore secondary
-			case r.ID.Valid():
-				// already has an ID
-			default:
-				r.ID = max + 1
-				max = r.ID
-			}
-
-			return term
-		}
-
-		m.ForEachRegion(fn)
-	}
-}
-
-func (m *Cluster) computeZonesRegion() {
-	fn := func(r *Region, z *Zone) {
-		if z.region != nil {
-			m.error(nil).
-				WithField("zone", z.Name).
-				WithField("region", []string{
-					z.region.Name,
-					r.Name,
-				}).
-				Print("zone in two regions")
-		} else {
-			z.region = r
-		}
-	}
-
-	m.ForEachRegion(func(r *Region) bool {
-		var term bool
-
-		if r.IsPrimary() {
-			r.ForEachZone(func(z *Zone) bool {
-				fn(r, z)
-				return term
-			})
-		}
-
-		return term
-	})
-}
-
 func (m *Cluster) getRegion(name string) (*Region, bool) {
 	for i := range m.Regions {
 		r := &m.Regions[i]

pkg/cluster/rings.go

@@ -5,11 +5,14 @@ import (
 	"io/fs"
 	"net/netip"
 
-	"git.jpi.io/amery/jpictl/pkg/rings"
 	"git.jpi.io/amery/jpictl/pkg/wireguard"
 )
 
 const (
+	// MaxZoneID indicates the highest ID allowed for a Zone
+	MaxZoneID = 0xf
+	// MaxNodeID indicates the highest Machine ID allowed within a Zone
+	MaxNodeID = 0xff - 1
 	// RingsCount indicates how many wireguard rings we have
 	RingsCount = 2
 	// RingZeroPort is the port wireguard uses for ring0
@@ -78,8 +81,8 @@ func canMergeKeyPairs(p1, p2 wireguard.KeyPair) bool {
 type RingAddressEncoder struct {
 	ID     int
 	Port   uint16
-	Encode func(zoneID rings.ZoneID, nodeID rings.NodeID) (netip.Addr, bool)
+	Encode func(zoneID, nodeID int) (netip.Addr, bool)
-	Decode func(addr netip.Addr) (zoneID rings.ZoneID, nodeID rings.NodeID, ok bool)
+	Decode func(addr netip.Addr) (zoneID, nodeID int, ok bool)
 }
 
 var (
@@ -107,34 +110,42 @@ 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 rings.ZoneID) bool {
+func ValidZoneID(zoneID int) bool {
-	return zoneID == 0 || zoneID.Valid()
+	switch {
+	case zoneID < 0 || zoneID > MaxZoneID:
+		return false
+	default:
+		return true
+	}
 }
 
 // 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 rings.NodeID) bool {
+func ValidNodeID(nodeID int) bool {
-	return nodeID == 0 || nodeID.Valid()
+	switch {
+	case nodeID < 0 || nodeID > MaxNodeID:
+		return false
+	default:
+		return true
+	}
 }
 
 // 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 rings.ZoneID, nodeID rings.NodeID, ok bool) {
+func ParseRingZeroAddress(addr netip.Addr) (zoneID int, nodeID int, ok bool) {
 	if addr.IsValid() {
 		a4 := addr.As4()
 
 		if a4[0] == 10 && a4[1] == 0 {
-			zoneID = rings.ZoneID(a4[2])
+			return int(a4[2]), int(a4[3]), true
-			nodeID = rings.NodeID(a4[3])
-			return zoneID, nodeID, true
 		}
 	}
 	return 0, 0, false
 }
 
 // RingZeroAddress returns a wg0 IP address
-func RingZeroAddress(zoneID rings.ZoneID, nodeID rings.NodeID) (netip.Addr, bool) {
+func RingZeroAddress(zoneID, nodeID int) (netip.Addr, bool) {
 	switch {
 	case !ValidZoneID(zoneID) || !ValidNodeID(nodeID):
 		return netip.Addr{}, false
@@ -146,13 +157,13 @@ func RingZeroAddress(zoneID rings.ZoneID, nodeID rings.NodeID) (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 rings.ZoneID, nodeID rings.NodeID, ok bool) {
+func ParseRingOneAddress(addr netip.Addr) (zoneID int, nodeID int, ok bool) {
 	if addr.IsValid() {
 		a4 := addr.As4()
 
 		if a4[0] == 10 && a4[2] == 0 {
-			zoneID = rings.ZoneID(a4[1] >> 4)
+			zoneID = int(a4[1] >> 4)
-			nodeID = rings.NodeID(a4[3])
+			nodeID = int(a4[3])
 			return zoneID, nodeID, true
 		}
 	}
@@ -160,7 +171,7 @@ func ParseRingOneAddress(addr netip.Addr) (zoneID rings.ZoneID, nodeID rings.Nod
 }
 
 // RingOneAddress returns a wg1 IP address
-func RingOneAddress(zoneID rings.ZoneID, nodeID rings.NodeID) (netip.Addr, bool) {
+func RingOneAddress(zoneID, nodeID int) (netip.Addr, bool) {
 	switch {
 	case !ValidZoneID(zoneID) || !ValidNodeID(nodeID):
 		return netip.Addr{}, false

pkg/cluster/zones.go

@@ -2,8 +2,6 @@ package cluster
 
 import (
 	"io/fs"
-
-	"git.jpi.io/amery/jpictl/pkg/rings"
 )
 
 var (
@@ -19,10 +17,9 @@ type ZoneIterator interface {
 // affinity.
 type Zone struct {
 	zones  *Cluster
-	region *Region
 	logger `json:"-" yaml:"-"`
 
-	ID      rings.ZoneID
+	ID      int
 	Name    string
 	Regions []string `json:",omitempty" yaml:",omitempty"`
 
@@ -34,7 +31,7 @@ func (z *Zone) String() string {
 }
 
 // SetGateway configures a machine to be the zone's ring0 gateway
-func (z *Zone) SetGateway(gatewayID rings.NodeID, enabled bool) error {
+func (z *Zone) SetGateway(gatewayID int, enabled bool) error {
 	var err error
 	var found bool
 
@@ -59,8 +56,8 @@ func (z *Zone) SetGateway(gatewayID rings.NodeID, enabled bool) error {
 }
 
 // GatewayIDs returns the list of IDs of machines that act as ring0 gateways
-func (z *Zone) GatewayIDs() ([]rings.NodeID, int) {
+func (z *Zone) GatewayIDs() ([]int, int) {
-	var out []rings.NodeID
+	var out []int
 	z.ForEachMachine(func(p *Machine) bool {
 		if p.IsGateway() {
 			out = append(out, p.ID)

pkg/rings/decode.go

@@ -0,0 +1,62 @@
+package rings
+
+import (
+	"net/netip"
+
+	"darvaza.org/core"
+)
+
+// DecodeAddress ... TODO
+//
+// revive:disable:function-result-limit
+func DecodeAddress(addr netip.Addr) (Ring, RegionID, ZoneID, uint) {
+	// revive:enable:function-result-limit
+	if addr.IsValid() {
+		if addr.Is4In6() {
+			addr = addr.Unmap()
+		}
+
+		if addr.Is4() {
+			a4 := addr.As4()
+			return unsafeDecodeAddress(a4[0], a4[1], a4[2], a4[3])
+		}
+	}
+
+	return InvalidRing, 0, 0, 0
+}
+
+// revive:disable:function-result-limit
+func unsafeDecodeAddress(a, b, c, d byte) (Ring, RegionID, ZoneID, uint) {
+	// revive:enable:function-result-limit
+	switch {
+	case a != 10:
+		return InvalidRing, 0, 0, 0
+	case b&0xf0 != 0:
+		k := RingThree
+		r := RegionID(b >> 4)
+
+		n2 := uint(b & 0x0f)
+		n1 := uint(c)
+		n0 := uint(d)
+		n := n0 + n1<<8 + n2<<16
+
+		return k, r, 0, n
+	case b&0x0f != 0:
+		r := RegionID(b)
+		z := ZoneID(c >> 4)
+		k := core.IIf(z == 0, RingTwo, RingOne)
+
+		n1 := uint(c & 0x0f)
+		n0 := uint(d)
+		n := n0 + n1<<8
+
+		return k, r, z, n
+	default: // b == 0
+		k := RingZero
+		r := RegionID(c >> 4)
+		z := ZoneID(c & 0xf)
+		n := uint(d)
+
+		return k, r, z, n
+	}
+}

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/rings.go

@@ -3,23 +3,36 @@
 package rings
 
 import (
-	"fmt"
+	"net/netip"
-	"strconv"
 	"syscall"
 
 	"darvaza.org/core"
 )
 
+// Ring ... TODO
+type Ring int
+
 const (
+	// InvalidRing ... TODO
+	InvalidRing Ring = iota - 1
+	// RingZero ... TODO
+	RingZero
+	// RingOne ... TODO
+	RingOne
+	// RingTwo ... TODO
+	RingTwo
+	// RingThree ... TODO
+	RingThree
+
 	// 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) - 2
+	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) - 2
+	NodeZeroMax = (1 << 8) - 1
 
 	// RingZeroBits indicates the size of the prefix on the ring 0 (backbone) network.
 	RingZeroBits = 16
@@ -39,20 +52,12 @@ type RegionID int
 // Valid tells a [RegionID] is within the valid range.
 func (n RegionID) Valid() bool { return n > 0 && n <= RegionMax }
 
-func (n RegionID) String() string {
-	return idString(n)
-}
-
 // 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 }
 
-func (n ZoneID) String() string {
-	return idString(n)
-}
-
 // 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
@@ -63,28 +68,179 @@ 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 }
 
-func (n NodeID) String() string {
-	return idString(n)
-}
-
 // 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)
 }
 
-type intID interface {
+// RingZeroPrefix represents the backbone that connects gateways
-	~int
+// of the different Ring 1 networks.
-	Valid() bool
+//
+// 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
 }
 
-func idString[T intID](p T) string {
+// 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 p == 0:
+	case !region.Valid():
-		return "unspecified"
+		err = ErrOutOfRange(region, "region")
-	case p.Valid():
+	case !zone.Valid():
-		return strconv.Itoa(int(p))
+		err = ErrOutOfRange(zone, "zone")
+	case !node.ValidZero():
+		err = ErrOutOfRange(node, "node")
 	default:
-		return fmt.Sprintf("invalid (%v)", int(p))
+		addr = unsafeRingZeroAddress(region, zone, node)
 	}
+
+	return addr, err
+}
+
+// DecodeRingZeroAddress attempts to extract region, zone and node identifiers
+// from a given ring 0 address.
+//
+// revive:disable:function-result-limit
+func DecodeRingZeroAddress(addr netip.Addr) (RegionID, ZoneID, NodeID, bool) {
+	// revive:enable:function-result-limit
+	k, r, z, n := DecodeAddress(addr)
+	if k == RingZero {
+		return r, z, NodeID(n), true
+	}
+
+	return 0, 0, 0, false
+}
+
+// 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
+}
+
+// DecodeRingOneAddress attempts to extract region, zone and node identifiers
+// from a given ring 1 address.
+//
+// revive:disable:function-result-limit
+func DecodeRingOneAddress(addr netip.Addr) (RegionID, ZoneID, NodeID, bool) {
+	// revive:enable:function-result-limit
+	k, r, z, n := DecodeAddress(addr)
+	if k == RingOne {
+		return r, z, NodeID(n), r != 0 && z != 0
+	}
+
+	return 0, 0, 0, false
+}
+
+// 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/rings_test.go

@@ -61,3 +61,49 @@ func RZNTest(t *testing.T,
 		}
 	}
 }
+
+func TestDecodeRingZeroAddress(t *testing.T) {
+	RZNDecodeTest(t, "DecodeRingZeroAddress", DecodeRingZeroAddress, []RZNDecodeTestCase{
+		{1, 1, 50, MustParseAddr("10.0.17.50"), true},
+		{1, 2, 50, MustParseAddr("10.0.18.50"), true},
+		{2, 3, 1, MustParseAddr("10.0.35.1"), true},
+	})
+}
+
+func TesDecodetRingOneAddress(t *testing.T) {
+	RZNDecodeTest(t, "DecodeRingOneAddress", DecodeRingOneAddress, []RZNDecodeTestCase{
+		{1, 1, 50, MustParseAddr("10.1.16.50"), true},
+		{1, 2, 50, MustParseAddr("10.1.32.50"), true},
+		{2, 3, 300, MustParseAddr("10.2.49.44"), true},
+	})
+}
+
+type RZNDecodeTestCase struct {
+	region RegionID
+	zone   ZoneID
+	node   NodeID
+	addr   netip.Addr
+	ok     bool
+}
+
+func RZNDecodeTest(t *testing.T,
+	fnName string, fn func(netip.Addr) (RegionID, ZoneID, NodeID, bool),
+	cases []RZNDecodeTestCase) {
+	//
+	for i, tc := range cases {
+		s := fmt.Sprintf("%s(%q)", fnName, tc.addr)
+
+		r, z, n, ok := fn(tc.addr)
+
+		switch {
+		case ok != tc.ok, r != tc.region, z != tc.zone, n != tc.node:
+			t.Errorf("ERROR: [%v/%v]: %s → %v %v %v %v (expected %v %v %v %v)",
+				i, len(cases), s,
+				r, z, n, ok,
+				tc.region, tc.zone, tc.node, tc.ok)
+		default:
+			t.Logf("[%v/%v]: %s → %v %v %v %v", i, len(cases), s,
+				r, z, n, ok)
+		}
+	}
+}