Hazmi35/turnfleet / .agents/skills/add-addressing-mode
add-addressing-mode
VerifiedAdd a new addressing mode to Turnfleet - implement Planner and Renderer, golden tests, an e2e case and an ADR. Use when a new way of assigning relay addresses or port ranges is needed.
Adding an addressing mode
An addressing mode answers two questions: which node does a relay run on, and
which public relay identity (address, port range) does it own. Anything that
does not change capacity accounting is not a new mode.
- Extend the enum.
api/v1alpha1/AddressingModeplus the+kubebuilder:validation:Enummarker. Adding a value breaks everyswitchover the type by design, so fix them all (exhaustiveenforces it). - Implement
internal/relay.Plannerfor the mode:- Deterministic ordering (sort nodes and addresses) so identities are stable across restarts and controller failover.
- A candidate set of relay identities:
(address, disjoint port range). Prove disjointness, do not assume it. - A relay moves only when its node or its address disappears. Anything else is a capacity bug the e2e suite will not catch.
- Capacity honesty: if the mode shares one IP between relays, the plan
must say so (
portsTotalsums to one IP's port space, not more).
- Implement
internal/relay.Rendererfor the mode: listening address, relay address,-E/-Xmapping, port range, listeners, realm, secret, denied peers. Every coturn flag must already appear ininternal/relay/testdata/coturn-4.18.0-r0-help.txt. Before adding a flag, re-capture that file from the pinned image (docker run --rm <pinned coturn> turnserver --help) and updatedocs/adr/0008-coturn-config-rendering.md. - Golden tests, one file per mode under
internal/relay/testdata/, plus a planner test for stability, rebalancing and disjointness. TheFuzzRenderertarget must still pass. - Webhook validation for mode-specific config in
internal/webhook/v1alpha1/turnpool_webhook.go: required fields present, forbidden fields absent, ranges partitioned without overlap. - An e2e case in
test/e2e/that proves the mode with real relays: the advertised address is the expected one, the ranges are disjoint, and each relay answers a real TURNAllocate. Fixtures go intest/fixtures/. - An ADR
docs/adr/NNNN-addressing-mode-<name>.md: what the mode is for, what it costs, what capacity it actually adds (often none), and what it forbids. Update the modes table indocs/adr/0001-addressing-modes.mdanddocs/capacity-model.mdin the same change. - Prove it:
make cithenmake test-e2e.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |