jpictl/pkg/rings/rings.go

// Package rings provides logic to work with the four rings
// of a cluster
package rings

import (
	"net/netip"
	"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)
}

// 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)
}