touch-tcp-pool

Estrelas13

Forks2

Atualizado21 de maio de 2026 às 16:52

Make changes to the TCP host-port pool or L4 bootstrap safely. Highest-risk area in the repo — PR

Instalação

Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.

Fonte

aerol-ai

aerol-ai/microvm

Abrir repositório GitHub Ver repositórios do creator

Download

Ocupações relacionadasSOC

Baseado na classificação ocupacional SOC

Administradores de redes e sistemas de computadorInformática e Matemática·SOC 15-1244

SKILL.md

readonly

name	touch-tcp-pool
description	Make changes to the TCP host-port pool or L4 bootstrap safely. Highest-risk area in the repo — PR

Change the TCP host-port pool or L4 bootstrap

Highest-risk area in the repo. Read pr-review.md §7 in full before editing.

What counts as "touching" this area

Any change to:

Store.TryReserveHostPort semantics (internal/store/store.go)
The partial unique index on exposed_ports.host_port
Service.allocateHostPort allocator loop (internal/service/)
Service.EnsureLayer4 / Service.EnsureLayer4Ready (internal/service/service.go)
The l4Ready atomic.Bool latch or the l4Mu mutex
allocatorRandomAttempts constant (internal/service/service.go)
pkg/caddy/client.go L4 route installation

What you MUST do

Regression test, required, not optional:
- Pool / allocator / TryReserveHostPort changes → internal/store/store_test.go.
- EnsureLayer4 / EnsureLayer4Ready / latch changes → internal/service/layer4_bootstrap_test.go.
- The existing tests give you the shape — copy and adapt.
PR call-out: fill in the "L4 / host-port-pool changes" section of the PR template with a link to the regression test.
Never collapse ReserveHostPortResult back into a bool. The three states (Reserved / Existing / neither) are what prevents pool walks on PK collisions. Look up the type before editing — the middle state matters.

Why this area is fragile

The allocator is randomized-first (allocatorRandomAttempts = 16 random tries) then falls back to a linear scan. Removing the random phase makes p95 spike under load; removing the fallback fails near pool exhaustion.
The partial unique index lets multiple sandboxes "use" port 0 (sentinel) while still uniquing real allocations. Don't replace it with a non-partial unique constraint.
L4 bootstrap is best-effort at daemon start. Caddy may not be reachable on a cold restart, so the expose path retries under l4Mu when the latch is still false. Failure must leave the latch unset so the next caller retries. Success latches forever.

Worked anti-patterns

Walking the host-port pool on a primary-key conflict during re-expose → caused the live incident in PR #16.
Retrying L4 bootstrap on every request instead of behind the latch → thundering herd on the caddy admin API.
Failing the daemon outright on a transient bootstrap error → makes the daemon un-restartable after a caddy hiccup.
Logging-and-forgetting an L4 bootstrap error → the user's first TCP expose gets a confusing "layer4 server not found" from caddy.

Reference reading

pr-review.md §3 (lazy-bootstrap pattern) — canonical shape mirrored from EnsureLayer4Ready.
pr-review.md §7 (this area specifically) — the rules above are summarized from here.
internal/service/layer4_bootstrap_test.go — read the existing test names; they describe the invariants you must preserve.

Mais deste repositório

mesmo repositório

maintain-coverage

aerol-ai/microvm

Keep the Go tree at its ~85% line-coverage bar when new or changed code lands. Finds the packages your branch touched, measures their coverage, locates the uncovered lines, and writes table-driven tests in the package's existing style. Use before opening any PR, or when the user says "add tests", "the new code has no tests", "check coverage", "bring this up to 85%", or "why did coverage drop". Proactively suggest right after a new package/driver/handler is written and before the PR goes up.

2026-06-1613

touch-create-sandbox

aerol-ai/microvm

Safely modify Service.CreateSandbox or anything it transitively calls. Walks the boot path step-by-step, enforces the failure-cleanup rules, and reminds you to document boot-latency impact in the PR. Use when the user asks to "change sandbox creation", "add this to sandbox boot", "modify CreateSandbox", or any change that lands inside internal/service/service.go near the create path. Proactively suggest as soon as a change is proposed that adds DB queries, HTTP calls, file I/O, or lock acquisitions to sandbox boot.

2026-05-2113

add-daytona-route

aerol-ai/microvm

