alkcall/docs/architecture/channel-client.md

status, last_updated

status	last_updated
draft	2026-07-18

channel-client.md — ChannelClient

The client side of a channels connection. ADR-043 is the decision; this doc specifies the API.

What

ChannelClient is the symmetric counterpart to ChannelsAdapter (ADR-039). The server side is a ProtocolHandler (ChannelsAdapter::handle); the client side takes over an established transport Connection, runs the demux/mux, and exposes open_channel(alpn, params) -> Channel to the application.

This is the channels analogue of CallClient (server: CallAdapter; client: CallClient) in the call protocol.

API

pub struct ChannelClient {
    manager: ChannelManager,
    // The transport-side demux/mux, running in a background task.
    ...
}

impl ChannelClient {
    /// Construct a `ChannelClient` over a pre-established transport
    /// `Connection` on ALPN `alknet/channels`. This is the
    /// transport-agnostic primary constructor: the caller (or a
    /// transport-specific dial helper) produces the `Connection` —
    /// via `Connection::from_bidi` (TCP+TLS, WebTransport, SSH
    /// `direct-tcpip`), a quinn connection, or any other `AsyncRead +
    /// AsyncWrite` source — and this method takes over: installs
    /// channel 0 (`alknet/call`), spawns the demux/mux, and returns
    /// the client. Mirrors the server side's transport-agnostic
    /// `ChannelsAdapter::handle(Connection)` and
    /// `CallClient::spawn_dispatch(Connection)`.
    ///
    /// This is the one-way-door API surface (ADR-043). It must not be
    /// coupled to a transport — the channels protocol is
    /// transport-agnostic (ADR-034, as amended by ADR-035; ADR-007,
    /// ADR-009), and the client side is half of that protocol.
    pub async fn from_connection(connection: Connection)
        -> Result<Self, ChannelError>;

    /// Open a data channel with the given ALPN and params. Sends
    /// `channel/open` on channel 0, waits for the response, and returns
    /// the channel.
    pub async fn open_channel(
        &self,
        alpn: &str,
        params: Value,
        direction: ChannelDirection,
    ) -> Result<Channel, ChannelError>;

    /// Subscribe to the peer's resource updates. Returns a stream of
    /// resource-set events (ADR-037 channel/resources/subscribe). Each
    /// event carries the JSON `output.resources` array from ADR-037's
    /// `channel/resources/subscribe` response shape.
    pub async fn subscribe_resources(&self)
        -> Result<BoxStream<ResourceEvent>, ChannelError>;

    /// The call-protocol connection on channel 0, for invoking channel
    /// lifecycle operations and any other call ops the peer exposes.
    pub fn call(&self) -> &CallConnection;
}

pub enum ChannelDirection {
    InitiatorToResponder,
    ResponderToInitiator,
}

pub struct Channel {
    pub channel_id: u32,
    /// The channel's BiStream, accessible via the BidiStreamSource
    /// (accept_bi — ADR-038 as amended by ADR-035).
    pub source: ChannelBidiStreamSource,
}

/// One event from `channel/resources/subscribe`. Wraps the JSON `output`
/// object from ADR-037's subscribe response — the `resources` array
/// describing what ALPNs the peer exposes and with what `access` preview.
/// The channels crate maps the JSON to this typed struct; the fields mirror
/// ADR-037's response shape.
pub struct ResourceEvent {
    pub resources: Vec<ResourceEntry>,
}

pub struct ResourceEntry {
    pub alpn: String,
    pub backends_or_targets: Vec<String>, // ALPN-specific enumeration
    pub access: Value,                     // preview of AccessControl (advisory)
}

Transport-agnostic by construction

ChannelClient is the client side of the channels protocol. The channels protocol is transport-agnostic (ADR-034 substrate modes, as amended by ADR-035; Connection::from_bidi/from_source from ADR-007/070/092 take any AsyncRead + AsyncWrite). The client side must not be welded to a transport — that would repeat the server-side welding ADR-007 explicitly unwound.

from_connection(connection: Connection) is the primary constructor and the one-way-door API surface. It takes a pre-established Connection and takes over channels establishment. The transport is the caller's concern: Connection::from_bidi(tls_stream, ...) for TCP+TLS, a quinn Connection, a WebTransport BiStream, an SSH direct-tcpip channel wrapped via from_bidi, a WebSocket carrying alknet/channels (the browser path per ADR-044) — all produce a Connection that from_connection accepts unchanged. This mirrors the server side's ChannelsAdapter::handle(Connection), which is substrate-agnostic by the same mechanism.

The dial (QUIC, TCP+TLS, iroh) lives in AlknetClient (alknet-client, ADR-045), not on ChannelClient. Callers compose AlknetClient::dial_quic(...).await? + ChannelClient::from_connection(conn).await? — two lines, the dial then the take-over. Keeping the dial off ChannelClient avoids alknet-channels-call depending on alknet-client; the protocol crates are parallel to the dial, not downstream of it.

The credential/verifier-selection rule (ADR-034) lives in the dial (AlknetClient), not in from_connection — from_connection receives an already-established, already-authenticated Connection, exactly as ChannelsAdapter::handle does on the server side.

Bidirectionality preserved

The channels protocol is bidirectional — either side can open a channel (ADR-037 §direction semantics). ChannelClient::open_channel supports both ChannelDirection::InitiatorToResponder and ChannelDirection::ResponderToInitiator. The client is not "the client side" in the request/response sense — it can also receive channel/open requests from the peer (the peer initiates, the client's ChannelManager responds). This mirrors the call protocol's operation overlay (each side populates what operations they expose).

ChannelClient is one endpoint of a bidirectional channels connection. The name follows the CallClient convention (the side that dialed), not a request/response role.

Relationship to AlknetClient

ChannelClient's API is transport-agnostic — from_connection takes a pre-established Connection. The shared dial+TLS seam (AlknetClient, OQ-55) is alknet-client, which provides AlknetClient with three dial methods (dial_quic / dial_tcp_tls / dial_iroh), each producing a Connection that from_connection consumes. The dial is transport-specific (QUIC, TCP+TLS, iroh); the take-over (from_connection) is transport-agnostic. The two concerns are separated.

AlknetClient::dial_quic is the dial that feeds from_connection. A caller that needs transport selection (QUIC with TCP+TLS fallback) uses AlknetClient directly; the fallback policy is a caller concern. See ADR-045 for the full decision and OQ-55 (resolved).

Design Decisions

All design decisions are documented as ADRs in decisions/.

ADR	Decision	Summary
080	ChannelClient	Client side; transport-agnostic from_connection primary; dial lives in AlknetClient (ADR-045, resolves OQ-55)
093	channels Pure Channel Multiplexing	No stream_types on open_channel/Channel; handler owns sub-stream multiplexing

Open Questions

• OQ-55 (resolved by ADR-045): AlknetClient core dial+TLS seam — alknet-client with three dial methods. ChannelClient's API is transport-agnostic (from_connection); the dial is the shared seam. See ADR-045.

References

• ADR-043: ChannelClient (the decision)
• ADR-035: channels pure channel multiplexing (no stream_types)
• ADR-037: channel lifecycle operations (open_channel sends channel/open)
• ADR-038: ChannelBidiStreamSource (what Channel.source wraps, as amended by ADR-035 — accept_bi yields a BiStream)
• ADR-039: ChannelManager (the shared state ChannelClient holds)
• OQ-55: AlknetClient / client establishment extraction
• docs/architecture/crates/call/client-and-adapters.md — CallClient (the shape ChannelClient mirrors)