rings: RingOnePrefix()/RingOneAddress()

Ring one designates the (virtual) local network of a zone
within a region.

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

pkg/rings/rings.go

@@ -3,6 +3,7 @@
 package rings
 
 import (
+	"net/netip"
 	"syscall"
 
 	"darvaza.org/core"
@@ -18,6 +19,9 @@ const (
 	// 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
+
+	// RingOneBits indicates the size of the prefix on the ring 1 (lan) network.
+	RingOneBits = 20
 )
 
 // RegionID is the identifier of a region, valid between 1 and [RegionMax].
@@ -47,3 +51,51 @@ func (n NodeID) ValidZero() bool { return n > 0 && n <= NodeZeroMax }
 func ErrOutOfRange[T ~int | ~uint32](value T, field string) error {
 	return core.Wrap(syscall.EINVAL, "%s out of range (%v)", field, value)
 }
+
+// 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
+}
+
+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)
+}

pkg/rings/rings_test.go

@@ -0,0 +1,54 @@
+package rings
+
+import (
+	"fmt"
+	"net/netip"
+	"testing"
+)
+
+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)
+		}
+	}
+}