chore: consume alkcall 0.6.0; OQ-TN-06 resolved by ADR-050
alkcall 0.6.0 landed the review 007 remediation (filed from this crate's UDP POC pass): - R-01: Establishment carries the plan (ADR-049 amendment 2) — typed-opaque ChannelPlan, OpenHandler gains the plan param, the wrapper threads it; the POC's side-channel HandleHandoff and its same-resource race are dead (the establisher returns the dialed handle: Ok(Establishment::new(plan))) - R-02: OpenHandler JoinHandle lifetime contract documented (early return = teardown-at-birth) + yield-once acceptance flag and debug! birth-teardown hint - R-03: pump_bidi pinned upstream (ADR-050) — two pumps, shutdown-on-completion, (u64, u64) copy counts, errors EOF-shaped alktunnels updates: - Cargo.toml: alkcall 0.5.0 -> 0.6.0 (lockfile resolves 0.6.0) - AGENTS.md convention 8: use alkcall channels::pump_bidi, do not hand-roll; await it inline inside the OpenHandler's task - AGENTS.md convention 11: pin note updated; amendment 2 marked load-bearing (Establishment::new replaces side-channel handoff) - AGENTS.md convention 13: fixed ADR citation bug (was "alkcall ADR-024, ADR-050" — those are peer-graph-routing and pump-bidi; intended targets are alknet ADR-024/ADR-050 with their alkcall ports ADR-019/ADR-011) - AGENTS.md architecture context: ADR-050 + ADR-049 amendment 2 rows - phase-0-findings OQ-TN-06: RESOLVED — pump_bidi landed upstream; the POC is cited as convergence input alongside alktty and the assembly-layer copies; Phase 1 consumes the helper - phase-0-findings OQ-TN-09: implementation note updated — Establishment::new(plan) replaces the handoff sketch - poc-summary: resolutions addendum for both upstream findings (R-01/R-02/R-03 with the typed-opaque and (u64, u64) deviations recorded); references note 0.6.0 supersession Verification: cargo test (0 tests, ok), clippy --all-targets -D warnings, fmt --check, wasm32 check, doc --no-deps — all clean
This commit is contained in:
@@ -65,8 +65,8 @@ just spawned implementation agents.
|
||||
expected on public API. Inline `//` comments only when the user asks
|
||||
or when a non-obvious safety/correctness constraint would otherwise be
|
||||
missed (e.g., "a two-pump tunnel must shut down the opposite sink on
|
||||
pump completion — `try_join!` alone deadlocks; see alkcall's
|
||||
channels-adapter spec / alknet ADR-078").
|
||||
pump completion — `try_join!` alone deadlocks; see alkcall ADR-050's
|
||||
`pump_bidi` / alknet ADR-078").
|
||||
|
||||
2. **Error handling** — `thiserror` for library error types
|
||||
(`TunnelError`; `HandlerError`/`StreamError` come from
|
||||
@@ -131,10 +131,14 @@ just spawned implementation agents.
|
||||
canonical two-pump handler (one pump per direction). Each pump MUST
|
||||
shut down the opposite sink when it completes; `tokio::try_join!`
|
||||
alone deadlocks. This was POC-validated in the alknet-channels POC
|
||||
(Target 3) and pinned as alknet ADR-078. The channels layer drops
|
||||
all per-channel senders on transport EOF — rely on that for
|
||||
teardown, and emit EOF sentinels (zero-length chunks) on clean
|
||||
sink shutdown.
|
||||
(Target 3), pinned as alknet ADR-078, and the helper is pinned
|
||||
upstream as alkcall `channels::pump_bidi` (ADR-050, review 007
|
||||
R-03) — use it; do not hand-roll the two-pump shape. The channels
|
||||
layer drops all per-channel senders on transport EOF — rely on
|
||||
that for teardown, and emit EOF sentinels (zero-length chunks) on
|
||||
clean sink shutdown. Await `pump_bidi` inline inside the
|
||||
`OpenHandler`'s task — the returned `JoinHandle` must track the
|
||||
data-plane lifetime (R-02; early return = teardown-at-birth).
|
||||
|
||||
9. **No forced local binding** — a tunnel must not require the producer
|
||||
(or consumer) to bind a local port. The POC's TCP-tunnel shape
|
||||
@@ -163,12 +167,14 @@ just spawned implementation agents.
|
||||
`alkcall::core`. Do not vendor copies into this crate. alkcall is
|
||||
v0.5.x — breaking changes are expected at this major-zero stage;
|
||||
this is an early consumer, so we find and fix issues upstream
|
||||
rather than working around them. Pin `alkcall = "0.5.0"` and bump
|
||||
deliberately. The 0.5.0 establishment phase (ADR-049) is
|
||||
load-bearing for this crate: tunnel opens use
|
||||
rather than working around them. Pin `alkcall = "0.6.0"` and bump
|
||||
deliberately. The 0.6.0 establishment surface (ADR-049 + amendment
|
||||
2) is load-bearing for this crate: tunnel opens use
|
||||
`register_openable_with_establisher` so a refused target dial is
|
||||
a typed `channel:open_failed` call error, never a phantom
|
||||
channel.
|
||||
a typed `channel:open_failed` call error, never a phantom channel,
|
||||
and the establisher returns the dialed handle via
|
||||
`Establishment::new(plan)` (typed-opaque `ChannelPlan`) — no
|
||||
side-channel handoff.
|
||||
|
||||
12. **BAST document for the wire format** — when the tunnel wire format
|
||||
gains binary framing (if any beyond pass-through), it carries a
|
||||
@@ -190,7 +196,8 @@ just spawned implementation agents.
|
||||
(`provider.owns(id_ref, kind, &id, "tunnel")` — the 4-arg shape;
|
||||
`OwnershipStore::record` is the 3-arg shape). Tunnels reach local
|
||||
networks — treat the open gate as the security boundary. See
|
||||
alkcall ADR-024, ADR-050.
|
||||
alknet ADR-024 (registry layering, alkcall ADR-019), alknet
|
||||
ADR-050 (ownership, alkcall ADR-011).
|
||||
|
||||
14. **Feature flags** — substrate backends may be feature-gated if the
|
||||
need arises. The base crate should compile lean (no socket/platform
|
||||
@@ -260,9 +267,13 @@ non-backend module changes.
|
||||
- alknet ADR-093 / alkcall ADR-035 — channels pure channel
|
||||
multiplexing (8-byte header, no `stream_type`); the tunnel payload
|
||||
is raw bytes inside the `BiStream`
|
||||
- alknet ADR-078 — two-pump shutdown-on-completion (the tunnel
|
||||
handler pattern; a helper extraction was deferred until a second
|
||||
two-pump consumer exists — this crate is that second consumer)
|
||||
- alknet ADR-078 / alkcall ADR-050 — two-pump shutdown-on-completion
|
||||
(the tunnel handler pattern); the helper is pinned upstream as
|
||||
`alkcall::channels::pump_bidi` — use it, do not hand-roll
|
||||
- alkcall ADR-049 (amendment 2) — the establishment phase; the
|
||||
establisher returns the dialed handle via `Establishment::new`
|
||||
(typed-opaque `ChannelPlan`), replacing the POC's side-channel
|
||||
handoff
|
||||
- alknet ADR-074 / alkcall ADR-038 — `ChannelConnection` as a
|
||||
`BidiStreamSource`; every handler (TTY, tunnel, call) receives a
|
||||
`Connection`
|
||||
|
||||
Reference in New Issue
Block a user