Contributing¶
Thanks for looking. This SDK is a thin client: it sends requests to the
pain001 REST API (pain001 serve) and maps the responses to Java
records. The payment logic lives in the server, in
pain001; change it
there.
Before you open a pull request¶
Everything CI checks, you can run locally with a JDK (17 or newer);
./mvnw fetches the pinned Maven and checks its SHA-256:
make check # whitespace format, file size, mvn -B verify, example compile
mvn -B verify compiles with -Xlint:all -Werror, runs the unit tests
(a stub HTTP server, no network) and fails on any PMD complexity
violation (cyclomatic 10, cognitive 15, 60 statements per method,
config/pmd/complexity.xml).
Maven refuses any dependency or plugin whose SHA-256 is not recorded in
.mvn/checksums/ (see .mvn/maven.config). After changing a dependency
or plugin version, including a Dependabot bump, run make lock, review
the diff of .mvn/checksums/, and commit it with the change. make
audit builds a CycloneDX SBOM and checks it with
OSV-Scanner, as CI does.
To run the conformance kit and the typed tests, start a server and point the tests at it:
pip install 'pain001[api]==0.0.88'
pain001 serve --host 127.0.0.1 --port 8000 &
PAIN001_BASE_URL=http://127.0.0.1:8000 make conformance
PAIN001_BASE_URL=http://127.0.0.1:8000 make example
Without PAIN001_BASE_URL those tests skip, and say so.
The README demo¶
.github/demo.gif is rendered from .github/demo.tape by make demo,
never recorded by hand. It needs vhs
(with ttyd and ffmpeg) and a pain001 server binary, taken from
PAIN001_SERVER or, if that is unset, from PATH; make demo stops
with an error when neither is there. Install the server the way CI
does, hash-pinned:
uv venv /tmp/pain001-srv
uv pip install --python /tmp/pain001-srv/bin/python --require-hashes -r ci/server-requirements.txt
PAIN001_SERVER=/tmp/pain001-srv/bin/pain001 make demo
The tape starts pain001 serve on 127.0.0.1:18767 in a temporary
directory, runs examples/GenerateCreditTransfer.java against it with
the kit's synthetic CSV, and stops the server. Nothing leaves the
loopback interface. Re-render the GIF in the same change whenever the
example's output changes.
What the tests are for¶
Pain001ClientTest: request shape, response mapping and error mapping against a stub server.ConformanceKitTest: the kit runner itself (JSON Pointer,$file, every kind of failure).KitChecksumTest:conformance/is byte for byte whatconformance/SHA256SUMSpins.ConformanceTest: every case inconformance/cases.jsonthroughPain001Client.request, against a live server.TypedApiTest: one test per typed method, against a live server.ResponseDecodingFuzzTestandClientResponseFuzzTest(insrc/fuzz/java/): Jazzer fuzz tests for what a server sends back. The first feeds arbitrary bytes to the lenient parse and every record decoder; the second answers every typed call from a loopback server with an arbitrary status and body, and checks that onlyPain001ApiException(orGenerationRefusedException, orNoDocumentExceptionfor a 2xxgeneratewithout XML) escapes, with the status, the body'sdetail, and a message that never contains the body.
Fuzzing¶
The fuzz tests live in src/fuzz/java/ and their committed seeds in
src/fuzz/resources/com/pain001/sdk/<Test>Inputs/; the build adds both
as test roots, so mvn verify runs every seed as an ordinary
regression test. They are outside src/test/ because OpenSSF
Scorecard's Fuzzing check ignores everything under src/test/. To fuzz:
make fuzz # each target for 60 s
make fuzz FUZZ_TARGETS=ClientResponseFuzzTest FUZZ_TIME=10m
The generated corpus goes to .cifuzz-corpus/ (ignored). Jazzer
always writes a finding as crash-<sha1> under
src/test/resources/com/pain001/sdk/<Test>Inputs/<method>/ (the path
is fixed in Jazzer). Move it to the same path under
src/fuzz/resources/ and commit it with the fix, so it stays a
regression test. CI fuzzes each target for 60 seconds on every pull
request and uploads any finding.
The conformance kit¶
conformance/ is vendored from core, byte for byte. Do not edit it
here. To move to a new kit, copy core's conformance/ at the matching
version over this one, then regenerate the pins:
cd conformance
find . -type f ! -name SHA256SUMS | sed 's|^\./||' | LC_ALL=C sort \
| xargs shasum -a 256 > SHA256SUMS
Update ci/server-requirements.in to the same core version and
regenerate ci/server-requirements.txt with the command in its header.
Commits¶
Conventional commits, with a body that says why. Every commit is signed
off (git commit -s, see DCO.txt).
Versioning¶
The version lives in pom.xml, Pain001Client.VERSION, CITATION.cff,
the SECURITY.md and SUPPORT.md tables and the install snippets, with
a ## [0.0.N] heading in CHANGELOG.md; scripts/verify-release-versions
fails when any of them disagrees. Versions increment by 0.0.1, in lockstep
with the pain001 suite. 0.1.0 follows 0.0.999, not 0.0.9.
Licence¶
Apache-2.0 OR MIT, at your option. By contributing you agree your work is released under the same dual grant.