alkdev/alknet

0 Fork 0

Files

T

glm-5.2 2abe8f1872 docs(arch): TCP+TLS as first-class owned transport — resolves OQ-60, dissolves OQ-61

ADR-083 revised: TCP+TLS moves from an external sibling loop calling
public dispatch to a first-class owned transport via
with_tcp_tls(listener, acceptor), running inside run() alongside the
quinn and iroh accept loops. The endpoint owns all its accept loops;
shutdown() stops them all. The multi-owner shutdown problem (OQ-61)
does not arise — dissolved.

The reason TCP+TLS was structurally excluded (ADR-010 Am. 1: the
endpoint built transports internally, TCP+TLS couldn't fit) is gone
after ADR-083 — the endpoint no longer builds transports; it runs
accept loops on whatever it's given. TCP+TLS is a listener transport,
same shape as quinn and iroh. ADR-010 Amendment 2 supersedes Am. 1's
struct-level exclusion.

dispatch stays public — but for genuinely external shapes (SSH channels,
future WebTransport streams), which are connection-internal multiplexing,
not listener transports. The listener-vs-multiplexing distinction is now
explicit.

OQ-60 resolved: the TCP+TLS loop lives in alknet-core behind a tcp
feature (owned by the endpoint); builder functions are inlined by the
assembly layer. A alknet-transport crate was rejected — it would contain
only trivial builders; the real component (the loop) is in core. Hub-
specific composition lives in the hub crate; transport runtimes that any
node might need live in core.

Updated: ADR-010 (Amendment 2), ADR-082 (TCP+TLS loop location), ADR-083
(revised), core/endpoint.md (struct + dispatch + shutdown), hub/README.md
(transport table + assembly example + stale sibling references),
tls/README.md (endpoint section + TCP+TLS loop location + references),
open-questions.md (OQ-60 resolved, OQ-61 dissolved).

Review: zero critical issues, five warnings fixed (stale hub README
prose, stale core endpoint.md struct/dispatch listings, stale ADR-082
TCP+TLS loop location, stale TLS README reference entry, hub front-matter
date).

2026-07-14 08:58:50 +00:00

1.5 KiB

Raw Blame History

OQ-61: Multi-Owner Shutdown Coordination

Origin: docs/architecture/decisions/083-endpoint-as-accept-loop-runner.md (the endpoint owns dispatched handlers; the assembly layer owns spawned accept loops — coordination between them on shutdown was unspecified).
Status: dissolved
Door type: two-way (the coordination mechanism was an implementation detail)
Priority: medium
Resolution: Dissolved by ADR-083 revision (2026-07-14). The problem this OQ tracked — coordinating shutdown between the endpoint's owned loops and external TCP+TLS accept loops — does not arise. The TCP+TLS accept loop is now an owned transport (via with_tcp_tls), not an external sibling. The endpoint owns all its accept loops (quinn, iroh, TCP+TLS); shutdown() stops them all and drains all dispatched handlers. One owner, one shutdown. The dispatch method stays public for SSH channels and future WebTransport streams, but those are connection-internal multiplexing callers, not listener loops with independent shutdown needs — they call dispatch on connections the endpoint already accepted and dispatched a handler for.

The premise of this OQ (external TCP+TLS loop + endpoint-owned dispatch = multi-owner shutdown) was a consequence of TCP+TLS being external. ADR-083's revision made TCP+TLS internal, retiring the premise.
Cross-references: ADR-083 (endpoint refactor — TCP+TLS is now owned), OQ-60 (resolved — the TCP+TLS loop lives in core)

1.5 KiB Raw Blame History

OQ-61: Multi-Owner Shutdown Coordination

1.5 KiB

Raw Blame History