Changelog¶
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog,
and this project adheres to the pain001 suite's 0.0.x versioning: each
release moves by 0.0.1, in lockstep with the suite. The first release
is 0.0.88, the first published to Maven Central.
[0.0.88] - 2026-11-14¶
Highlights¶
- On Maven Central: the first release,
com.pain001:pain001-sdk0.0.88, signed, with a CycloneDX SBOM,SHA256SUMSand build provenance. - Opt-in retries:
RetryPolicyretriesGETcalls on connection failures, 429 and 503, honouringRetry-After;POSTis never retried. - A returned
generatealways has the XML: a 2xx without it now raisesNoDocumentExceptioninstead of passing silently. - Proven, measured and documented: 100 % line and branch coverage enforced, a runnable example and JMH benchmarks for every method, and a user manual with the Javadoc.
Changed¶
- CI tests against pain001 0.0.88, the release this SDK ships with
(
ci/server-requirements.in). - The Maven release-signing public key is committed as
MAVEN-SIGNING-KEY.ascand documented indocs/packaging.md;KEYS.ascstays the SSH allowed-signers list for commits and tags. - The version is 0.0.88 everywhere (
pom.xml, now a release version,CITATION.cff,SECURITY.md,SUPPORT.md, the install snippets);scripts/verify-release-versionsfails CI on any mismatch. - The fuzz tests and their seeds moved from
src/test/tosrc/fuzz/(added as test roots, so Maven runs them as before). OpenSSF Scorecard's Fuzzing check skips every path undersrc/test/, so it scored 0 although the Jazzer tests ran on every build. -
The CI conformance job runs
make regression: the full gate, every kit case (none skipped), every example and the benchmark smoke run against a server on a free loopback port. Every workflow has a concurrency group. -
Tests run on JUnit 6.1.3 (was 5.14.4); it needs Java 17, the build's existing floor, and no test source changed. Jackson moves to 2.23.0 (was 2.22.4).
.mvn/checksumsre-recorded withmake lock.
Added¶
User-Agent: pain001-sdk-java/<version>on every request, and the public constantPain001Client.VERSION.- JMH benchmarks (profile
bench,src/bench/): request building and response decoding for every typed method, and a loopback round trip for every method;make bench, and a smoke run in CI.docs/BENCHMARKS.mdhas the method, environment and results. - JaCoCo coverage gate at 100 % line and branch in
mvn verify. - The release pipeline (
.github/workflows/release.yml): on tagv0.0.Nit verifies the tag and versions, builds reproducible jars, sources and Javadoc jars, a CycloneDX SBOM andSHA256SUMS, attests provenance, publishes to Maven Central through the Central Portal plugin with GPG signatures, and writes the GitHub release; aworkflow_dispatchdry run publishes nothing.make release-dry-runbuilds the same bundle locally. - An API breakage check (japicmp,
make api-check) against the last release on Maven Central, a no-op until the first one. - A user manual (MkDocs Material,
make manual) with the Javadoc (doclint all, warnings fail) under/api/, deployed to GitHub Pages frommain;docs/ARCHITECTURE.md,docs/COMPARISON.md,docs/BENCHMARKS.md,docs/ROADMAP.md,docs/packaging.md, four ADRs,DEVELOPMENT.md,GOVERNANCE.mdandSUPPORT.md. make regression(scripts/regression.sh): installs the pinned server whenPAIN001_SERVERis unset, runs everything CI runs against it, and always stops it.- REUSE compliance (
REUSE.toml,LICENSES/), codespell and an offline lychee link check in the docs-lint workflow;.editorconfig,.pre-commit-config.yamland a devcontainer. - One runnable example per part of the API in
examples/:Health,Validate,Check,Faces,ProjectFace,RawRequest,ErrorHandling,TimeoutsandApiKey, besideGenerateCreditTransfer.make examplesruns them all againstPAIN001_BASE_URL, and the CI conformance job does so on every push. RetryPolicy, an opt-in retry policy set withPain001Client.Builder.retryPolicy. It retriesGETcalls only (health,faces, andrequestwithGET) after a connection failure, a timeout, or HTTP 429 or 503, up tomaxAttempts(default 3), with exponential backoff and jitter (200 ms initial, 5 s maximum by default). ARetry-Afterheader is honoured exactly, and when it asks for longer thanmaxBackoffthe answer is returned rather than retried early.POSTis never retried. Without a policy the client sends every request once, as before.- A README demo,
.github/demo.gif, rendered bymake demofrom.github/demo.tape: the example program againstpain001 serveon loopback.make demotakes the server fromPAIN001_SERVERorPATH(seeCONTRIBUTING.md). examples/GenerateCreditTransfer.javanow also callshealthandvalidatebeforegenerate, printing one line per step.- Fuzz tests with Jazzer 0.30.0 (
jazzer-junit, test scope, running on JUnit 6.1.3):ResponseDecodingFuzzTestfuzzes the response-body parse and every record decoder, andClientResponseFuzzTestfuzzes every typed call against a loopback server answering an arbitrary status and body, checking the documented exceptions,detailand message. Their seeds run inmake check;make fuzzfuzzes, and a newFuzzworkflow fuzzes each target for 60 seconds on every pull request..mvn/checksumsre-recorded withmake lock. GenerationRefusedException, a subclass ofPain001ApiExceptionthatgenerateraises when the server refuses the data (HTTP 422 withsuccess: false, from pain001 0.0.87). Itsresponse()is the decodedGenerateResponse, so the caller gets the row errors and scheme violations;detail()is JSON null because that body has nodetail. A 200 fromgeneratenow always carries the XML.-
Conformance kit 2 from pain001 0.0.87: 14 cases, adding
generate-refused-rows,generate-refused-scheme,validate-bad-leiandvalidate-chaps-purpose-required, and the fixtures they read. -
Pain001Client, a typed client for the pain001 REST API built onjava.net.http.HttpClient:health,validate,generate,check,faces,projectFace, and the rawrequestthe conformance runner uses. Configured with a builder (base URL, optional API key sent as a bearer token, timeout). No retries, no logging of bodies. - Response records (
HealthResponse,ValidationResponse,GenerateResponse,RowError,CheckResponse,CheckFinding,FaceInfo,FaceResponse,LossReport,ApiResponse),MessageTypeconstants for the 13 message types, andPain001ApiExceptioncarrying the HTTP status and the parseddetail. conformance/, the SDK conformance kit vendored byte for byte from core, pinned byconformance/SHA256SUMS; a JUnit runner that executes every case throughrequest, typed tests per method, and unit tests against a stub HTTP server.examples/GenerateCreditTransfer.java, which writes a pain.001.001.09 file from the kit's credit-transfer fixture.- CI on Java 17 and 21 with PMD complexity ceilings, a conformance job
against
pain001 serve0.0.86 from hash-pinned requirements, DCO and Markdown lint, and the suite's community files.
Fixed¶
generatereturned aGenerateResponsewithout the XML when a 2xx answer hadsuccessnot true or noxml, which is what a server older than pain001 0.0.87 sends for a refused file; its Javadoc promised the XML. It now raises the newNoDocumentException, anUncheckedIOException(a broken reply, not a refusal), as the Go SDK returnsErrNoDocumentand the C++ SDK throwsNoDocument. AClientResponseFuzzTestseed pins it.