Development¶
The single entry point for working on pain001-sdk-rust: the toolchain,
every CI gate and how to run it locally, the test layout, and how a
release is made. Links point at the repository, so they work both on
GitHub and in the user manual.
Toolchain¶
| Tool | Version | Used by |
|---|---|---|
| Rust | stable, and 1.85.0 (the floor, rust-version) |
everything |
| clippy, rustfmt, llvm-tools-preview | with the toolchain | make lint, make fmt-check, make coverage |
| cargo-deny | 0.20.2 | make deny |
| cargo-llvm-cov | 0.9.1 | make coverage |
| rust-code-analysis-cli | 0.0.25 | make complexity |
| cargo-semver-checks | 0.51.0 | make api-check (once a version is on crates.io) |
| cargo-fuzz and a nightly toolchain | 0.13.2 | the fuzz targets |
| Python | 3.12 | the pinned server, scripts/*.py |
uv (or python3 -m venv) |
any | installing the server |
Node.js (for npx), codespell, reuse |
22, 2.4.x, 6.x | make docs-lint |
rustup toolchain install stable 1.85.0 --component clippy,rustfmt,llvm-tools-preview
cargo install --locked cargo-deny@0.20.2 cargo-llvm-cov@0.9.1 rust-code-analysis-cli@0.0.25
The devcontainer
has all of these at the same versions. pre-commit install runs the fast
checks on every commit (.pre-commit-config.yaml, local hooks only).
The gates¶
make check runs what CI's static jobs run; make regression runs
everything, against a server it starts. Each CI job maps to a target:
| CI job | Local command | What it checks |
|---|---|---|
| Format and lint | make fmt-check lint doc |
rustfmt; clippy with -D warnings and the cognitive-complexity and length lints, with all features and with none; rustdoc with warnings denied |
| Build and unit tests (stable, 1.85.0) | make build test |
every target, benches included, on stable and the floor |
| Coverage | make coverage |
100% of lines and regions in src/, or it fails |
| Complexity ceilings | make complexity |
cyclomatic 10, cognitive 15, Halstead difficulty 30, 60 lines per function, 500 per file |
| Versions, package contents and API breakage | make versions package-check api-check |
every version restatement; what the crate ships; cargo-semver-checks |
| Dependency policy | make deny |
RustSec advisories, licences, bans, sources |
| Conformance kit against pain001 serve | make conformance and make bench-smoke with PAIN001_BASE_URL |
the kit, the typed tests, every example, every benchmark once |
| Docs lint | make docs-lint |
markdownlint, codespell, REUSE |
| Manual | make manual |
MkDocs strict build, API reference, link check |
| Fuzz | see Fuzzing | 30 seconds per target from the seeds |
| CodeQL, Scorecard, DCO | none locally | static analysis, supply chain, Signed-off-by |
Coverage¶
make coverage runs cargo-llvm-cov over the unit and integration tests
and fails below 100% of lines or of regions. The unit tests reach 100%
on their own; the live tests skip without a server. The cfg(fuzzing)
decoding module (src/fuzzing.rs) is compiled for unit tests and
counted. There are no exclusions: no coverage(off) attributes and
no ignored files.
llvm-cov counts a generic function by its best single instantiation, so
a test that covers an error path of a generic function has to use a type
whose instantiation also covers the success path (see
a_body_that_cannot_be_encoded_is_a_decode_error_and_is_not_sent).
Against a live server¶
uv venv /tmp/pain001-server
uv pip install --python /tmp/pain001-server/bin/python \
--require-hashes -r ci/server-requirements.txt
/tmp/pain001-server/bin/pain001 serve --host 127.0.0.1 --port 8000 &
PAIN001_BASE_URL=http://127.0.0.1:8000 make conformance
Start the server with PAIN001_API_KEY=<key> and export the same
variable to exercise the API key path, as CI does. make regression does
all of this itself: it installs the server into a temporary venv (or uses
PAIN001_SERVER), starts it on a free loopback port with a random key,
runs make check, make conformance and make bench-smoke, and stops
the server and removes the venv even when a step fails.
ci/server-requirements.txt pins the latest released pain001
(ci/server-requirements.in), hash-locked; regenerate it with the
command in the .in file's header.
Fuzzing¶
cargo +nightly fuzz run response fuzz/corpus/response fuzz/seeds/response -- -max_total_time=60
cargo +nightly fuzz run error fuzz/corpus/error fuzz/seeds/error -- -max_total_time=60
A crash lands in fuzz/artifacts/: fix the cause, add a unit test in the
main crate, and add the input to fuzz/seeds/.
Benchmarks¶
make bench runs both criterion benches; reports land in
target/criterion/. benches/client.rs needs no server;
benches/roundtrip.rs needs PAIN001_BASE_URL and skips without it.
scripts/record-bench-responses.sh re-records the response bodies the
client bench decodes. See BENCHMARKS.md.
Test layout¶
| Where | What | Needs a server |
|---|---|---|
src/** #[cfg(test)] modules, src/client/tests.rs, src/retry/tests.rs |
unit tests, against src/stub.rs, a one-request loopback stub |
no |
tests/conformance.rs |
core's conformance kit through Client::request, plus offline tests of the runner and the kit's SHA-256 sums |
for the kit |
tests/typed.rs |
one test per typed method, asserting fields | yes |
examples/*.rs |
one program per method; each exits non-zero on a wrong answer | yes |
benches/*.rs |
criterion, client-side and round trip | round trips only |
fuzz/ |
cargo-fuzz targets over response decoding and error mapping | no |
Release model¶
Versions advance by 0.0.1, in lockstep with the pain001 suite; the
maintainer opens a release. A release is prepared, then tagged by the
maintainer, and the release workflow
does the rest:
- On the release branch: rename
## [Unreleased]inCHANGELOG.mdto## [<version>] - <date>, writereleases/v<version>.md(two to four Highlights), and checkmake versions. - Run the workflow by hand first (Actions, Release, Run workflow): a dry run builds, packages, writes the SBOM and checksums, and prints what a release would carry.
- After the release pull request is merged, the maintainer creates and
pushes a signed annotated tag:
git tag -s v<version> -m "pain001-sdk-rust v<version>". - The tag runs the workflow: the GitHub release titled
pain001-sdk-rust <version>with the.crate, the CycloneDX SBOM andSHA256SUMS, provenance attestations, notes composed byscripts/release_notes.py, thencargo publishto crates.io. - Check the live release (
gh release view v<version> --json name,body) and the crate on crates.io and docs.rs.
The workflow is safe to re-run: assets are replaced, the notes rewritten, and a version already on crates.io is reported, not failed.
Settings the maintainer creates¶
None of these exist yet, and none are created by automation:
| Setting | Where | Why |
|---|---|---|
release environment |
Settings, Environments | the publish job runs in it; add a required reviewer |
| First publish of 0.0.88 | crates.io | crates.io registers a trusted publisher only for a crate that exists: publish 0.0.88 once by hand from the signed tag (cargo publish --locked), or set CRATES_IO_BOOTSTRAP_TOKEN (a scoped crates.io token) as a release environment secret for that one run, then delete it and revoke the token |
| Trusted publisher | crates.io, pain001-sdk, Settings, Trusted Publishing |
repository sebastienrousseau/pain001-sdk-rust, workflow release.yml, environment release |
| GitHub Pages | Settings, Pages, Source: GitHub Actions | the manual's deploy job |
PAGES_ENABLED = true |
Settings, Variables, Actions | turns the manual's deploy job on once Pages is enabled |
| OpenSSF Best Practices badge | bestpractices.dev | clears Scorecard's CIIBestPracticesID alert |
Writing code here¶
Read AGENTS.md
and CONTRIBUTING.md.
In short: no unsafe, no logging of request or response bodies, no
retries of a POST, no new runtime dependency without a reason, tests in
the same commit, and every commit signed off (git commit -s).