portalloc

Documentation

Overview

Package portalloc provides deterministic internal-port allocation for per-Gateway edge listeners (proposal 021 Phase 2). Each (Gateway namespace, Gateway name, listener section name) triple gets a stable internal port in the range [BasePort, BasePort+RangeSize) via FNV-1a hashing, so:

• The same triple always maps to the same port across restarts.
• Different triples are overwhelmingly likely to map to different ports (birthday-paradox collision probability is ~RangeSize² / 2 ≈ negligible at single-digit Gateway counts).
• No external state or etcd/CRD storage is required.

For production workloads with O(10) Gateways × O(4) listeners the expected collision rate is < 0.04 % per allocation, which is acceptable. Collision detection (PortSet.Assign) detects conflicts and bumps by +1 up to MaxProbes times, guaranteeing uniqueness within a single reconcile batch.

Index

• Constants
• func AssignAll(keys []Key) (map[Key]uint32, error)
• func Hash(k Key) uint32
• type Key
• type PortSet
  • func NewPortSet() *PortSet
  • func (ps *PortSet) Assign(k Key) (uint32, error)

Constants

const (
	// BasePort is the first internal port in the allocation range.
	BasePort = uint32(18100)
	// RangeSize is the number of ports in the allocation range.
	RangeSize = uint32(900) // [18100, 18999]
	// MaxProbes is the maximum number of linear-probe steps on hash collision.
	MaxProbes = 20
)

Functions

func AssignAll

func AssignAll(keys []Key) (map[Key]uint32, error)

AssignAll allocates internal ports for all keys, returning a map from Key to port and any allocation error. On error the returned map is partial.

func Hash

func Hash(k Key) uint32

Hash returns the deterministic hash-derived port for key. It does NOT check for collisions — use PortSet.Assign when building a batch.

Types

type Key

type Key struct {
	Namespace    string
	GatewayName  string
	ListenerName string
}

Key uniquely identifies a (Gateway, listener) pair for port allocation.

type PortSet

type PortSet struct {
	// contains filtered or unexported fields
}

PortSet tracks which ports have been assigned in the current batch and provides collision-safe assignment via linear probing.

func NewPortSet

func NewPortSet() *PortSet

NewPortSet returns an empty PortSet.

func (*PortSet) Assign

func (ps *PortSet) Assign(k Key) (uint32, error)

Assign returns the internal port for key, probing up to MaxProbes times to avoid collisions with already-assigned keys. Returns an error only when every probe slot is taken by a different key (extremely unlikely in practice).