Documentation
¶
Overview ¶
Package ports allocates the host ports a bay publishes on.
Two properties matter, and only one of them is negotiable.
Determinism is desirable: the same branch should land on the same ports across daemon restarts, because humans bookmark URLs and agents cache them. A hash of the branch name gives that for free.
Correctness is not negotiable, and a hash alone cannot provide it. Hashing into N buckets collides at the rate the birthday problem predicts -- with 90 buckets and five bays that is better than a one-in-ten chance, and a collision is total, because both bays would publish every service on identical ports. Nor does a hash know which ports something else on the machine has already taken.
So the hash is the first guess, not the answer. The allocation it suggests is confirmed against persisted state and against the host, probed forward when either objects, and then recorded. The common case stays deterministic; the uncommon case stays correct.
Index ¶
Constants ¶
const ( RangeStart = 40000 RangeEnd = 49000 BlockSize = 10 )
The range devbay allocates from. Deliberately high and contiguous: the alternative of offsetting each service from its own base port lets two services in different bays land on the same number whenever their base ports differ by less than the offset range.
Variables ¶
var ErrExhausted = errors.New("ports: no free block in the allocation range")
ErrExhausted is returned when every block in the range is taken.
Functions ¶
func PreferredBase ¶
PreferredBase is the block a bay gets when nothing is in the way.
Exported because it is part of the contract, not an implementation detail: a bay's URL is predictable precisely because this function is. Tests use it to arrange the collisions that prove probing works.
Types ¶
type Allocator ¶
type Allocator struct {
// contains filtered or unexported fields
}
Allocator hands out and remembers blocks.
func (*Allocator) Allocate ¶
Allocate reserves a block large enough for n ports.
It is idempotent: calling it again for the same bay returns the same block, which is what makes a URL survive a daemon restart. An existing block that is too small is replaced, because a manifest that grew a service should not silently reuse a block it has outgrown.
type Block ¶
Block is a contiguous run of host ports reserved for one bay.
func (Block) Assign ¶
Assign maps a sorted list of port keys onto a bay's block.
The keys are sorted by the caller so the mapping depends only on which ports a manifest declares, not on map iteration order -- otherwise the same bay would publish a service on a different port each boot, and determinism would be a claim rather than a property.
Source Files