Contents
Getting started
- Install: from crates.io, or the git repository
- Requirements: toolchain floor, platforms
- Quick Start: generate a pain.001 file from a CSV in one call
The pain001-sdk-rust ecosystem
- The pain001-sdk-rust ecosystem: the pain001 core, its servers, loaders, tools and SDKs
Library reference
- Capabilities at a glance: the current surface by theme
- Ecosystem comparison: short matrix; full table at
docs/COMPARISON.md - Benchmarks: headline numbers; full table at
docs/BENCHMARKS.md - Features: module-level capability list
- Configuration: core options
- Examples: runnable example index
Operational
- When not to use pain001-sdk-rust: limitations
- Development: make targets, fuzzing, CI
- Security: guarantees and compliance
- Documentation: all reference docs
- Stability guarantees: SemVer axis, output stability, minimum toolchain discipline
- License
Install
As a Rust library
[]
= "0.0.88"
0.0.88 is the first release published to crates.io. Before it is out,
depend on the repository instead:
pain001-sdk = { git = "https://github.com/sebastienrousseau/pain001-sdk-rust" }.
The client needs a running pain001 server, which is a Python package:
HTTPS uses rustls through the default tls feature. A client that only
talks to a loopback server over plain HTTP can drop it with
default-features = false. cargo add pain001-sdk does the same as the
snippet above.
Requirements
- Rust 1.85 or newer (
rust-versioninCargo.toml), built and tested in CI on 1.85.0 and stable on Linux (toolchain policy). - A pain001 server to talk to. CI runs the conformance kit in
conformance/against pain001 0.0.88, the latest release, pinned inci/server-requirements.in. - No async runtime: every call blocks the calling thread. Any platform ureq and rustls support; CI runs on Linux, development happens on macOS.
Quick Start
use ;
use Duration;
generate posts the file's text to POST /api/v1/ui/generate and
returns the XML inline; an Ok always carries it. Rows that fail
validation or a scheme rule come back as Error::Refused, a 422 whose
refusal() holds the typed validation_errors and scheme_violations.
A file the server cannot read at all (a bad IBAN, an unknown message
type) comes back as Error::Api with the HTTP status and the server's
detail, so the caller sees why.
# use ;
# let client = new;
# let csv = Stringnew;
match client.generate
The pain001-sdk-rust ecosystem
This crate is one of the pain001 suite. pain001 has one engine, the Python server, and thin typed clients per language that all pass one shared conformance kit. The suite releases together at one version, core first; this crate's first release is 0.0.88.
| Component | Purpose | Use case |
|---|---|---|
pain001 |
Generation, validation, CLI and REST | The server this client calls |
pain001-mcp |
Model Context Protocol server | Agent tools for payment data |
pain001-lsp |
Language Server Protocol server | Editor diagnostics for payment data |
pain001-loader-mt101 |
SWIFT MT101 loader plugin | Convert supported MT101 inputs |
pain001-loader-xlsx |
Excel loader plugin | Read .xlsx and .xlsm payment inputs |
pain001-mockbank |
Synthetic SFTP bank-response test service | Generate pain.002 replies in integration tests |
pain001-plugin-template |
Cookiecutter plugin scaffold | Develop an external loader or validator |
pain001-fast |
Experimental native validation extension | Optional IBAN, BIC and character-set helpers |
pain001.com |
Website and browser demo | Browse documentation and try the library |
pain001-sdk-go, -java, -dotnet, -cpp |
Typed clients in other languages | Call pain001 from Go, Java, .NET or C++ |
pain001-sdk-rust |
Typed Rust client for the REST API | Call pain001 from a Rust service |
Capabilities at a glance
| Area | Capability | Status |
|---|---|---|
| Health | health(): GET /api/v1/health |
Supported |
| Validation | validate(): a CSV, JSON or JSONL file's rows, with optional scheme rulebooks |
Supported |
| Generation | generate(): pain.001 and pain.008 XML from a file's text; a refusal is a typed Error::Refused |
Supported |
| Checking | check(): the XSD, MDR, scheme and Schematron ladder on an existing document |
Supported |
| Faces | faces() and project_face(): project a pain.001 into Berlin Group, ISO 2018 names or UK Open Banking, with a loss report |
Supported |
| Low level | request(): any method and path, returning the status and parsed JSON |
Supported |
| Errors | Error::Api, Refused, Transport, Decode |
Supported |
| Retries | RetryPolicy: opt-in retries of GET calls on transport errors, 429 and 503, honouring Retry-After |
Supported, off by default |
| Async jobs | POST /api/v1/generate with server-side file paths and job polling |
Not wrapped; use request() |
Ecosystem comparison
The suite's five SDKs share one method surface and run core's conformance kit against a live pain001 serve in CI. Core's CI also generates a Python client from the OpenAPI document, which it imports but does not run against the kit.
| Project | Language (minimum) | Conformance kit in CI | Types |
|---|---|---|---|
| pain001-sdk-go | Go 1.26 | Yes | Hand-written |
| pain001-sdk-java | Java 17 | Yes | Hand-written |
| pain001-sdk-rust | Rust 1.85 | Yes | Hand-written (serde) |
| pain001-sdk-dotnet | .NET 10 | Yes | Hand-written |
| pain001-sdk-cpp | C++17 | Yes | Hand-written |
| openapi-generator client (core CI artifact) | Python | No, CI imports it only | Generated |
| Raw HTTP | Any | No | None |
See docs/COMPARISON.md for the evidence and complete matrix.
Benchmarks
Criterion benchmarks cover every public method: the client-side cost
with no network (encoding each request body, decoding each response) and
a loopback round trip against pain001 serve. The client's work is
microseconds; the server's is milliseconds. Medians from the first of two
runs on a busy laptop (load average 25 to 63), so read them as orders of
magnitude:
| Scenario | Result | Environment |
|---|---|---|
Decode a generate response (4,466 bytes, XML inside) |
12.0 µs | Apple A18 Pro, macOS 27.2, rustc 1.99.0 |
Encode a check request (the kit's pain.001) |
10.0 µs | same |
Round trip, health |
0.44 ms | same, pain001 0.0.87 on loopback |
Round trip, generate (5 rows) |
16.4 ms | same |
Round trip, project_face |
24.2 ms | same |
See docs/BENCHMARKS.md for methodology and full results.
Features
Client(src/client.rs):Client::new(base_url)with.api_key(..)(sent asAuthorization: Bearer <key>),.timeout(..)(default 30 seconds per attempt) and.retry(RetryPolicy). One method per endpoint, plusrequest(). Every request sendsUser-Agent: pain001-sdk-rust/<version>. Clones share the connection pool;Debugoutput redacts the API key.- Types (
src/types.rs):HealthResponse,ValidationResponse,GenerateResponse,CheckResponsewithCheckFinding,FaceInfo,FaceResponsewithLossReport,RowErrorandRequestError.FaceResponse::payloadstays rawserde_json::Value, since each face has its own shape. Response structs are#[non_exhaustive]. MessageType: the 13 message types in the server's OpenAPI enum. Methods takeimpl AsRef<str>, so a type a newer server adds works as a plain string.Error(src/error.rs):Refused { status, response }for a422refusal fromgenerate, with the decodedGenerateResponse(also throughError::refusal());Api { status, detail }for any other non-2xx response, typed byError::request_errors()for a422detailarray;Transportfor connection, timeout and TLS failures;Decodefor a 2xx body of the wrong shape.Error::status()coversRefusedandApi.RetryPolicy(src/retry.rs): 3 attempts, 200 ms base and 5 s maximum delay by default, forGETcalls only (ADR 4).
Configuration
| Option | Default | Set with |
|---|---|---|
| Base URL | none | Client::new("http://127.0.0.1:8000") |
| API key | none | .api_key(key) |
| Timeout per attempt | 30 seconds (DEFAULT_TIMEOUT) |
.timeout(Duration) |
| Retries | none | .retry(RetryPolicy::new()), tuned with with_max_attempts, with_base_delay, with_max_delay |
| HTTPS | on (rustls) | the tls Cargo feature |
The client reads no environment variables. The tests, examples and
benchmarks read PAIN001_BASE_URL and PAIN001_API_KEY.
Examples
One program per method, each run against a live server in CI's conformance job and exiting non-zero when an answer is wrong:
PAIN001_BASE_URL=http://127.0.0.1:8000
PAIN001_BASE_URL=http://127.0.0.1:8000
| Example | Shows |
|---|---|
basic |
health, generate a pain.001.001.09 file, write it, check it |
health |
health() |
validate |
validate(), a valid file and a typed row error |
generate |
generate() of a pain.008.001.08 direct debit |
check |
check(), the rungs and findings |
faces |
faces() and their bindings |
project_face |
project_face() into Berlin Group, with the loss report |
request |
request(), the raw call, with a 200 and a 404 |
errors |
Error::Api (string and array detail), Refused, Transport, and Decode for a document-less success |
timeout |
.timeout() firing against a silent listener |
api_key |
.api_key(): 401 without it, 200 with it |
retry |
RetryPolicy: a GET retried past a 503, a POST not |
When not to use pain001-sdk-rust
- You need async. The client blocks the calling thread; in an async service, call it from a blocking task, or use an async HTTP client against the same API.
- You cannot run a Python server. The work happens in pain001, so a server must be reachable.
- You want to read files on the server. The wrapped endpoints take
the file's text in the request; the path-based
POST /api/v1/generateis reachable only throughrequest(). - You need a
POSTretried. The client never repeats one, since that could submit a payment file twice; that decision stays with the caller.
Development
make check runs rustfmt, clippy with -D warnings and the complexity
lints, the build (benches included), the tests at 100% line and region
coverage (cargo-llvm-cov), rustdoc with warnings denied, cargo deny,
the complexity ceilings (cyclomatic 10, cognitive 15, Halstead difficulty
30, 60 lines per function), the version check and the package contents
check. make regression installs the pinned server into a temporary
venv, starts it on loopback with an API key, and adds the conformance
kit, every example and the benchmark smoke run. The fuzz targets in
fuzz/ run for 30 seconds each on every pull request. See
DEVELOPMENT.md for every gate and its CI job.
Security
The crate has no unsafe code (#![forbid(unsafe_code)]). It never logs
request or response bodies, which carry payment data, and its Debug
output hides the API key. HTTPS uses rustls with the webpki root store;
use HTTPS and an API key for any server that is not on loopback. A
response body is read up to 64 MiB. No POST is ever retried. The
response decoding and error mapping are fuzzed with cargo-fuzz on every
pull request from committed seeds, and every dependency is checked by
cargo deny for RustSec advisories and licences. CodeQL and OpenSSF
Scorecard run on main; releases carry an SBOM and build provenance.
Report vulnerabilities according to SECURITY.md.
Documentation
User manual · API reference (docs.rs) · Developer docs · Ecosystem map
Also: Architecture · Decision records · Conformance kit · Changelog · Policies · Packaging · Roadmap · Support · Governance · Agent rules
Stability guarantees
The project is pre-1.0 and versions advance in 0.0.1 steps, in lockstep
with the pain001 suite. The breaking axis is the public Rust API: method
signatures, the Error variants, RetryPolicy and the response types;
cargo-semver-checks guards it against the last crates.io release from
0.0.88 on. Response structs and enums are #[non_exhaustive], so a field
or message type the server adds is not breaking. The client adds no
output of its own: what a call returns is what the server sent, decoded,
so behaviour changes follow the server's release notes and the
conformance kit. The internals feature and pain001_sdk::fuzzing are
not public API. The Rust floor moves only as described in the
toolchain policy.
License
This project is dual-licensed under either:
- Apache License, Version 2.0 (
LICENSE-APACHEor https://www.apache.org/licenses/LICENSE-2.0) - MIT License (
LICENSE-MITor https://opensource.org/licenses/MIT)
at your option. Dependencies keep their own licences.