Architecture¶
Pain001.Sdk is a thin client: every call is a request to
pain001 serve, which does the work (ADR 0001).
This page is for contributors: where things live and how a call flows.
Layout¶
| Path | What it holds |
|---|---|
src/Pain001.Sdk/Pain001Client.cs |
The client: one public method per endpoint, the send path, timeouts and retries |
src/Pain001.Sdk/Pain001ClientOptions.cs, RetryPolicy.cs |
Configuration: base address, API key, timeout, retry policy, clock |
src/Pain001.Sdk/Models/ |
Response records, mapped from the server's snake_case JSON |
src/Pain001.Sdk/Internal/Requests.cs |
Request bodies (UiFilePayload, CheckRequest, FaceRequest) |
src/Pain001.Sdk/Internal/Wire.cs |
JSON options, body parsing, error-detail extraction, decoding, refusal detection |
src/Pain001.Sdk/Pain001*Exception.cs |
The error model (ADR 0003) |
conformance/ |
Core's conformance kit, vendored byte for byte |
tests/Pain001.Sdk.Tests/ |
Unit tests, FsCheck properties, the kit runner, live-server tests |
examples/ |
One console project per method |
benchmarks/ |
BenchmarkDotNet: client-side and loopback |
How a call flows¶
GenerateAsync(content, filename, messageType, scheme)
-> FilePayload: argument checks, a UiFilePayload record
-> SendPayloadAsync: System.Text.Json to UTF-8 bytes (nulls omitted)
-> SendCoreAsync: POST, so one attempt (GETs go through the RetryPolicy)
-> SendOnceAsync: HttpRequestMessage (Accept, Bearer key, JSON body),
a linked CancellationTokenSource for the timeout, read every byte
-> Wire.ParseBody: JsonElement; empty is Undefined, non-JSON is a string
-> Wire.AsRefusal: 422 + success false -> Pain001GenerationRefusedException
-> Wire.Decode: non-2xx -> Pain001ApiException; 2xx -> the record
-> no XML in a 2xx -> Pain001NoDocumentException
RequestAsync stops after ParseBody: it returns the status and body,
whatever the status. The conformance runner uses it, so the kit tests
the same send path as every typed method.
Invariants¶
- No payment data in messages. Exception messages name the status
and counts; the detail and findings stay in properties.
ResponsePropertyTestschecks this with generated error bodies. - Every body can be read. A body that is not valid UTF-8 or not JSON
becomes a JSON string of its text, so
Detail.GetString()never throws. - One request per POST. Only a
GETis ever retried (ADR 0004). - The caller's
HttpClientis theirs. The client never changes its settings and disposes only anHttpClientit created. - No third-party runtime dependency (ADR 0002).
Where the contract comes from¶
The server's OpenAPI document is vendored at
conformance/openapi.json; the records follow its schemas by hand. The
kit's cases (conformance/cases.json) pin statuses and fields. When core
changes the wire, it ships a new kit; this repository copies it in,
updates SHA256SUMS, and changes the client until every case passes.