docs(arch): tighten tls/endpoint/client specs — remove connect/connect_quic, move CallCredentials to core, shed alknet-call TLS deps
Review of the three new crates (alknet-tls, alknet-endpoint, alknet-client) + revised core found compile-blocking inconsistencies, stale claims, and dep-graph contradictions. All resolved: Critical: - C1: CallClient::connect / ChannelClient::connect_quic REMOVED (not delegated) — keeping them as thin wrappers over AlknetClient::dial_quic would make protocol crates depend on alknet-client, contradicting the dep graph. Callers compose dial + take-over (2 lines). - C2: alknet-client feature gates now pull alknet-core/quinn + alknet-core/iroh (for Connection::from_quinn_with_alpn / from_iroh). - C3: rustls-native-certs + webpki-roots added to alknet-tls deps (always-present, not feature-gated — CA-verify path is transport-agnostic). Warning: - W1: CallCredentials/RemoteIdentity moved to alknet-core (from alknet-call) — the dial must not depend on the call protocol; not a two-way-door, it determines the dep graph. - W2: webpki-roots fallback implemented in spec (ADR-088 §5 added) — the code claimed a fallback that never existed; now the store is never empty, NoRootAnchors unreachable, containerized deployments work. - W3: EndpointError removed entirely (BindFailed + HandlerNotFound both vestigial after ADR-083); shutdown() is now infallible. - W4: FingerprintPinVerifier moved to alknet-tls (from alknet-call) — alknet-call sheds quinn/rustls/rustls-pemfile/rustls-native-certs entirely; CallClient becomes a pure protocol crate. Plus: ClientError removed (only produced by removed connect); S1 (CallCredentials → ClientVerifierContext mapping + auth_token stripped at TLS boundary documented); amendment notes on ADR-017, ADR-069, ADR-080, ADR-082, ADR-087, ADR-090; overview crate graph + README index updated. 29 files, consistency-reviewed.
This commit is contained in:
1 parent
34e3be2801
commit
bf6ce957c0
29 files changed
+524
-267
No files matched your search
@@ -4,5 +4,5 @@
|
||||
- **Status**: resolved
|
||||
- **Door type**: One-way
|
||||
- **Priority**: high
|
||||
- **Resolution**: `CallClient` takes over transport connections (`spawn_dispatch` transport-agnostic primary, `connect` QUIC convenience — ADR-017 Am. 2026-07-13) and shares the dispatch loop with `CallAdapter` — both sides can send and receive `call.requested` once connected. Connection direction (who opened the connection) is independent of call direction (who calls whom). `from_call` adapter discovers remote operations via `services/list` + `services/schema` and registers them with forwarding handlers — same pattern as `from_openapi` and `from_mcp`. `to_openapi` and `to_mcp` project local operations to external protocols. Adapter contract trait (`OperationAdapter`) produces `HandlerRegistration` bundles. Cross-node call tree: abort cascade (ADR-016) propagates across node boundaries through `from_call` handlers. Credentials for connections come from capabilities (ADR-014). Adapter-registered operations are `Internal` by default (ADR-015). See ADR-017.
|
||||
- **Resolution**: `CallClient` takes over transport connections (`spawn_dispatch` transport-agnostic primary; `connect` removed per ADR-089 §5 — dial extracted to `AlknetClient`) and shares the dispatch loop with `CallAdapter` — both sides can send and receive `call.requested` once connected. Connection direction (who opened the connection) is independent of call direction (who calls whom). `from_call` adapter discovers remote operations via `services/list` + `services/schema` and registers them with forwarding handlers — same pattern as `from_openapi` and `from_mcp`. `to_openapi` and `to_mcp` project local operations to external protocols. Adapter contract trait (`OperationAdapter`) produces `HandlerRegistration` bundles. Cross-node call tree: abort cascade (ADR-016) propagates across node boundaries through `from_call` handlers. Credentials for connections come from capabilities (ADR-014). Adapter-registered operations are `Internal` by default (ADR-015). See ADR-017.
|
||||
- **Cross-references**: ADR-005, ADR-013, ADR-014, ADR-015, ADR-016, ADR-017, [call-protocol.md](crates/call/call-protocol.md), [operation-registry.md](crates/call/operation-registry.md)
|
||||
@@ -39,9 +39,10 @@
|
||||
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).
|
||||
take-over (`from_connection`, ADR-080) are decided; the
|
||||
`connect` / `connect_quic` convenience constructors are **removed**
|
||||
per ADR-089 §5 (not delegated — the dial is centralized in
|
||||
`AlknetClient`, and the protocol crates shed their TLS/transport deps).
|
||||
- **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
|
||||
|
||||
@@ -76,14 +76,14 @@
|
||||
Subsidiary question: does `TlsError` live in `alknet-tls` (owned by
|
||||
the crate that produces it) or is it re-exported from `alknet-core`?
|
||||
**Resolved: `alknet-tls`, owned by the crate that produces it.**
|
||||
`alknet-core`'s `EndpointError` no longer has a `TlsConfig` variant
|
||||
after ADR-083 (the endpoint takes no TLS config); core does not need to
|
||||
know about `TlsError`. Re-exporting from core would invert the
|
||||
ownership (core re-exporting a type from a crate that depends on it).
|
||||
`EndpointError` is removed entirely after ADR-083 (both variants
|
||||
vestigial); core has no endpoint error type and does not need to know
|
||||
about `TlsError`. Re-exporting from core would invert the ownership
|
||||
(core re-exporting a type from a crate that depends on it).
|
||||
- **Cross-references**: ADR-088 (the resolution — single enum, owned by
|
||||
`alknet-tls`, six variants), ADR-082 (the extraction that introduces
|
||||
`TlsError`), ADR-083 (the endpoint refactor that removes
|
||||
`EndpointError::TlsConfig`, making `TlsError` the sole TLS error
|
||||
`EndpointError` entirely, making `TlsError` the sole TLS error
|
||||
surface), ADR-087 (extends the surface to client-side variants),
|
||||
`crates/alknet-core/src/endpoint.rs` (the current
|
||||
`io::Error`-wrapping pattern the new type replaces),
|
||||
|
||||
@@ -32,8 +32,10 @@
|
||||
`TlsClientConfig::new` takes a verifier context (the inputs to
|
||||
ADR-034's rule: `PeerEntry` presence, expected fingerprint, remote
|
||||
cert type) and returns a `rustls::ClientConfig`. The caller
|
||||
(transport-specific dial helper, `CallClient::connect_quic`, a future
|
||||
`connect_tcp_tls`) passes it to the transport's connector. Iroh is
|
||||
(transport-specific dial helper — now `AlknetClient::dial_quic` /
|
||||
`dial_tcp_tls` per ADR-089; the per-protocol `CallClient::connect` /
|
||||
`ChannelClient::connect_quic` convenience constructors are removed
|
||||
per ADR-089 §5) passes it to the transport's connector. Iroh is
|
||||
the exception — it has its own TLS and does not consume a
|
||||
`rustls::ClientConfig`; the iroh dial helper applies the same
|
||||
ADR-034 rule via iroh's `NodeId` verification API.
|
||||
|
||||
Reference in new issue
Block a user