diff --git a/pkg/rings/encode.go b/pkg/rings/encode.go new file mode 100644 index 0000000..7a083eb --- /dev/null +++ b/pkg/rings/encode.go @@ -0,0 +1,145 @@ +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) +} diff --git a/pkg/rings/encode_test.go b/pkg/rings/encode_test.go new file mode 100644 index 0000000..0b404fc --- /dev/null +++ b/pkg/rings/encode_test.go @@ -0,0 +1,63 @@ +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) + } + } +} diff --git a/pkg/rings/rings.go b/pkg/rings/rings.go index 01f2ce7..646014d 100644 --- a/pkg/rings/rings.go +++ b/pkg/rings/rings.go @@ -1,3 +1,60 @@ // 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) +}