alktunnels/docs/architecture/decisions/005-consumer-session-owns-teardown.md

ADR-005: The Consumer Session Type Owns Teardown

Status

Accepted (2026-09-07; resolves the reverse POC W3 finding)

Context

A tunnel channel's two ends have asymmetric lifecycle machinery:

• The serving side (the side the open op ran on) is wrapper-managed: the open wrapper awaits the pump handler's JoinHandle, and its completion triggers channel teardown (drop of the demux sender = EOF to the handler's read half — alkcall ADR-049
  • review 007 R-02). Out-of-band channel/close also tears it down. Nothing leaks.
• The adopting side (the side that called the open op and adopted the channel ID — the consumer) has NO such machinery: ChannelManager::adopt_channel installs routing state nothing awaits. The consumer-side pump (pump_bidi spawned locally) is somebody's JoinHandle; the adopted channel state is nobody's to reap. If the assembly layer drops both, the channel entry leaks in the manager until transport EOF (clear_all) — and worse, a consumer that drops the pump handle mid-flight aborts the pump without reaping, leaving half-open state on the peer.

The reverse POC found this by construction (W3, 2026-09-07): the hub must hold its pump handle and reap (teardown_channel) itself — ReverseTunnel::join_and_reap/close in the POC. The lifecycle is assembly-layer by design (OQ-TN-04 — no forced binding means no protocol-owned listener lifecycle either), but the POC demonstrated that leaving teardown discipline to each assembly layer's memory is exactly the kind of gap the spec must close with a type, not a doc note.

Related constraint from the same POC pass: one session = one channel = one tunnel (the channel ID is the flow key, OQ-TN-02's resolution); the session is also the natural owner of the substrate-shaped data plane (raw halves vs datagram codec, ADR-003).

Decision

The consumer half is a typed session, TunnelSession, and it owns its teardown:

• Construction: TunnelSession::open(client, params) — calls the open op (ChannelClient::open_channel on the forward path; the reverse path's open_reverse_channel + adopt_channel equivalent), adopts the returned channel ID, splits the channel BiStream, and presents the substrate-shaped data plane:
  • Stream variant: raw halves (AsyncRead/AsyncWrite) — the halves ARE the tunnel.
  • Datagram variant: send_datagram/recv_datagram over the mandatory codec (ADR-003) — boundary-preserving, len=0 is an empty datagram, recv_datagram returns None only on stream EOF.
• Pump ownership: the session's pump_against(accepted_halves) (the reverse-flow use) spawns pump_bidi and holds the returned JoinHandle. For the pure consumer (no local pump — the session halves ARE handed to the caller), the session does not spawn; the caller drives the halves and the session still owns the channel entry.
• Teardown API (the point of the ADR):
  • close(self) — abort the pump (if session-owned), tear down the adopted channel (teardown_channel), consume the session. The abort path (ungraceful).
  • join(self) — await pump completion (both directions finished), THEN reap the adopted channel, return the (u64, u64) copy counts from pump_bidi for observability. The graceful path.
  • Dropping the session without either: the Drop impl tears the channel down (the panic-free fallback — never leak the entry). Drop cannot await, so it aborts the pump and calls the sync teardown_channel; this is semantically close.
• Half-open semantics fall out of pump_bidi (ADR-050): one direction EOFs → the opposite sink shuts down (the EOF sentinel crosses the mux) → the other pump keeps running until its own EOF. The session's join completes when BOTH pumps finish. Half-close semantics validated end-to-end (reverse POC W4).
• Error surface: a failed open resolves a typed error — ChannelOpenError::CallFailed carrying the wire CallError; branch on establishment_reason() for channel:open_failed's reason (ADR-049 §4). A failed open never yields a session (no phantom session, mirroring the no-phantom-channel property).
• TunnelSession does not implement Clone. One session = one channel; aliasing a session would alias its teardown. Multi-channel consumers hold a Vec<TunnelSession> (or the assembly layer does).

Consequences

• Assembly layers cannot leak adopted channels by forgetting to reap — the type is the discipline (the W3 gap closes structurally).
• The reverse-flow initiator gets the same session shape as the forward consumer: the reverse POC's hub-side ReverseTunnel is the seed; the spec generalizes it so -L and -R consumers share one API (role-follows-resource, OQ-TN-03).
• Observability for free: join's copy counts surface the data-plane volumes without extra plumbing.
• Serving-side parity is upstream's: the worker's pump handler is already wrapper-managed (R-02); the session only fixes the adopter asymmetry.
• Drop-based teardown is best-effort (abort + sync reap, no await) — the documented contract; graceful flows call join or close explicitly.

References

• Reverse POC: docs/research/reverse-poc-summary.md §W3 (the finding), §W4 (half-close validation)
• OQ-TN-03, OQ-TN-04, OQ-TN-09 (promoted)
• alkcall ADR-049 + review 007 R-02 (wrapper-managed serving side), ADR-050 (pump_bidi + copy counts), ADR-047 §5 (allocation — the initiator adopts)
• AGENTS.md convention 10 (limits inherited — the session adds no second bookkeeping layer; it owns exactly one channel's lifecycle)