ADR 0002: The HTTP stack¶
- Status: Accepted
- Date: 2026-11-15
Context¶
The SDK makes many small JSON calls, often concurrently, from servers that keep one client for the process lifetime. It must reuse connections, follow DNS changes, refuse redirects (a redirect would carry the API key or token to another origin), keep TLS validation on, and add no dependency a user's application would have to reconcile.
Decision¶
HttpClientover aSocketsHttpHandlerthat the client creates (CryptoServiceClient.CreateHandler()): pooled keep-alive connections recycled every five minutes (PooledConnectionLifetime),AllowAutoRedirect = false, no cookies, andEnableMultipleHttp2Connections. Each request asks for HTTP/2 withRequestVersionOrLower, so HTTPS negotiates HTTP/2 by ALPN and plain HTTP stays on HTTP/1.1. The SDK never sets a certificate callback and offers no option to.- Injection: a caller's
HttpMessageHandler(tests, custom transports) orHttpClient(IHttpClientFactorytyped clients). An injectedHttpClientis never reconfigured or disposed; a response whose request URI changed (a redirect the caller's handler followed) is refused. System.Text.Jsonwith source generation (CryptoJsonContext): no reflection, trimming- and AOT-compatible, decoding that honoursrequiredand nullability. 2xx bodies are deserialized from the response stream; error bodies are read up to 64 KiB.- No third-party runtime dependency.
Consequences¶
- A caller using
IHttpClientFactoryshould setConfigurePrimaryHttpMessageHandler(CryptoServiceClient.CreateHandler)to keep redirects refused at the handler, not only detected after. - The retry policy, timeouts and deadline are the SDK's own, so they
behave the same whatever
HttpClientis injected; an injected client'sTimeoutstill applies on top.