alktunnels/CHANGELOG.md

Changelog

All notable changes to this crate are documented here. The format is based on Keep a Changelog, and this crate adheres to Semantic Versioning.

Unreleased

0.2.0 - 2026-09-20

The graduation release: the direct op + the bind-first/forwarded metadata flow (ADRs 007/008), over alkcall 0.8.0. Composed against by alksocks (the SOCKS5 layer) and the planned alknodes assembly.

Added

• TunnelListener — the listen-flow consumer session (ADR-008 §4) — the listen-flow sibling of TunnelSession: TunnelListener::open (rides ChannelClient::open_channel_with_reply, alkcall 0.8.0's U-2 surface — the full reply arrives and the bind-first bound/ listen fields project through the lenient listen_reply_fields; adopt-free construction — the client already adopted the channel), bound()/listen() (the Option posture — None for dial/accept-first producers and old producers), and the listen channel's teardown ownership (ADR-005's posture extended to the listen flow): close (the graceful EOF sentinel via shutdown, then the reap) and Drop (the held write half drops → the mux pump's implicit-EOF chunk → the far accept dispatcher's teardown signal; sync reap — never leaks). The held BiStream's write half stays IDLE and private (a listen channel has no data-plane role; pumping one is meaningless). No Clone (compile-asserted). Forwarded sessions are NOT owned by the listener — they arrive as ordinary adopted-side TunnelSessions on the opener's manager (adopt gains nothing, pinned by test); the assembly correlates them via the listen() token (the receipt queue is assembly-side bookkeeping).

• The local feature's bind-first substrate half (ADR-008 §1, shape 3) — the real-socket sources behind the committed BindFn/BindFirstAcceptLoop contracts (behind local; the default crate stays wasm-clean): bind_tcp_first (port 0 resolved via local_addr — the bound reply field's data) + TcpListenerHalves::accept_pair (one accept → (peer, halves) — the peer rides accept()'s return, the forwarded op's peer carrier); unix bind-first parity shipped (OQ-TN-14): bind_unix + UnixListenerHalves (local_addr, the queue-feeding accept_loop, the bind-first accept_pair — an unnamed (autobind) peer fails loud: the forwarded peer param requires an address) + bind_unix_first; the assembly conveniences local_bind_first() (tcp/unix dispatch; udp fails loud — a UDP socket has no accept, the bind-first shape is not defined there, never a fake listener) and local_bindfirst_accept_loop() (downcasts the plan's opaque listener to the module's wrappers; a foreign listener type fails loud as handler_error). The accept-FIRST shapes (accept_loop + AcceptQueue) are untouched. The direct-op DialFn reuse is verified + pinned: local_dial is shared unchanged (the UDP framed wrap happens inside the closure — review 001 U-1); a TunnelSession::open_direct + Substrate::Udp test drives a REAL UDP echo socket through the direct op's establisher path.

• The forwarded op's SERVING side + the lenient reply projection (ADR-008 §3 as amended) — the listen-opener half, the receipt counterpart to the bind-first producer (the opener SERVES the op; the producer CALLS it per accept): ForwardedHandler (the injected assembly handler — the parsed params + the channel BiStream; the assembly owns the pump, since the local halves are assembly state)

  • make_forwarded_op_handler (the built-in wrapper: deny-unknown params parse (a malformed open fails LOUD → the wrapper returns early → teardown-at-birth reaps the channel — no phantom, the correct shape for a malformed ingress), accept_bi FIRST (R-02 accepted-flag telemetry), then wrapper→assembly bridge, the injected handler's JoinHandle awaited inline); + register_tunnel_forwarded_openable (register_openable — no establisher, the data plane starts immediately; scope gate tunnel:forwarded, ingress — a separate grant from tunnel:open/tunnel:direct, never implied by either). Plus listen_reply_fields (the lenient, infallible session-surface projection of the bind-first reply — unknown extra reply fields tolerated, a malformed shape logs loud and surfaces both-None; shared with TunnelListener). Correlation-miss teardown semantics documented + test-pinned: the assembly holds the map, its error path drops the stream, the channel reaps (the producer's accept loop drops the accepted connection on the open's failure — the shapes mirror).

• The bind-first establisher + accept dispatcher (shape 3, ADR-008 as amended) — the -R/ingress establisher whose establishment phase BINDS (the address-first-vs-accept-first deadlock dissolves; the accept wait lives in the teardown-governed pump phase): BindFn (the substrate bind function — the platform boundary, the protocol never binds) + BoundListener (the opaque listener + the real OS-chosen bound address); bindfirst_establisher (registry namespace gate → token mint → bind → bound + listen reply fields via Establishment::with_reply_field → the BindFirstPlan plan payload; the token mint is the pinned discipline — non-zero- seeded AtomicU32, per-open fresh, per-producer unique, token 0 never minted); BindFirstAcceptLoop (the type-erased accept closure — receives the opaque listener, yields (peer, halves) per accept); ForwardedOpener (the per-accept forwarded-open caller — the call plane: call_with_payload on channel 0 + manager.adopt_channel, the reverse POC's shape); make_bindfirst_accept_handler (the dispatcher: accept_bi first per R-02, the idle listen-stream EOF cancels the loop and tears the listener down, per-accept pump_bidi tasks tracked by the handler's JoinHandle — a forwarded pump never outlives its listener; forwarded-open failures are per-accept isolated — log + drop, the loop continues, v1 no retry); register_tunnel_bindfirst_openable (same spec + tunnel:open scope gate as the dial/listen variants — the per-registration establisher posture; the injected seams ride BindFirstInjections {bind, accept_loop, open_forwarded} + the optional CF-006 identity witness). The opener-side forwarded-op serving shape (register_openable, no establisher) landed with tunnels/forwarded-receipt.

• The forwarded op + the bind-first params surface (ADR-008 as amended) — the wire-stable types pin first (the ordering tunnels/params used for the base op): OP_TUNNEL_FORWARDED / TUNNEL_FORWARDED_SCOPE constants; TunnelForwardedParams {listen, substrate, peer} (deny-unknown; listen is the producer-minted correlation token, positive by wire contract — schema minimum: 1 + a serde-level pin) with a per-substrate peer sub-schema (malformed peers fail the registry's schema gate before the opener-side handler); tunnel_forwarded_spec() (Sub-typed, External, alk/tunnel ALPN marker, no establisher — the forwarded data plane starts immediately); TunnelListenReply + parse_listen_reply (the typed projection of the bind-first listen open's additive bound/listen reply fields — unknown reply fields tolerated, malformed ones fail loud via the new TunnelError::MalformedReply); BindFirstPlan (the opaque assembly-typed listener + the token — the plan payload the bind-first establisher/accept-dispatcher task consumes).

• The direct op (channels/tunnel/direct, ADR-007) — dynamic- target egress (the ssh direct-tcpip / SOCKS5 CONNECT shape), riding the same alk/tunnel ALPN: SubstrateAddr (the untagged substrate-shaped address object, also the forwarded op's peer shape) + TunnelDirectParams {substrate, target} with a per-substrate input_schema (malformed targets fail the registry's schema gate — INVALID_INPUT — before the establisher), tunnel_direct_spec(), direct_establisher (+ witness variant; no registry lookup — unknown_resource can never fire; targets render to the same backing-string form the registry backings use and ride the SAME injected DialFn), register_tunnel_direct_ openable (same pump handler + plan-flow as the base op), and TunnelSession::open_direct (separate constructor — tunnel:direct is a separate grant from tunnel:open, never implied by it; the session type, data planes, and teardown API are identical). An old producer rejects the unknown op loudly (NOT_FOUND).

Changed

• alkcall 0.7.1 → 0.8.0 (crates.io). The two upstream asks the graduation ADRs depend on landed (alkcall review 008): the establisher → reply projection (Establishment::with_reply_field, ADR-049 amendment 3 — the bind-first bound carrier) and flavor-form open-op ids in discovery (ADR-047 amendment 3 — channels/tunnel/direct-shaped ops reconstruct their channel_open marker through discovery, so hub relay wraps them as channels, not plain forwarding stubs). Plus the bonus: ChannelRelay + HubLegTemplate (ADR-051) — the hub re-produce machinery the graduation's re-produce story assumed would be assembly-layer is now in-tree, with bound flowing end-to-end per-hop-truthful (ADR-051 §6, ADR-008 §6's sentence realized). No alktunnels API or wire change in this bump; 71/91 tests pass, wasm-clean verified.

• BindFirstPlan gains substrate: Substrate (review 002 M-1 remediation) — the accept dispatcher's silent unwrap_or(Substrate::Tcp) fallback (the second TunnelParams re-parse of wire input) is removed: the establisher stamps the parsed substrate into the plan (one parse, one source of truth) and the dispatcher reads it from the plan it already downcast. A drift can no longer silently stamp Tcp into a UDP listen tunnel's forwarded opens (a raw-vs-framed data-plane mismatch on the opener side). Plan-payload change is pre-consumer (no external BindFirstPlan consumer yet). Pinned by forwarded_opens_carry_plan_stamped_substrate (a UDP bind-first flow whose forwarded opens carry substrate: udp from the plan).

0.1.0 - 2026-09-10

The initial release: the v1 tunnel protocol implementation over alkcall 0.7.x channels, spec-complete (Phase 1) and implementation- complete (Phase 2, review 001 findings remediated).

Added

• Wire surface (one-way-door stable from this release): the channels/tunnel/sub open op on the alk/tunnel ALPN; params {resource, substrate} (deny_unknown_fields; ADR-001); the tunnel:open scope gate (ADR-006).
• Data-plane codec (ADR-003): raw pass-through for stream substrates (tcp, unix); mandatory [len: u16 BE] boundary- preserving framing for udp (len = 0 a legal empty datagram, never EOF; oversize rejected at frame time; truncation fails loud — OQ-TN-13). The BAST contract: docs/architecture/bast.md.
• Producer half (ADR-004): ResourceRegistry, tunnel_establisher (dial shape) and listen_establisher (the -R far-side accept shape) over alkcall's establishment surface (ADR-049), make_tunnel_pump_handler (the pump_bidi two-pump contract, alkcall ADR-050), and the register_tunnel_openable / register_tunnel_listen_openable registration helpers.
• Consumer half (ADR-005): TunnelSession — open (forward) / adopt (reverse), substrate-shaped data planes (stream_halves, take_halves, send_datagram/recv_datagram), pump ownership (pump_against), teardown ownership (close/join/Drop); open_reverse_channel for the hub-call path.
• local feature (non-wasm): dial_tcp, bind_tcp + TcpListenerHalves accept loop, connect_udp wrapped in the FRAMED UdpHalf adapter (the codec composes at the substrate boundary — review 001 U-1), dial_unix, and the all-substrate local_dial closure. Stdio intentionally out of scope (alktty's pipe mode owns process stdio — OQ-TN-14).
• Identity seam (alkcall 0.7.0 CF-005/CF-006): payload-token > ServingConfig.identity > transport identity precedence proven end-to-end; the per-call opener identity reaches the establisher.
• Test suite: 71 tests default / 91 with local, including the review 001 gates (real-socket UDP framing probes, the AcceptQueue lost-wakeup regression, the identity-precedence matrix). Wasm-clean default crate verified (wasm32-unknown-unknown check + clippy).