Architecture¶
pain001-sdk is a thin, typed, blocking client for the REST API of
pain001 serve. Every payment rule, schema and scheme check lives in the
Python server; this crate turns Rust calls into JSON requests and JSON
responses into Rust types and errors. It adds no payment logic of its
own (ADR 1).
Modules¶
| Module | File | Responsibility |
|---|---|---|
client |
src/client.rs |
Client: configuration (base URL, API key, timeout, retry policy), one method per endpoint, request, and the exchange: build the request head, encode the body, send it with ureq, read at most 64 MiB, parse the body |
types |
src/types.rs |
request bodies (crate-private) and the #[non_exhaustive] response types, MessageType |
error |
src/error.rs |
Error and the mapping from a non-2xx status and body to Api or Refused; the check that a 2xx generate carries the XML |
retry |
src/retry.rs |
RetryPolicy: which outcomes are retried, the backoff, Retry-After |
fuzzing |
src/fuzzing.rs |
the encoding and decoding without the network; compiled only for fuzzing, the internals feature (benches) and tests |
stub |
src/stub.rs |
a loopback HTTP stub for unit tests |
A call, end to end¶
Client::generate(content, filename, message_type, scheme)
-> FilePayload { .. } types.rs
-> exchange: encode as JSON client.rs (Error::Decode if it cannot)
-> send: head (method, URL, Accept, client.rs (Error::Transport for a bad URL)
User-Agent, Authorization)
-> once: ureq Agent::run, read body client.rs (Error::Transport on I/O, timeout, TLS)
(GET only: retry::run loops here under a RetryPolicy)
-> parse_body: empty is null, non-JSON is a JSON string
-> decode: 2xx -> GenerateResponse client.rs (Error::Decode on a wrong shape)
non-2xx -> generate_error error.rs (Refused for a 422 refusal, else Api)
-> generated: success and xml present error.rs (Error::Decode otherwise)
Every typed method follows this path; request stops after
parse_body and returns the status and the JSON whatever the status.
Decisions that shape it¶
- Blocking, on ureq. No async runtime is pulled into the caller's program; an async service calls the client from a blocking task (ADR 2).
- One error type.
Errorseparates what the server said (Api,Refused) from what went wrong on the way (Transport) and a reply of the wrong shape (Decode) (ADR 3). - No retries unless asked, never of a POST (ADR 4).
- Published from a signed tag to crates.io (ADR 5).
What keeps it honest¶
- The conformance kit in
conformance/is vendored byte for byte from pain001 core and pinned byconformance/SHA256SUMS; CI runs every case against the server version inci/server-requirements.txt. tests/typed.rsand every example check typed fields against that server; the fuzz targets check the decoding contracts on arbitrary input; the unit tests cover 100% of lines and regions.- Request and response bodies carry payment data, so nothing logs them,
and
Client'sDebugoutput redacts the API key.