pain001-sdk 0.0.88

Typed blocking client for the pain001 REST API (ISO 20022 pain.001 and pain.008)
Documentation

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

Library reference

Operational


Install

As a Rust library

[dependencies]
pain001-sdk = "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:

pip install 'pain001[api]==0.0.88'
pain001 serve --host 127.0.0.1 --port 8000

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-version in Cargo.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 in ci/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 pain001_sdk::{Client, Error, MessageType};
use std::time::Duration;

fn main() -> Result<(), Error> {
    let client = Client::new("http://127.0.0.1:8000").timeout(Duration::from_secs(10));
    let csv = std::fs::read_to_string("payments.csv").expect("read the CSV");

    let generated = client.generate(&csv, "payments.csv", MessageType::Pain00100109, None)?;
    let xml = generated.xml.expect("success carries the XML");

    let report = client.check(&xml, None, None)?;
    println!("{} passed={}", report.message_type, report.passed);
    Ok(())
}

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 pain001_sdk::{Client, Error};
# let client = Client::new("http://127.0.0.1:8000");
# let csv = String::new();
match client.generate(&csv, "payments.csv", "pain.001.001.09", Some("uk-chaps")) {
    Ok(generated) => println!("{} bytes", generated.xml.unwrap_or_default().len()),
    Err(Error::Refused { response, .. }) => {
        for row in &response.validation_errors {
            eprintln!("{}: {}", row.field, row.message);
        }
        for violation in &response.scheme_violations {
            eprintln!("{}", violation["rule"]);
        }
    }
    Err(other) => eprintln!("{other}"),
}

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 as Authorization: Bearer <key>), .timeout(..) (default 30 seconds per attempt) and .retry(RetryPolicy). One method per endpoint, plus request(). Every request sends User-Agent: pain001-sdk-rust/<version>. Clones share the connection pool; Debug output redacts the API key.
  • Types (src/types.rs): HealthResponse, ValidationResponse, GenerateResponse, CheckResponse with CheckFinding, FaceInfo, FaceResponse with LossReport, RowError and RequestError. FaceResponse::payload stays raw serde_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 take impl AsRef<str>, so a type a newer server adds works as a plain string.
  • Error (src/error.rs): Refused { status, response } for a 422 refusal from generate, with the decoded GenerateResponse (also through Error::refusal()); Api { status, detail } for any other non-2xx response, typed by Error::request_errors() for a 422 detail array; Transport for connection, timeout and TLS failures; Decode for a 2xx body of the wrong shape. Error::status() covers Refused and Api.
  • RetryPolicy (src/retry.rs): 3 attempts, 200 ms base and 5 s maximum delay by default, for GET calls 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 cargo run --example health
PAIN001_BASE_URL=http://127.0.0.1:8000 make examples   # all of them
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/generate is reachable only through request().
  • You need a POST retried. The client never repeats one, since that could submit a payment file twice; that decision stays with the caller.

Development

git clone https://github.com/sebastienrousseau/pain001-sdk-rust
cd pain001-sdk-rust
make check
make regression

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:

at your option. Dependencies keep their own licences.