Add a Daytona-SDK-compatible route under /daytona/... by translating Daytona's wire shape to internal/service calls. Keeps version branching out of internal/. Use when the user asks to "support this in the Daytona facade", "add a /daytona route", "make Daytona SDK work with X", or wants to extend Daytona compatibility coverage. Proactively suggest when adding a feature that has a corresponding Daytona SDK call.

2026-05-1413

add-docs-page

aerol-ai/microvm

Add a new AerolVM docs page (.mdx) with synced five-language tabs and register it in the Starlight sidebar. Enforces the repo's hard rules — no raw curl, all five SDK languages, syncKey="lang" on every tab block. Use when the user asks to "add a docs page", "document this feature", "write the docs for X", or after shipping a user-facing capability that isn't documented yet. Proactively suggest after a new SDK method or top-level feature lands.

2026-05-1413

add-e2b-route

aerol-ai/microvm

Add an E2B-SDK-compatible route under /e2b/... by mirroring the Daytona facade pattern. The /e2b package does not exist yet — copy pkg/api/daytona/ as the template. Forces the open create-idempotency design question to be answered before coding. Use when the user asks to "build the e2b facade", "add an /e2b route", "make E2B Python SDK work with X", or work on plans/sdk-compatibility/e2b/. Proactively suggest when an E2B SDK call needs server-side support.

2026-05-1413

add-mount-adapter

aerol-ai/microvm

Add an external-storage mount adapter (S3, NFS, SSHFS, rclone, etc.) under pkg/mounts/adapters/. Enforces the host-side input threat model and the per-sandbox cleanup contract. Use when the user asks to "add a mount type", "support mounting X", "add a storage adapter", or wants AerolVM sandboxes to consume a new backing storage. Proactively suggest when a feature request implies a new mount backend.

2026-05-1413

Change the TCP host-port pool or L4 bootstrap

Highest-risk area in the repo. Read pr-review.md §7 in full before editing.

What counts as "touching" this area

Any change to:

Store.TryReserveHostPort semantics (internal/store/store.go)

The partial unique index on exposed_ports.host_port

Service.allocateHostPort allocator loop (internal/service/)

Service.EnsureLayer4 / Service.EnsureLayer4Ready (internal/service/service.go)

The l4Ready atomic.Bool latch or the l4Mu mutex

allocatorRandomAttempts constant (internal/service/service.go)

pkg/caddy/client.go L4 route installation

What you MUST do

Regression test, required, not optional:

Pool / allocator / TryReserveHostPort changes → internal/store/store_test.go.
EnsureLayer4 / EnsureLayer4Ready / latch changes → internal/service/layer4_bootstrap_test.go.
The existing tests give you the shape — copy and adapt.

PR call-out: fill in the "L4 / host-port-pool changes" section of the PR template with a link to the regression test.

Never collapse ReserveHostPortResult back into a bool. The three states (Reserved / Existing / neither) are what prevents pool walks on PK collisions. Look up the type before editing — the middle state matters.

Why this area is fragile

The allocator is randomized-first (allocatorRandomAttempts = 16 random tries) then falls back to a linear scan. Removing the random phase makes p95 spike under load; removing the fallback fails near pool exhaustion.

The partial unique index lets multiple sandboxes "use" port 0 (sentinel) while still uniquing real allocations. Don't replace it with a non-partial unique constraint.

L4 bootstrap is best-effort at daemon start. Caddy may not be reachable on a cold restart, so the expose path retries under l4Mu when the latch is still false. Failure must leave the latch unset so the next caller retries. Success latches forever.

Worked anti-patterns

Walking the host-port pool on a primary-key conflict during re-expose → caused the live incident in PR #16.

Retrying L4 bootstrap on every request instead of behind the latch → thundering herd on the caddy admin API.

Failing the daemon outright on a transient bootstrap error → makes the daemon un-restartable after a caddy hiccup.

Logging-and-forgetting an L4 bootstrap error → the user's first TCP expose gets a confusing "layer4 server not found" from caddy.

Reference reading

pr-review.md §3 (lazy-bootstrap pattern) — canonical shape mirrored from EnsureLayer4Ready.

pr-review.md §7 (this area specifically) — the rules above are summarized from here.

internal/service/layer4_bootstrap_test.go — read the existing test names; they describe the invariants you must preserve.