docs(research): add alknet-channels POC summary — 3 targets validated, core refactor notes
This commit is contained in:
glm-5.2 committed
1 parent
5e07203b86
commit
6f1663a391
1 file changed
+463
@@ -0,0 +1,463 @@
|
||||
---
|
||||
status: complete
|
||||
last_updated: 2026-07-12
|
||||
---
|
||||
|
||||
# alknet-channels: POC Research Summary
|
||||
|
||||
**Status:** Research complete — all three high-leverage unknowns validated. The
|
||||
approach is viable; the remaining unknowns are spec-scope, not feasibility.
|
||||
**Date:** 2026-07-12
|
||||
**Scope:** Captures what the POC proved about the 9-byte chunk format, N-channel
|
||||
demux/mux, per-channel `Connection` presentation, and the tunnel handler — and
|
||||
what it surfaced for the coming `alknet-channels` crate spec and the light
|
||||
`alknet-core` refactor that should land alongside it.
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
A POC (`alknet-channels-poc`, `/workspace/alknet-channels-poc`) validated the
|
||||
three highest-leverage unknowns of the channels layer over a
|
||||
`tokio::io::duplex` stand-in transport:
|
||||
|
||||
1. **Chunk format + N-channel demux/mux** — the 9-byte format
|
||||
(`[channel_id:u32 be][stream_type:u8][length:u32 be][payload]`) is a clean
|
||||
generalization of TTY's 5-byte format. The sync core (`parse_header`/
|
||||
`write_header`) is pure, WASM-compatible by construction. The mpsc-bridged
|
||||
async shell scales to N concurrent channels with per-channel order
|
||||
preservation and cross-channel isolation, and bounded-buffer backpressure
|
||||
(DP-5 option c) works for the simple case.
|
||||
2. **Per-channel `Connection` presentation** — `Connection::from_stream` (from
|
||||
the transport-generalization work) is sufficient to present each channel as
|
||||
a `Connection` a `ProtocolHandler` can drive unchanged. A minimal echo
|
||||
handler runs through the full demux→Connection→handler→mux path with zero
|
||||
channels-layer awareness. The yield-once `accept_bi` contract composes for
|
||||
handlers that loop `accept_bi` (like `TtyAdapter`).
|
||||
3. **Tunnel handler** — the bidirectional pump pattern (same shape as TTY's
|
||||
`pump_session`, two pumps instead of three) works as a generic port proxy
|
||||
through channels. A `TunnelHandler` of ~15 lines proxies a channel to a
|
||||
local TCP echo server with no chunk-format or channels-layer awareness, and
|
||||
a tunnel channel coexists with an echo channel on one channels connection
|
||||
without interference.
|
||||
|
||||
**28 tests pass** (5 wire codec + 7 mpsc stream adapters + 5 demux + 3 mux + 5
|
||||
echo handler + 3 tunnel handler). Clippy is clean for the POC's own code; the
|
||||
only remaining warnings are upstream in `alknet-core` (`types.rs:500`
|
||||
`Connection::close` has unused `code`/`reason` params — pre-existing, not
|
||||
introduced by this POC).
|
||||
|
||||
**Stretch goal validated:** the sync core (`wire.rs`) compiles cleanly under
|
||||
`wasm32-unknown-unknown`. The "WASM compatibility by construction" claim holds
|
||||
for the pure-byte-manipulation core; the async shell and the `alknet-core`
|
||||
dependency graph are NOT WASM-clean yet (transitive `getrandom`/`rand` deps),
|
||||
which is a Phase 1 concern, not a POC concern.
|
||||
|
||||
The POC depends on `alknet-core` only (path dependency,
|
||||
`default-features = false` — no QUIC needed for the POC), and uses
|
||||
`tokio::io::duplex` as the stand-in transport. It does NOT depend on
|
||||
`alknet-tty`, `alknet-call`, or any other handler crate. The echo and tunnel
|
||||
handlers are POC-local stubs, not the real adapters.
|
||||
|
||||
---
|
||||
|
||||
## The Sync Core / Async Shell Split (Confirmed)
|
||||
|
||||
The POC confirms the split proposed in `poc-plan.md` §"Design Principles":
|
||||
|
||||
- **Sync core (`wire.rs`)**: `parse_header(&[u8; 9]) -> ChunkHeader` and
|
||||
`write_header(channel_id, stream_type, length, &mut [u8; 9])`. Pure
|
||||
functions, no async, no platform deps. Validates `MAX_CHUNK_LEN` (matches
|
||||
TTY's 16 MiB cap, preserving the framing-disambiguation soundness property
|
||||
from ADR-052 §5). Compiles under `wasm32-unknown-unknown`.
|
||||
- **Async shell (`demux.rs` / `mux.rs`)**: `Demux::run` reads 9-byte headers +
|
||||
payloads off the transport via `read_exact`, routes payloads to per-
|
||||
`(channel_id, stream_type)` bounded `mpsc::Sender<Bytes>`. `Mux` frames
|
||||
`Bytes` from per-channel `mpsc::Receiver<Bytes>` back onto the transport.
|
||||
- **Per-channel reassembly (`mpsc_stream.rs`)**: `MpscRecvStream`
|
||||
(`mpsc::Receiver<Bytes>` → `AsyncRead`, ~50 lines) and `MpscSendStream`
|
||||
(`mpsc::Sender<Bytes>` → `AsyncWrite` with backpressure, ~60 lines). These
|
||||
back the `RecvStream`/`SendStream` the handler sees via
|
||||
`RecvStream::from_stream` / `SendStream::from_stream`.
|
||||
|
||||
The split is as clean as the TTY POC's was. The "don't have to async" pattern
|
||||
lives in the demux/mux shell; the core byte manipulation is pure and
|
||||
WASM-portable.
|
||||
|
||||
---
|
||||
|
||||
## POC Target 1: Chunk Format + N-Channel Demux/Mux
|
||||
|
||||
**Question:** Does the 9-byte format decompose and recombine N concurrent
|
||||
streams correctly, with per-channel order preservation and cross-channel
|
||||
isolation?
|
||||
|
||||
**Answer:** Yes. The demux routes chunks to per-`(channel_id, stream_type)`
|
||||
bounded `mpsc::Sender`s; the mux frames `Bytes` from per-channel receivers
|
||||
back onto the transport. Three concurrent channels with interleaved writes
|
||||
round-trip with no cross-channel contamination and per-channel order
|
||||
preserved (`demux_three_concurrent_channels_no_cross_contamination`,
|
||||
`mux_demux_round_trip_three_concurrent_channels`).
|
||||
|
||||
**Lenient unknown-`channel_id` handling (OQ-CH-12):** a chunk with an
|
||||
unallocated `channel_id` (or an unallocated `stream_type` on an allocated
|
||||
channel) is dropped with a debug log and an error counter, and the demux
|
||||
continues (`demux_unknown_channel_drops_lenient`). This matches SSH's
|
||||
behavior and survives transient mis-ordering during teardown. The error
|
||||
counter is exposed via `Demux::stats()` for observability. This is the
|
||||
recommended v1 behavior from the plan; the POC validates it works.
|
||||
|
||||
**Zero-length sentinel (TTY convention carried forward):** a zero-length
|
||||
chunk is delivered as an empty `Bytes`, which `MpscRecvStream` interprets as
|
||||
EOF (`demux_zero_length_sentinel_delivered`, `recv_zero_length_sentinel_is_eof`).
|
||||
This is the same convention as TTY's zero-length stdin/stdout chunks. See
|
||||
§"Issues Surfaced" below for a subtlety about how shutdown propagates this.
|
||||
|
||||
**Chunk-too-large:** a chunk with `length > MAX_CHUNK_LEN` returns
|
||||
`ChunkTooLarge` and does not corrupt the stream
|
||||
(`demux_chunk_too_large_does_not_panic`).
|
||||
|
||||
**Backpressure (DP-5 option c):** each `(channel_id, stream_type)` has an
|
||||
independent bounded `mpsc` buffer. A slow reader on one channel does not block
|
||||
another channel's reads — the demux's per-chunk `route` awaits the matching
|
||||
sender without holding a global lock. The 1 MiB tunnel test
|
||||
(`tunnel_large_payload`) exercises this end-to-end and does not deadlock.
|
||||
|
||||
---
|
||||
|
||||
## POC Target 2: Per-Channel `Connection` Presentation
|
||||
|
||||
**Question:** Is `Connection::from_stream` sufficient to present each channel
|
||||
as a `Connection` a `ProtocolHandler` can drive unchanged?
|
||||
|
||||
**Answer:** Yes. The `EchoHandler` (~5 lines of handler code) runs through the
|
||||
full demux→Connection→handler→mux path with zero channels-layer awareness.
|
||||
It calls `connection.accept_bi().await`, gets a `(SendStream, RecvStream)`
|
||||
pair, and pumps via `tokio::io::copy`. The handler does not know it is inside
|
||||
a channels connection.
|
||||
|
||||
**Wiring (`ChannelEndpoint`):** the POC's local equivalent of the symmetric
|
||||
client/server types (OQ-CH-14). `channel_endpoint()` constructs both sides of
|
||||
a channels connection (server demux/mux + client demux/mux, connected by two
|
||||
`tokio::io::duplex` pipes). `open_echo_channel(channel_id)` allocates a
|
||||
channel on both sides: the server side wraps `MpscSendStream`/`MpscRecvStream`
|
||||
as `Connection::from_stream(..., b"alknet/echo", None)` and spawns
|
||||
`EchoHandler::handle`; the client side returns a `ClientChannel { send, recv }`
|
||||
the test drives. This is the POC-local shape Phase 1 will generalize into
|
||||
`ChannelsAdapter::handle` (server) and `ChannelClient` (client).
|
||||
|
||||
**ALPN threading:** `handler_sees_alpn` validates that `Connection::from_stream`'s
|
||||
`alpn` parameter threads through correctly — the handler's
|
||||
`connection.remote_alpn()` returns the ALPN the channel was opened with.
|
||||
|
||||
**Yield-once contract:** `handler_loops_accept_bi_gets_one_session` validates
|
||||
that a handler that loops `accept_bi` (like `TtyAdapter`) gets exactly one
|
||||
session per channel, then `ConnectionClosed` on the second call. The
|
||||
yield-once `Connection::from_stream` path composes correctly for looping
|
||||
handlers.
|
||||
|
||||
---
|
||||
|
||||
## POC Target 3: Tunnel Handler
|
||||
|
||||
**Question:** Does the bidirectional pump pattern (same shape as TTY's
|
||||
`pump_session`, two pumps instead of three) work as a generic port proxy
|
||||
through channels?
|
||||
|
||||
**Answer:** Yes. The `TunnelHandler` (~15 lines of handler code) opens a
|
||||
`TcpStream` to a fixed target and runs two `tokio::io::copy` pumps:
|
||||
`recv → tcp_write` (client → target) and `tcp_read → send` (target → client).
|
||||
The handler contains zero chunk-format or channels-layer awareness — it
|
||||
only sees `Connection`/`SendStream`/`RecvStream`.
|
||||
|
||||
**Shutdown-on-completion (subtlety):** the naive `tokio::try_join!(c2t, t2c)`
|
||||
deadlocks — `t2c` waits forever for the TCP echo server to close, which only
|
||||
happens once the handler closes `tcp_write`, which only happens after
|
||||
`try_join` returns. The POC fixes this by shutting down the opposite sink
|
||||
when each pump completes: `c2t` shuts down `tcp_write` on EOF, `t2c` shuts
|
||||
down `send` on EOF. This is the `pump_session` shape with an explicit
|
||||
shutdown-on-completion step that the TTY adapter doesn't need (because TTY's
|
||||
three pumps coordinate via the exit-code future). The tunnel's two-pump
|
||||
shape needs it. See §"Issues Surfaced" below.
|
||||
|
||||
**Tests:**
|
||||
- `tunnel_echo_round_trip` — 1 KiB round-trips through the tunnel to a TCP
|
||||
echo server.
|
||||
- `tunnel_large_payload` — 1 MiB round-trips without corruption or deadlock,
|
||||
exercising the bounded-buffer backpressure path (the tunnel handler's
|
||||
`AsyncRead` side and the channels demux must not deadlock when the TCP
|
||||
echo server is slower than the channel writer).
|
||||
- `tunnel_concurrent_with_echo_channel` — one tunnel channel and one echo
|
||||
channel on the same channels connection, both running concurrently, neither
|
||||
blocks the other. The multiplexing is transparent.
|
||||
|
||||
---
|
||||
|
||||
## Issues Surfaced (For the Spec and the Core Refactor)
|
||||
|
||||
These are the things the POC ran into that should be addressed in Phase 1 or
|
||||
in the light `alknet-core` refactor landing alongside it. They are grouped by
|
||||
where the fix likely lives.
|
||||
|
||||
### In `alknet-core` (the refactor)
|
||||
|
||||
#### 1. `Connection::from_stream` is yield-once — `BidiStreamSource` would be cleaner (OQ-CH-13, confirmed +EV)
|
||||
|
||||
The POC validates the yield-once path is sufficient, as the plan predicted.
|
||||
But wiring `ChannelEndpoint::open_echo_channel` made the awkwardness concrete:
|
||||
each channel constructs a fresh `Connection::from_stream` that yields one bidi
|
||||
stream, and the endpoint holds a bag of these connections (one per channel)
|
||||
rather than a single `ChannelConnection` that yields N streams. The
|
||||
`BidiStreamSource` trait proposed in OQ-CH-13 would make `ChannelConnection`
|
||||
a first-class peer of QUIC (many bidi streams) instead of a bag of yield-once
|
||||
connections:
|
||||
|
||||
```rust
|
||||
trait BidiStreamSource: Send + Sync {
|
||||
async fn accept_bi(&self) -> Result<(SendStream, RecvStream), StreamError>;
|
||||
async fn open_bi(&self) -> Result<(SendStream, RecvStream), StreamError>;
|
||||
}
|
||||
```
|
||||
|
||||
with `Connection` holding `Box<dyn BidiStreamSource>`, and QUIC/Iroh/Stream/
|
||||
Channels all implementing it. The POC confirms this is **additive** (existing
|
||||
callers keep working via a `from_stream`-backed default impl) and would
|
||||
clean up both the channels layer and the client-side endpoint (OQ-CH-14).
|
||||
**Recommendation: do this refactor.** It is not a major/pita break and it
|
||||
makes downstream substantially cleaner.
|
||||
|
||||
#### 2. `Connection::close` has unused params (`code`, `reason`) for the stream backend
|
||||
|
||||
`crates/alknet-core/src/types.rs:500` — the `Stream` backend of `Connection::close`
|
||||
takes `code: u32, reason: &str` and does nothing with them (clippy flags both
|
||||
as unused). The stream backend just drops the inner stream. This is a leak of
|
||||
the QUIC-centric `close(code, reason)` shape into a backend that has no such
|
||||
concept. The `BidiStreamSource` refactor is the natural place to give the
|
||||
stream backend a `close()` that doesn't take QUIC-shaped args, or to make
|
||||
the args `Option`-al / ignored-with-a-warning. Low priority but worth fixing
|
||||
while the trait is open.
|
||||
|
||||
#### 3. `AuthContext` construction is verbose for tests and POCs
|
||||
|
||||
Every POC handler test constructs an `AuthContext` literal with four `None`
|
||||
fields and a hardcoded ALPN. The real assembly layer gets one from the
|
||||
endpoint; POCs and tests repeat the boilerplate. A
|
||||
`AuthContext::test(alpn: &[u8])` or `AuthContext::anonymous(alpn)` helper in
|
||||
`alknet-core` (behind a `test-utils` feature, or just a `pub fn` if we don't
|
||||
mind it in the public API) would remove this. Small, but it recurs in every
|
||||
handler POC.
|
||||
|
||||
### In `alknet-channels` (the spec / Phase 1)
|
||||
|
||||
#### 4. `MpscSendStream::poll_shutdown` must emit a zero-length sentinel
|
||||
|
||||
The POC's `MpscSendStream::poll_shutdown` sends an empty `Bytes` (the EOF
|
||||
sentinel) before dropping the sender. Without this, the demux never sees EOF
|
||||
on the channel's `stream_type`, and `tokio::io::copy` in the handler never
|
||||
completes — the test hangs. The TTY crate's `pump_session` emits the
|
||||
zero-length stdout sentinel explicitly via `Chunk::stdout(Bytes::new())`;
|
||||
the channels layer's per-channel write pump does NOT forward a sentinel on
|
||||
sender-drop, so the send adapter must do it.
|
||||
|
||||
**Implication for Phase 1:** the `ChannelConnection` write-half contract
|
||||
must specify that `AsyncWrite::shutdown` (or the `BidiStreamSource`
|
||||
equivalent) emits a zero-length sentinel so the peer sees EOF. This is a
|
||||
wire-level invariant, not just an implementation detail — both sides must
|
||||
agree, or channels will hang on clean shutdown. The TTY crate already
|
||||
follows this convention; the channels crate should codify it.
|
||||
|
||||
#### 5. The mux needs dynamic registration (handle/runner split)
|
||||
|
||||
The plan's `Mux::run(self, transport)` shape (consume the mux, run pumps for
|
||||
pre-registered channels) does not compose with the "open a channel after the
|
||||
run loop started" API that `ChannelEndpoint::open_echo_channel` needs. The
|
||||
POC split `Mux` into `MuxHandle` (clone-able, `register(channel_id,
|
||||
stream_type) -> Sender<Bytes>` at any time) and `MuxRunner` (owns the
|
||||
transport, `select!`s on new-pump registrations). This is the shape Phase 1
|
||||
should adopt — the alternative (pre-registering all channels before run)
|
||||
doesn't match the dynamic `channel/open` model.
|
||||
|
||||
The split adds one `mpsc::UnboundedSender` + `Arc<Mutex<HashMap>>` per mux,
|
||||
which is cheap. The runner's `select!` loop exits when all `MuxHandle` clones
|
||||
drop (the `new_pumps` sender closes), which is the natural shutdown signal.
|
||||
|
||||
#### 6. The demux must drop all channel senders on transport EOF
|
||||
|
||||
`Demux::run` clears its `channels` map on exit (transport closed) so every
|
||||
handler's `MpscRecvStream` sees EOF even without an explicit zero-length
|
||||
sentinel arriving on the wire. Without this, `read_to_end` / `tokio::io::copy`
|
||||
in handlers hangs forever waiting for a sender that never drops because the
|
||||
demux task is holding the map. This is a teardown invariant: transport close
|
||||
→ all channel senders drop → all handlers see EOF → all handler tasks exit.
|
||||
Phase 1 should specify this as part of the `ChannelsAdapter::handle` contract.
|
||||
|
||||
#### 7. The tunnel's two-pump shape needs explicit shutdown-on-completion
|
||||
|
||||
`tokio::try_join!(c2t, t2c)` deadlocks for the tunnel: each pump waits for the
|
||||
other's EOF, which only comes once the *opposite* pump completes and shuts
|
||||
down its sink. The fix (shut down the peer's sink when one pump completes) is
|
||||
small but easy to get wrong. The TTY adapter doesn't have this problem
|
||||
because its three pumps coordinate via the `exit_code` future, which is a
|
||||
third signal. The tunnel has no such signal — it's purely pump-driven.
|
||||
|
||||
**Implication for Phase 1:** the tunnel handler (and any future handler
|
||||
with a pump-driven two-direction shape) must shut down the opposite sink on
|
||||
pump completion, not just `try_join` the two pumps. This is worth a
|
||||
documented pattern in the channels spec, or — if `BidiStreamSource` lands —
|
||||
a helper in `alknet-core` that encapsulates the "two-pump with
|
||||
shutdown-on-completion" shape so handlers don't reimplement it. The TTY
|
||||
crate's `pump_session` is the three-pump version; the two-pump version is
|
||||
the tunnel's shape and will recur (e.g. an SSH `direct-tcpip` channel is
|
||||
the same two-pump shape).
|
||||
|
||||
### Cosmetic / clippy
|
||||
|
||||
#### 8. "Very complex type" for the `reserve_owned` future
|
||||
|
||||
`MpscSendStream` stores an in-flight `reserve_owned()` future for
|
||||
backpressure. The concrete future type is anonymous (async fn), so it's
|
||||
boxed as `Pin<Box<dyn Future<Output = Result<OwnedPermit<Bytes>, SendError<()>>> + Send>>`.
|
||||
Clippy flags this as "very complex type." The POC factored it into a
|
||||
`type ReserveFut = ...` alias, which silences clippy but doesn't reduce the
|
||||
complexity. The clean fix is `tokio_util::io::PollSender`-style helper that
|
||||
wraps an `mpsc::Sender<T>` as `AsyncWrite` for `T: Into<Bytes>` — but that
|
||||
requires `tokio-util` as a dep and a small adapter. Phase 1 should consider
|
||||
whether to extract this adapter (it's ~50 lines and will recur in any
|
||||
mpsc-backed stream) or keep it POC-local. Low priority.
|
||||
|
||||
---
|
||||
|
||||
## What the POC Does NOT Validate
|
||||
|
||||
Following the docker POC summary's pattern:
|
||||
|
||||
1. **The call protocol.** `channel/open`, `channel/close`, `channel/control`,
|
||||
`channel/resources` are call-protocol operations. The POC uses a POC-local
|
||||
channel-allocation mechanism (`Demux::allocate_channel` /
|
||||
`MuxHandle::register`), not the real `OperationRegistry` path. The call
|
||||
protocol is already in production; its integration with channels is Phase 1's
|
||||
concern, not a POC unknown.
|
||||
2. **Real transport.** `tokio::io::duplex` stands in for QUIC/TCP/WebTransport.
|
||||
The transport-generalization work already validated `Connection::from_stream`
|
||||
over real transports; the POC reuses that.
|
||||
3. **ACL.** The call protocol's `AccessControl::check` gates `channel/open`
|
||||
in the real system; the POC has no auth.
|
||||
4. **Real adapters.** `EchoHandler` and `TunnelHandler` are POC-local stubs.
|
||||
The real `TtyAdapter` / `SshAdapter` / `DockerTtyBackend` are unchanged and
|
||||
integrate in Phase 1.
|
||||
5. **Recursive composition.** `alknet/channels` inside `alknet/channels` is a
|
||||
natural consequence of the `Connection` abstraction but is not a POC goal.
|
||||
6. **Hub relay.** The stretch goal (two `Demux`/`Mux` pairs bridged by a byte
|
||||
pump with `channel_id` remapping, OQ-CH-11) was not built — the three primary
|
||||
targets were the higher-leverage unknowns. The POC's demux/mux shape would
|
||||
support it, but the relay sketch is left for Phase 1.
|
||||
7. **WASM test harness.** The sync core compiles under
|
||||
`wasm32-unknown-unknown`; running the same tests in a WASM test harness
|
||||
(`wasm-bindgen-test`) was the secondary stretch and was not set up. The
|
||||
compile check validates the "no platform dependencies" claim for the core;
|
||||
the async shell and `alknet-core` dep graph are not WASM-clean yet (transitive
|
||||
`getrandom`/`rand`), which is a Phase 1 concern.
|
||||
|
||||
---
|
||||
|
||||
## Test Coverage
|
||||
|
||||
```
|
||||
running 28 tests
|
||||
test wire::tests::parse_max_length ... ok
|
||||
test wire::tests::parse_preserves_channel_id_max ... ok
|
||||
test wire::tests::parse_round_trip ... ok
|
||||
test wire::tests::parse_too_large ... ok
|
||||
test wire::tests::parse_zero_length ... ok
|
||||
test mpsc_stream::tests::recv_dropped_sender_is_eof ... ok
|
||||
test mpsc_stream::tests::recv_partial_then_leftover ... ok
|
||||
test mpsc_stream::tests::recv_reads_bytes_in_order ... ok
|
||||
test mpsc_stream::tests::recv_zero_length_sentinel_is_eof ... ok
|
||||
test mpsc_stream::tests::send_after_close_errors_broken_pipe ... ok
|
||||
test mpsc_stream::tests::send_backpressure_pends_then_completes ... ok
|
||||
test mpsc_stream::tests::send_writes_then_shutdown_closes ... ok
|
||||
test demux::tests::demux_chunk_too_large_does_not_panic ... ok
|
||||
test demux::tests::demux_routes_to_allocated_channel ... ok
|
||||
test demux::tests::demux_three_concurrent_channels_no_cross_contamination ... ok
|
||||
test demux::tests::demux_unknown_channel_drops_lenient ... ok
|
||||
test demux::tests::demux_zero_length_sentinel_delivered ... ok
|
||||
test mux::tests::mux_demux_round_trip_three_concurrent_channels ... ok
|
||||
test mux::tests::mux_frames_single_chunk_round_trip ... ok
|
||||
test mux::tests::mux_zero_length_sentinel_round_trips ... ok
|
||||
test echo_handler::tests::echo_single_channel ... ok
|
||||
test echo_handler::tests::echo_single_channel_1kib ... ok
|
||||
test echo_handler::tests::echo_three_concurrent_channels ... ok
|
||||
test echo_handler::tests::handler_loops_accept_bi_gets_one_session ... ok
|
||||
test echo_handler::tests::handler_sees_alpn ... ok
|
||||
test tunnel_handler::tests::tunnel_concurrent_with_echo_channel ... ok
|
||||
test tunnel_handler::tests::tunnel_echo_round_trip ... ok
|
||||
test tunnel_handler::tests::tunnel_large_payload ... ok
|
||||
|
||||
test result: ok. 28 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
|
||||
```
|
||||
|
||||
The 1 MiB `tunnel_large_payload` test exercises the bounded-buffer
|
||||
backpressure path end-to-end (channel writer faster than TCP echo server,
|
||||
no deadlock). The three `echo_*` tests validate the full
|
||||
demux→Connection→handler→mux path. The five `wire::*` tests are pure sync
|
||||
core, WASM-portable.
|
||||
|
||||
---
|
||||
|
||||
## POC Structure
|
||||
|
||||
```
|
||||
alknet-channels-poc/
|
||||
Cargo.toml — depends on alknet-core (path, no default features), tokio, tokio-util, bytes, async-trait, thiserror, tracing
|
||||
src/
|
||||
lib.rs — module docs; the three-step POC overview
|
||||
wire.rs — sync core: 9-byte ChunkHeader, parse_header, write_header (WASM-clean)
|
||||
mpsc_stream.rs — MpscRecvStream (AsyncRead), MpscSendStream (AsyncWrite + backpressure + sentinel-on-shutdown)
|
||||
demux.rs — Demux: route chunks to per-(channel,stream_type) bounded mpsc senders; lenient on unknown ids; drop senders on EOF
|
||||
mux.rs — MuxHandle/MuxRunner: dynamic per-channel write pumps; frames Bytes onto the shared transport
|
||||
echo_handler.rs — EchoHandler (ProtocolHandler) + ChannelEndpoint (POC-local client/server wiring) + open_echo_channel
|
||||
tunnel_handler.rs — TunnelHandler (two-pump TcpStream proxy) + tcp echo server test helper
|
||||
```
|
||||
|
||||
No `tests/` directory — tests are inline per-module (`#[cfg(test)] mod tests`),
|
||||
matching the alknet-core / alknet-tty convention (vs. the docker POC's
|
||||
separate `tests/integration.rs`, which matched bollard's style).
|
||||
|
||||
---
|
||||
|
||||
## Key Code-to-Concept Mappings
|
||||
|
||||
| POC concept | alknet-core equivalent | alknet-tty equivalent |
|
||||
|---|---|---|
|
||||
| `wire::parse_header`/`write_header` | — | `wire::ChunkReader::read_chunk` / `ChunkWriter::write_chunk` (5-byte, no `channel_id`) |
|
||||
| `MpscRecvStream` (`AsyncRead`) | backs `RecvStream::from_stream` | the channel-bridge adapter in the TTY POC |
|
||||
| `MpscSendStream` (`AsyncWrite`) | backs `SendStream::from_stream` | `TestStdinSink` in TTY adapter tests |
|
||||
| `Demux` | — | (new — TTY has no per-channel demux; it's single-channel) |
|
||||
| `MuxHandle`/`MuxRunner` | — | (new — TTY has `ChunkWriter` directly, no mux) |
|
||||
| `ChannelEndpoint` | the symmetric client/server types (OQ-CH-14) | — |
|
||||
| `Connection::from_stream(send, recv, alpn, addr)` | `types.rs:405` | `TtyAdapter::handle` receives a `Connection` the same way |
|
||||
| `EchoHandler::handle` | `ProtocolHandler::handle` | `TtyAdapter::handle` (loops `accept_bi`) |
|
||||
| `TunnelHandler::handle` two pumps | — | `pump_session` (three pumps — stdout/stderr + client→backend + exit) |
|
||||
| zero-length sentinel = EOF | — | `wire.rs` §Sentinels (ADR-052) |
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- POC plan: `docs/research/alknet-channels/poc-plan.md` — the detailed
|
||||
de-risk POC plan this summary reports against.
|
||||
- Phase 0 findings: `docs/research/alknet-channels/phase-0-findings.md` — the
|
||||
research doc this POC derisks (OQ-CH-12/13/14 all surfaced there).
|
||||
- TTY wire format: `crates/alknet-tty/src/wire.rs` — the 5-byte
|
||||
`ChunkReader`/`ChunkWriter` this POC generalizes to 9 bytes.
|
||||
- TTY adapter: `crates/alknet-tty/src/adapter.rs` — `TtyAdapter::handle` and
|
||||
`drive_session`/`pump_session` (the per-stream dispatch and three-pump
|
||||
bidirectional pattern the tunnel handler reuses with two pumps).
|
||||
- Core types: `crates/alknet-core/src/types.rs` — `Connection::from_stream`
|
||||
(`:405`), `SendStream::from_stream` (`:267`), `RecvStream::from_stream`
|
||||
(`:289`), `ProtocolHandler` (`:220`) — the integration points the POC
|
||||
validates.
|
||||
- Docker POC summary: `docs/research/alknet-docker/poc-summary.md` — the
|
||||
POC summary this doc mirrors in structure and tone.
|
||||
- TTY POC: `/workspace/alknet-tty-poc/` — the POC convention this POC follows
|
||||
(sibling-of-`@alkdev` location, standalone Cargo crate, inline tests).
|
||||
Reference in new issue
Block a user