get2knowio / get2knowio/deacon
auto-forward: surface extensions (configurable+adaptive poll, forward subcommand, exec --auto-forward)
- Dominant language
- Rust
- Stars
- 2
- Forks
- 0
- Avg merge
- 2h 36m
- Merged PRs (30d)
- 78
Description
Tracked deferrals from `up --auto-forward` (spec `015-auto-forward-ports`, tasks **T060** + **T056**; shipped in #188). Groups the v1-surface extensions and the detection-latency question. Acceptance: added without breaking the v1 boolean `--auto-forward` surface.
This bundles four related, individually-small items.
---
### 1. Configurable poll interval
v1 uses a fixed ~1s poll (`POLL_INTERVAL` in `crates/core/src/port_forward/daemon.rs`, FR-004).
- **Gotcha:** trivial to expose, but a too-small interval multiplies `docker exec cat /proc/net/tcp` overhead; keep a sane floor.
- **Path:** add `--auto-forward-poll-interval ` (plumbed to `DaemonConfig`), with a documented minimum.
### 2. Adaptive polling — the practical answer to "event-driven detection" (folds in T056)
T056 proposed netlink/inotify event-driven detection. **Recommendation: don't.** Hidden issues with true event-driven:
- **No kernel push for "entered LISTEN":** `/proc/net/tcp` doesn't support inotify (synthetic procfs); `sock_diag`/`inet_diag` netlink is request/response, not a subscription — so netlink is just *binary polling*, not events. The only real push is **eBPF** on `listen()`, which needs `CAP_BPF`/`CAP_SYS_ADMIN` + recent kernel + BTF (privileged, fragile, anti to our "no root, any image" design).
- **Reintroduces the in-container-agent problem** (see #190): netlink/eBPF must run inside the container netns → ship/embed an agent + capabilities.
- **The 1s poll already meets SC-002 (≤~2s) at negligible CPU**, so the payoff is polish, not capability.
- **Path (recommended):** *adaptive* polling — poll fast (~200–300ms) for the first few seconds after `up` (when declared/expected ports are most likely to appear) then back off to the steady interval. ~90% of the perceived-latency win, a handful of lines in the supervisor loop, no agent/capabilities. Leave true event-driven detection explicitly **wontfix-unless-demanded**.
### 3. Standalone `forward` subcommand
Attach a forwarder to an already-running container without a full `up`.
- **Gotcha:** must reuse the exact `ContainerIdentity`/marker/registry/reap machinery so it composes with `up`/`down` adopt-or-reuse (no parallel lookup path). **Beware the pre-existing exec/up resolution mismatch (#187)** — a `forward --workspace-folder` would hit the same `configHash`-mismatch wall; resolve #187 first or resolve by `--container-id`/label.
- **Path:** `deacon forward [--workspace-folder|--container-id] [--declared-port ...]` that spawns/adopts the same daemon.
### 4. `exec --auto-forward` attach
Start forwarding as a side effect of `exec`.
- **Gotcha:** `exec` currently resolves containers via `ContainerIdentity` and is subject to #187; lower value than the others.
- **Path:** thin wrapper that adopt-or-spawns the forwarder for the resolved container before running the command.
---
## Suggested sequencing
Do **(1) + (2)** first (cheap, in-loop, high perceived value). **(3)** after #187 is fixed (shared resolution). **(4)** last (lowest value). Keep `--auto-forward` as the stable v1 entry point throughout.
Contributor guide
Assessment
This issue has not been assessed yet.