ADR 0004: The async model¶
- Status: Accepted
- Date: 2026-11-15
Context¶
Every operation is network I/O. The suite's SDKs offer an async API
first and a blocking one where the language makes it idiomatic.
pain001-sdk-dotnet, the template this repository follows, is async
only. In .NET a blocking wrapper over async I/O (.Result,
.GetAwaiter().GetResult()) risks thread-pool starvation and
deadlocks under a synchronization context, and HttpClient's own
synchronous Send does not support every handler.
Decision¶
- Every operation is
Task<T> XxxAsync(..., CancellationToken cancellationToken = default). There is no blocking variant; a caller that must block does so at its own boundary. - Library awaits use
ConfigureAwait(false)(CA2007 is enforced). CryptoServiceClientis immutable after construction and safe to share across threads and concurrent calls; it implementsIDisposableandIAsyncDisposable, and should live as long as the application, not one call.- Cancellation is the token: cancelling it raises
OperationCanceledExceptionand sends no further attempt. Timeouts and the deadline are separate, and raiseCryptoTransportExceptionwithTimedOutset.
Consequences¶
- Concurrency is
Task.WhenAllover one client (theConcurrentexample); the pooled handler bounds connections, not the SDK. - A console or test that needs a synchronous call uses an
async Mainor its framework's async support.