Changelog¶
All notable changes to this project are documented in this file. The format follows Keep a Changelog, and versions advance by 0.0.1 in lockstep with the pain001 suite. The first release will be 0.0.88.
[0.0.88] - 2026-11-14¶
Changed¶
- CI tests against pain001 0.0.88, the release this SDK ships with
(
ci/server-requirements.in). - The README follows the suite's template in full: crates.io and docs.rs badges, the complete family table, the shared ecosystem comparison, measured benchmarks, the example index, and the four documentation links.
- The version moves to 0.0.88 in
Cargo.toml, both lockfiles,CITATION.cff, theSECURITY.mdsupport table, the bug report form and theKEYS.ascexample. No 0.0.87 was tagged, so 0.0.88 is this crate's first release, at the suite's version. - The test-only
sha2dependency moves to 0.11.0 (was 0.10.9). The kit checksum test hex-encodes the digest itself, since 0.11's output type has noLowerHex. 0.11.0 is the newest release within the 1.85 MSRV (0.11.1 needs Rust 1.88), so Dependabot skips 0.11.1 and later until the floor rises. The runtime dependencies and the MSRV are unchanged.
Added¶
- Documentation:
DEVELOPMENT.md(toolchain, every CI gate and its local command, test layout, release model, the settings the maintainer creates),GOVERNANCE.md, and indocs/the architecture, ADRs 1 to 5, the ecosystem comparison with evidence links, the benchmarks with their environment, the roadmap and a packaging guide. - A user manual: MkDocs Material from
docs/with the root documents included, the rustdoc API reference under/api/, built strict with an offline link check and the author footer checked on every page (make manual,scripts/build-manual.sh), deployed to GitHub Pages by the Manual workflow once the maintainer enables Pages. .editorconfig,.pre-commit-config.yaml(local hooks: fmt, clippy, complexity, versions, codespell, markdownlint, REUSE) and a.devcontainer/whose image, pinned by digest and tracked by Dependabot, carries the toolsmake checkneeds at CI's versions.- REUSE compliance:
REUSE.tomlgives every file its copyright andApache-2.0 OR MIT,LICENSES/holds both texts, and the docs-lint workflow runsreuse lintand codespell (.codespellrc) beside markdownlint;make docs-lintruns all three. scripts/complexity-gate.py(make complexity, part ofmake check, and a CI job): every tracked.rsfile is held to cyclomatic 10, cognitive 15, Halstead difficulty 30 and 60 lines per function, and 500 lines per file, measured with rust-code-analysis-cli 0.0.25, against a committed baseline that is empty because nothing is over.- Publishing to crates.io as
pain001-sdk:Cargo.tomlnow sayspublish = ["crates-io"](waspublish = false), and.github/workflows/release.ymlreleases av<version>tag: version check,cargo package, a CycloneDX SBOM,SHA256SUMSand build provenance attestations, a GitHub release titledpain001-sdk-rust <version>with notes composed by the suite'sscripts/release_notes.py(vendored from core) fromreleases/v<version>.md, thencargo publishthrough trusted publishing in thereleaseenvironment. A manual run is a dry run, and a re-run replaces assets and tolerates a version already published. Seedocs/adr/0005-publish-to-crates-io.md. scripts/verify-release-versions(make versions, part ofmake checkand CI): fails when a lockfile,CITATION.cff, theSECURITY.mdorSUPPORT.mdtable, the README install snippet, the bug report form or theKEYS.ascexample disagrees withCargo.toml, or, with--tag, when the tag names another version.scripts/check-package.sh(make package-check) fails when the crate package would ship a demo, fuzz, docs, scripts or CI file, andscripts/api-check.sh(make api-check) runs cargo-semver-checks against the newest crates.io release, a no-op until the first one.SUPPORT.md: where to ask, the supported versions, what to expect.make regression(scripts/regression.sh): installs the pinned server into a temporary venv unlessPAIN001_SERVERnames one, starts it on a free loopback port with a random API key, runsmake check,make conformance(kit, typed tests, every example) and the benchmark smoke run, and stops the server and removes the venv even on failure.- Benchmarks of every public method with criterion 0.7 (a
dev-dependency; 0.8 needs Rust 1.86, above the floor):
benches/client.rstimes the client-side cost with no network, encoding each request body and decoding each response from the kit's fixtures and the responses inbenches/responses/(recorded from pain001 0.0.87 byscripts/record-bench-responses.sh), andbenches/roundtrip.rstimes a loopback round trip per method againstPAIN001_BASE_URL, skipped without it.make benchruns them,make bench-smokeruns each once, and CI smoke-runs both on every pull request. The client-side bench reaches the encoding and decoding throughpain001_sdk::fuzzing, now also compiled with the newinternalsfeature, which is not public API. - One runnable example per method in
examples/:health,validate,generate,check,faces,project_face,request(the raw call),errors(Error::Apiwith a string and an arraydetail,Error::Refused,Error::Transport, andError::Decodefor a document-less success),timeout,api_keyandretry, besidebasic. Each exits non-zero when the server does not answer as it expects.make examplesruns them all,make conformancenow runs them after the kit, and CI's conformance job does so against a server started with a throwawayPAIN001_API_KEY, which the live tests now send when it is set. RetryPolicy, opt-in throughClient::retry:GETcalls (health,faces,requestwith"GET") are tried again after a transport error or an HTTP429or503, up to 3 attempts by default, with exponential backoff and jitter (200 ms base, 5 s maximum). ARetry-Afterin seconds or as an HTTP date is waited exactly, and one longer than the maximum ends the retries.POSTcalls are never retried. Without a policy every call makes one attempt, as before. Seedocs/adr/0004-opt-in-retries.md.- Every request sends
User-Agent: pain001-sdk-rust/<version>, so a server's access log shows which client and release made a call; it used to be ureq's default.VERSIONandUSER_AGENTare exported, both derived fromCargo.toml. - A README demo,
.github/demo.gif, rendered bymake demofrom.github/demo.tape:cargo run --example basicagainst apain001 serveon 127.0.0.1, then the head of the generated file. The server comes fromPAIN001_SERVERorPATH; the GIF and tape are excluded from the package. Client, a blocking client for the pain001 REST API onureq, with.api_key(..)(sent as a bearer token) and.timeout(..)(30 seconds by default).- One typed method per endpoint:
health,validate,generate,check,facesandproject_face, plus the low-levelrequest. MessageTypewith the 13 message types of the server's OpenAPI enum; methods also accept any string.ErrorwithApi { status, detail },TransportandDecode, andError::request_errors()for a422's FastAPIdetailitems.Error::Refused { status, response }andError::refusal(): pain001 0.0.87 answers a refused generation (rows that fail validation or a scheme rule) with HTTP422instead of200, andgeneratenow returns the decodedGenerateResponsewith its typedvalidation_errorsandscheme_violations, so the findings are not lost in a rawdetail.Error::status()still reports422, and anOkfromgeneratealways carries the XML.RowError(field,message,value) for row errors. The 0.0.85 OpenAPI document names FastAPI's request-error schema for these lists through a name collision; the type follows what the server sends.- The conformance kit from pain001 core, vendored in
conformance/with its SHA-256 sums pinned inconformance/SHA256SUMS: kit version 2 from core 0.0.87, 14 cases, adding the422generate refusals (bad rows and a UK CHAPS scheme breach) and the bad-LEI and CHAPS purpose validation cases with their fixtures. tests/conformance.rs, a port of core's reference runner that sends every kit case throughrequest(), andtests/typed.rs, one test per method; both run againstPAIN001_BASE_URLand skip without it.examples/basic.rs: generate and check a pain.001.001.09 file.- CI on stable and on Rust 1.85.0, cargo-deny, the conformance job
against
pain001 serve0.0.86 from hash-pinned requirements, the DCO check and Markdown lint. - A coverage gate:
make coverage(part ofmake check) and the CIcoveragejob run cargo-llvm-cov and fail below 100% of lines or regions insrc/, thecfg(fuzzing)decoding module included. There are no exclusions. - Fuzzing with cargo-fuzz in
fuzz/, a crate of its own: theresponsetarget decodes any 2xx body as every typed call's response, and theerrortarget maps any status and body to the error a call returns, both checking the documented contracts (onlyError::Decodefor a 2xx, the documenteddetailforError::Api,Error::Refusedonly for a refusal body). They reach the decoding path throughpain001_sdk::fuzzing, which exists only undercfg(fuzzing)and is not public API. A pull request runs each target for 30 seconds from the seeds infuzz/seeds/.
Fixed¶
generatereturnsError::Decodefor a 2xx reply that lackssuccess: trueor the XML, so anOkalways carries the document as the README says; it used to return theGenerateResponsewithxml: None. A422whose body hassuccess: falsebut also carriesxmlstaysError::Apiinstead of becomingError::Refused, whose response is documented to have no XML. pain001 0.0.87 sends neither shape; adding the fuzz targets showed that the client enforced neither promise.