alkdev/alknet

0 Fork 0

Files

T

glm-5.2 7610ec1f31 docs(arch): workspace scope correction (ADR-085) + tls spec review fixes

ADR-085 records the actual workspace scope: the mono-repo is the core
networking toolkit (substrate: core, tls, call, channels; deployment
shapes: hub, worker; foundational handlers: tty, http, ssh, tunnel,
socks5, fs, sftp; vault). Consumer repos (docker, agent) are separate
repos depending on the published core crates. The overview's crate
graph had been describing the wrong scope since ADR-003 — a flat
~12-crate workspace including DNS/messaging/NAPI while omitting
channels, hub, worker, and tls. This stale scope was a causal factor
in the 'assembly layer' hedging pattern: when the overview implies
everything lives in one repo but the architecture needs a hub/worker
composition layer not in the graph, the gap gets filled with
'assembly layer' as an escape hatch. The overview is rewritten to
match the real boundary.

TLS spec review fixes (from architecture review):
- C3: hub/worker/hub-worker terminology pointers (tls README + endpoint.md)
- W1: server-only statement + OQ-64 (client-side TLS helper, deferred)
- W2: ACME task lifecycle semantics (returns immediately, no first-cert await)
- W3: remove stale EndpointError::TlsConfig variant
- W4: update stale ALPN section for two-config hub
- W5: add alknet-tls to hub dep graph (assembly-layer dep)
- W6: trim inline rationale -> point to ADR-084
- W7: ADR-084 status dependency note

New open questions:
- OQ-62: ALPN list sharing for two-config hub (open, high)
- OQ-63: TlsError shape (open, high)
- OQ-64: client-side TLS helper (deferred, blocked on OQ-55)

2026-07-14 12:46:16 +00:00

2.8 KiB

Raw Blame History

OQ-63: `TlsError` Shape

Origin: docs/architecture/crates/tls/README.md (TlsError is referenced as the Result error type in TlsServerConfig::new, for_quinn(), and the crate's public signatures, but is never sketched or defined); ADR-082 (same — TlsError in signatures, no shape).
Status: open
Door type: one-way (the error type is the public API surface of alknet-tls; changing it after consumers exist is a breaking change to every assembly-layer call site)
Priority: high (an implementer cannot write the crate without deciding this; guessing produces divergent shapes — one thin rustls::Error wrapper vs a 10-variant enum with per-path context)
Resolution: Not yet decided. The shape needs to cover the failure modes across all four identity paths:
- Cert/key loading (X509: file read + PEM parse; SelfSigned: rcgen generation) — currently io::Error-wrapped in the core code.
- rustls config construction (builder_with_provider / with_safe_default_protocol_versions / with_single_cert / with_cert_resolver) — currently rustls::Error-wrapped.
- quinn wrap (QuicServerConfig::try_from(rustls::ServerConfig)) — the one path where for_quinn() can fail; currently io::Error::other(e)-wrapped.
- ACME — rustls-acme has its own error types; the ACME task runs in the background and surfaces errors via events (logged, not returned from new), so new's ACME path may only need to cover "ACME feature not enabled but TlsIdentity::Acme configured" (currently an io::ErrorKind::Unsupported).
The open question is the granularity: a single TlsError enum with variants per failure category (cert-load, rustls-build, quinn-wrap, acme-disabled) vs a thin wrapper around rustls::Error / io::Error. The single-enum shape gives callers matchable context (the assembly layer can distinguish "cert file missing" from "quinn rejected the rustls config"); the thin wrapper is less code but loses the distinction. This is an API-surface decision — it needs an ADR or at minimum a sketch in the TLS README before implementation.

Subsidiary question: does TlsError live in alknet-tls (owned by the crate that produces it) or is it re-exported from alknet-core? Likely alknet-tls (it's the crate's own error), but worth confirming so alknet-core's EndpointError (which no longer has a TlsConfig variant after ADR-083) doesn't need to know about it.
Cross-references: ADR-082 (the extraction that introduces TlsError), ADR-083 (the endpoint refactor that removes EndpointError::TlsConfig, making TlsError the sole TLS error surface), crates/alknet-core/src/endpoint.rs (the current io::Error-wrapping pattern the new type replaces)

2.8 KiB Raw Blame History

OQ-63: TlsError Shape

2.8 KiB

Raw Blame History

OQ-63: `TlsError` Shape