alkdev/alknet

0 Fork 0

Files

T

glm-5.2 ce7de57973 docs(arch): AlknetClient native dial seam — resolves OQ-55 (ADR-089)

Extract the deferred AlknetClient as a new crate alknet-client — the
client-side analogue of AlknetEndpoint. Three dial methods (QUIC +
TCP+TLS via TlsClientConfig, iroh via key) produce a Connection for
CallClient::spawn_dispatch / ChannelClient::from_connection to consume.
The deferral collapsed because ADR-086 gave the native endpoint type
three dial shapes within one endpoint type, ADR-087 broke the circular
hedge, and ADR-083 gave the server-side shape to mirror by symmetry.

Names the three concept layers that were tangled throughout the initial
development (deployment role / establishment side / ALPN-level category)
so the fix is legible. Names alknet/register as a dialable entry-point
ALPN (native registration, parallel to HTTP registration in OQ-58); its
wire protocol is deferred to OQ-66 (blocked on OQ-58's token model).

Cross-references updated across 11 existing docs (README, overview,
open-questions, OQ-55, tls, hub, core, channels README/overview/
channel-client, call client-and-adapters) to reflect OQ-55 resolved and
the new alknet-client crate. Architecture review passed (2 critical, 7
warnings — all addressed).

2026-07-15 12:50:13 +00:00

3.4 KiB

Raw Blame History

OQ-55: AlknetClient / Client Establishment Extraction

Origin: docs/research/alknet-channels/phase-0-findings.md OQ-CH-14 (the AlknetClient clarification); docs/research/alknet-channels/poc-summary.md §"Issues Surfaced" #1 (the BidiStreamSource finding that motivates separating the client-extraction question from the Connection extension question).
Status: resolved (ADR-089)
Door type: one-way (crate existence + dial seam — ADR-089)
Priority: medium
Resolution: AlknetClient is extracted as a new crate alknet-client — the client-side analogue of AlknetEndpoint (ADR-083). Three dial methods: dial_quic / dial_tcp_tls (both build a TlsClientConfig via ADR-087 and call their transport's connector) + dial_iroh (the key-not-config exception, shares the Ed25519SecretKey). The dial produces a Connection for the protocol take-overs (CallClient::spawn_dispatch, ChannelClient::from_connection) to consume — it does not run protocols.
Why the deferral collapsed: the blocking condition ("a second transport's real dial existing") is met within the native endpoint type (ADR-086): QUIC + TCP+TLS (both rustls-consuming via TlsClientConfig) + iroh (key-based) — three dial shapes, two sharing TlsClientConfig. ADR-087 broke the circular hedge (TlsClientConfig is a prerequisite, not a consequence of the dial). ADR-083 made the server-side shape a clean accept-loop runner, giving the client-side shape by symmetry. The dial seam is extractable from two different transport implementations, not guessable from one.
Scope of the resolution: the native transport-polymorphic dial. The web/browser client (WebSocket, HTTP — the browser bidirectional path per ADR-044/048) was never what this OQ was about — it is a different client surface (the JS SDK / wasm), not a Rust dial, and does not use AlknetClient. Non-Rust native clients (Node/Deno/Bun, Python, wasm) that negotiate TLS against an X.509 endpoint and implement the wire protocols directly are also out of scope — AlknetClient is the Rust native client, one of several possible native clients sharing the same wire protocols.
What does NOT block on this (unchanged): each crate building its own client standalone with a shared TlsClientConfig (ADR-087), and each transport-specific dial helper. CallClient's transport-agnostic take-over (spawn_dispatch) and ChannelClient's transport-agnostic take-over (from_connection, ADR-080) are decided; the existing connect / connect_quic convenience constructors become thin wrappers over AlknetClient::dial_quic (ADR-089 §5).
Cross-references: ADR-089 (the resolution — AlknetClient native dial seam), ADR-083 (the server-side shape mirrored), ADR-086 (endpoint types — native has QUIC + TCP+TLS + iroh), ADR-087 (TlsClientConfig — the prerequisite the dial consumes), ADR-034 (verifier selection — centralized in TlsClientConfig::new), ADR-065 (server-side transport generalization — the client-side analogue this OQ's deferral avoided preempting, now completed), ADR-070 (the BidiStreamSource extension point — orthogonal to the client establishment question), OQ-CH-14 in docs/research/alknet-channels/phase-0-findings.md (the research-scope question this core-scope OQ carried forward).

3.4 KiB Raw Blame History

OQ-55: AlknetClient / Client Establishment Extraction

3.4 KiB

Raw Blame History