Architecture¶
CryptoService.Sdk is a thin client: every call is a request to
crypto-server, which does the cryptography
(ADR 0001). This page is for
contributors: where things live and how a call flows.
Layout¶
| Path | What it holds |
|---|---|
src/CryptoService.Sdk/CryptoServiceClient.cs |
Construction, disposal, RequestAsync and the generic send helpers |
src/CryptoService.Sdk/CryptoServiceClient.*.cs |
One public method per operation, by area (Meta, Hashing, Symmetric, Keys, PostQuantum, Asymmetric, Kms, Opaque) |
src/CryptoService.Sdk/Models/ |
Request and result classes, one per schema |
src/CryptoService.Sdk/Internal/Transport.cs |
Request building, timeouts, the deadline, the retry loop, redirect refusal |
src/CryptoService.Sdk/Internal/RetryDecision.cs, Idempotency.cs |
When to retry and after how long; the retry-safety table |
src/CryptoService.Sdk/Internal/Decoding.cs |
2xx decoding and problem parsing (both fuzzed) |
src/CryptoService.Sdk/Internal/CryptoJsonContext.cs |
The source-generated JSON contract |
src/CryptoService.Sdk/Crypto*Exception.cs, ProblemDetails.cs |
The error model (ADR 0003) |
conformance/, ci/server.ref |
crypto-service's conformance kit, vendored byte for byte, and the commit it came from |
tests/, fuzz/, benchmarks/, examples/ |
Unit and conformance tests, SharpFuzz targets, BenchmarkDotNet, runnable examples |
How a call flows¶
SignAsync(SignRequest)
-> PostAsync: argument check, the request to UTF-8 JSON (source-generated, nulls omitted)
-> Transport.SendAsync: a CancellationTokenSource for the deadline; is the route idempotent?
-> AttemptAsync: a linked source for the per-attempt timeout
-> BuildRequest: Accept, User-Agent, traceparent, x-api-key or Bearer, HTTP/2 policy
-> HttpClient.SendAsync (headers first), redirect check
-> 2xx: Decoding.ReadSuccessAsync streams the body into DataEnvelope<SignResult>
-> else: Decoding.ReadErrorAsync reads up to 64 KiB into a ProblemDetails
-> failure: RetryDecision.DelayAfter (status, idempotency, Retry-After, backoff)
-> wait, or raise CryptoApiException / CryptoTransportException
-> the envelope's data
Invariants¶
- No cryptography in the client; byte accessors only decode the encoding the server chose.
- No secret in a message or
ToString(); options redact credentials, models print their type name only. - A stateful call is never repeated after the server may have acted (504, a lost connection, a timeout).
- Immutable after construction, so one client serves concurrent calls from any thread.
- The caller's
HttpClientis theirs: the client never changes its settings and disposes only anHttpClientit created.
Where the contract comes from¶
crypto-service's OpenAPI document is the contract; the models follow
its schemas by hand, and the conformance kit pins statuses and bodies.
The kit runner re-encodes each typed answer with the SDK's own contract
before matching it, so a member the models drop or misname fails a
vector. When crypto-service changes the wire, a new kit and
ci/server.ref come in together.