Architecture¶
How a call travels through the SDK, and where each part lives. For the reasons behind the shape, see the decision records.
One call, end to end¶
caller
│ client.generate(csv, "payments.csv", kPain00100109)
▼
Client (src/client.cpp)
│ builds the JSON body, URL and headers (Accept, User-Agent,
│ Authorization, Content-Type) into an HttpRequest
│ GET + RetryPolicy set? ──► detail::send_with_retry (src/retry.cpp)
▼
Transport::send (include/pain001/client.hpp)
│ default: CurlTransport (src/curl_transport.cpp), one libcurl easy
│ handle per Client; tests: FakeTransport or a loopback server
▼
pain001 serve ──► HttpResponse {status, body, headers}
│
▼
Client
│ 2xx: parse JSON, decode with from_json (src/models.cpp)
│ 422 refusal on generate: GenerationRefused
│ other non-2xx: ApiError; no response or bad shape: TransportError
▼
typed struct (GenerateResponse, ...)
Source layout¶
| Path | What it holds |
|---|---|
include/pain001/client.hpp |
The whole public API: Client, the options, the response structs, the error types, Transport and RetryPolicy |
src/client.cpp |
Request building, error mapping, the typed methods |
src/models.cpp, src/models.hpp |
from_json decoders for every response struct; counts that do not fit std::int64_t are refused |
src/retry.cpp, src/retry.hpp |
The opt-in retry loop: backoff, jitter, Retry-After |
src/curl_transport.cpp |
The libcurl Transport, with RAII ownership of every handle |
tests/ |
GoogleTest: unit tests with a fake transport, the libcurl transport against a scripted loopback server, the retry policy, the conformance kit runner and typed tests against a live server |
tests/package/ |
A consumer of the installed CMake package |
fuzz/ |
libFuzzer targets for response decoding and error mapping |
benchmarks/ |
Google Benchmark: client-side cost and loopback round trips |
examples/ |
One program per public method |
conformance/ |
The kit vendored from core; never edited here |
Design rules¶
- No payment logic. The SDK does not parse CSV or XML or check an IBAN; the server does (ADR 0001).
- One header. Everything public is in
include/pain001/client.hpp;src/*.hppare internal. - Never log. No code path writes to a stream.
ApiError::what()holds only the status; the server's detail, which can name rows and values, is returned throughdetail(). - Strings for open sets. Message types, schemes and faces are strings, with constants for the known message types, so a newer server works without an SDK release.
- Thread-compatible. A
Clientowns one libcurl handle and reuses its connection; oneClientper thread, or a caller's own mutex. - Retries are opt-in and GET only (ADR 0004).
How it is proven¶
- Unit tests reach every line and branch outcome of
include/andsrc/(make coverage; one defensive branch is excluded inline, see DEVELOPMENT.md). - The conformance kit (
conformance/cases.json) runs every case throughClient::requestagainst a livepain001 serve, and the typed tests check each method's decoded fields. - The fuzz targets feed arbitrary bodies through a canned transport and check that only the documented exceptions escape.