alktls/docs/architecture/decisions/002-tlserror-shape.md

status, last_updated

status	last_updated
accepted	2026-09-10

ADR-002: TlsError — the ADR-088 six-variant shape from day one

Status

Accepted (2026-09-10)

Context

The extracted code (crates/alknet-tls/src/lib.rs) carries a simplified 3-variant TlsError: Config(String), Io(io::Error), Cert(String). alknet ADR-088 recorded the target shape — a single #[non_exhaustive] enum, one variant per failure category, typed #[from] sources — but it was never implemented; the extracted code folds every typed failure into Config(e.to_string()) strings, losing the #[source] chain and the category distinction.

Phase 0 identified this as gap #1, the highest-value gap closure: this crate is pre-consumer, so the enum shape is still a two-way door; once the alknet rewrite consumes it, it is one-way.

Two mechanics from ADR-088's "Gotchas" needed verification before pinning the shape:

• CertLoad's #[from] io::Error relies on rustls_pemfile funnelling its own non-std::error::Error error type into io::Error. Confirmed at the pinned versions: rustls_pemfile 2.x returns Result<T, io::Error> from its iterator and read APIs (certs, private_key), so PEM parse failures surface as io::Error — the CertLoad(#[from] io::Error) variant is sound.
• VerifierBuild wraps rustls::webpki::VerifierBuilderError (confirmed present in rustls 0.23.44: NoRootAnchors + InvalidCrl(CertRevocationListError), #[non_exhaustive]). With the ADR-088 §5 root-store fallback in place, NoRootAnchors is unreachable in practice — the variant exists for the builder API's completeness, not a reachable failure path.

Decision

TlsError ships as the alknet ADR-088 shape, unmodified:

#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum TlsError {
    /// Cert or key file read / PEM parse. `rustls_pemfile` funnels its
    /// own error type into `io::Error`, so one `io::Error` source covers
    /// the whole loading path.
    #[error("loading cert/key material: {0}")]
    CertLoad(#[from] std::io::Error),

    /// Self-signed cert generation (rcgen). Server `SelfSigned` path.
    #[error("generating self-signed cert: {0}")]
    SelfSigned(#[from] rcgen::Error),

    /// rustls server or client config construction
    /// (`with_safe_default_protocol_versions`, `with_single_cert`,
    /// `CertifiedKey::from_der`, `RootCertStore::add`).
    #[error("building rustls config: {0}")]
    Rustls(#[from] rustls::Error),

    /// `WebPkiServerVerifier::builder(_with_provider)..build()` — the
    /// unknown-X.509-remote client path. Re-exported by rustls at
    /// `rustls::client` (the `rustls::webpki` module is private at the
    /// pinned 0.23.44; same type, public path).
    #[error("building webpki verifier: {0}")]
    VerifierBuild(#[from] rustls::client::VerifierBuilderError),

    /// QUIC config wrapping — the one path where `for_noq()` fails
    /// (`NoInitialCipherSuite`, not a `rustls::Error`). noq-gated.
    #[cfg(feature = "noq")]
    #[error("wrapping rustls config for noq: {0}")]
    NoqWrap(#[from] noq_proto::crypto::rustls::NoInitialCipherSuite),

    /// Config-mismatch errors that are not wrapped third-party
    /// errors: ACME feature not enabled but `Acme` configured
    /// (server), or `Acme` identity used for client auth. A config
    /// error, not a wrapped third-party error.
    #[error("TLS config error: {0}")]
    AcmeConfig(String),
}

Notes on the shape, per ADR-088's rationale:

• Single enum, not a thin wrapper. ADR-088's three findings stand: the QUIC-wrap failure is NoInitialCipherSuite (not a rustls::Error), rustls_pemfile's error is not a std::error::Error, and WebPkiServerVerifier::build() returns its own VerifierBuilderError. One enum with #[from] sources models the actual call sites.
• The quinn-gated variant becomes NoqWrap (noq-gated), renaming ADR-088's QuinnWrap per ADR-003. Same failure type name (NoInitialCipherSuite), different crate path.
• AcmeConfig(String) keeps string payloads. The two Acme mismatches are genuinely configuration mistakes, not wrapped upstream errors; there is no third-party error type to preserve. The extracted code's residual Config(String) call sites (e.g. CertifiedKey::from_der string fallbacks in the client-auth builder) map to this variant — see the refinement below.
• Scope boundary holds (alknet ADR-088 §6). TlsError is the config-construction error type. Handshake outcomes (a rejected cert, the unknown-raw-key fail-closed) flow through the transport's connector; ACME state-machine runtime errors are stream events logged in the spawned task. No handshake variants, ever.
• #[non_exhaustive] from day one. The enum is crate-local today, but the rewrite compiles against it; new variants are additive for consumers that match with a wildcard arm.

Refinement over the extracted code: the extracted code uses TlsError::Config(e.to_string()) at rustls::Error call sites that ADR-088 assigns to Rustls (e.g. with_single_cert, CertifiedKey::from_der — both return rustls::Error). This crate maps those call sites to the typed variants. The only genuinely stringy sites are the Acme mismatches, which land in AcmeConfig (matching the sketch above — AcmeConfig holds exactly the two config-mismatch cases, nothing else). No Config(String) catch-all survives — a variant-per-category enum with a string catch-all would reintroduce the fold this ADR removes.

Consequences

Positive:

• #[source] chains survive for programmatic inspection (the rewrite's config plumbing can distinguish a missing file from a bad PEM from a bad config without string parsing).
• The crate ships the recorded target shape — no later migration.
• The noq rename rides along; TlsError never has a QuinnWrap variant to deprecate.

Negative:

• Six variants is more surface than three; consumers must match more arms (mitigated by #[non_exhaustive] + wildcard arms).
• rcgen::Error in the public API couples the error type to rcgen's error churn (accepted — rcgen 0.13 is stable and the coupling is what ADR-088 chose).

Amendment (2026-09-10, from the Phase 2 implementation): the VerifierBuild source's reachable path at the pinned rustls 0.23.44 is rustls::client::VerifierBuilderError, not rustls::webpki::VerifierBuilderError — the rustls::webpki module is private at that version and the type is publicly re-exported at rustls::client (same type; the implementation carries it that way, with the path noted in the variant's doc comment).

References

• alknet ADR-088 — the recorded target shape and its rationale
• alknet ADR-088 §5 — the root-store fallback that keeps NoRootAnchors unreachable
• docs/research/phase-0.md §Gaps #1 — the gap analysis
• ADR-001 — the inheritance baseline
• ADR-003 — the noq feature (the NoqWrap rename)