Changelog¶
All notable changes to this project are documented in this file. The
format follows Keep a Changelog,
and versions advance in 0.0.1 steps in lockstep with the pain001 suite.
[0.0.88] - 2026-11-14¶
The first release will be 0.0.88, in lockstep with the pain001 suite. CI tests against pain001 0.0.87, the latest released server.
Added¶
Version, the module's release, and aUser-Agent: pain001-sdk-go/<Version>header on every request, so a server's access log shows which SDK and release sent a call.WithRetry(RetryPolicy{...}): opt-in retries for idempotent calls only (Health,Faces, andRequestwith GET). It retries a failed connection and a429or503, waits with exponential backoff and jitter or for the response'sRetry-After, and never retries a POST. Off by default, so a client without it behaves as before.pain001.NewClientwithWithAPIKey,WithHTTPClientandWithTimeout; typedHealth,Validate,Generate,Check,FacesandProjectFacemethods, each taking acontext.Context; andRequestfor any endpoint.*APIErrorfor non-2xx responses, carrying the status and the server'sdetail, withDetailTextandIssuesaccessors.MessageTypeconstants for the 13 message types pain001 0.0.85 serves.- The conformance kit (kit 2, from pain001 0.0.87: 14 cases, including
the
422generate refusals, a bad LEI and a CHAPS purpose code), vendored from core withSHA256SUMS, a runner for its cases, and typed tests against a live server. *RefusalError, returned byGeneratewhen the server refuses the data with422andsuccess: false(pain001 0.0.87 and later). It wraps the*APIError, soStatusstays 422 anderrors.Asfinds either type, and itsResponsecarries the decodedValidationErrorsandSchemeViolations. A nil error fromGeneratenow always comes with the XML.examples/basic, which generates pain.001.001.09 from the kit's credit-transfer fixture and prints each finding of a refusal.- One runnable program per method under
examples/:health,validate,basic(generate),check,faces,projectface,request,errors(*APIError,*RefusalError,ErrNoDocument),timeout,apikeyandretry.make examplesbuilds them all and runs each againstPAIN001_BASE_URL; each exits non-zero when the server does not answer as it expects.make conformanceruns them. - Benchmarks for every public method (
bench_test.go,make bench):BenchmarkClientmeasures the client's own request building and response decoding against responses recorded from pain001 0.0.87 (testdata/bench,scripts/record-bench-responses.sh), with no network;BenchmarkLivemeasures one loopback round trip toPAIN001_BASE_URL. CI smoke-runs both on every pull request. make regression(scripts/regression.sh): installs the pinned server into a temporary venv unlessPAIN001_SERVERis set, starts it on a free loopback port with a random API key, runsmake check(with the conformance kit, the live tests and every example) and the benchmark smoke against it, and stops it even on failure. CI's conformance job runs the same script.VULNDBpointsmake vulncheckat a local copy of the Go vulnerability database.- Fuzz targets for the client's handling of untrusted responses:
FuzzRequest,FuzzTypedMethods,FuzzAPIError,FuzzErrorOmitsRejectedInputandFuzzRefusalOmitsFindings, seeded from the conformance kit's responses.go testruns their seeds,make fuzzfuzzes each for a minute, and a CI job fuzzes each for 30 seconds on every push and pull request. ErrNoDocument:Generatenow returns an error wrapping it when a2xxresponse carries no XML (success: falseor an emptyxml), as a server older than pain001 0.0.87 sends for a refusal. It used to return that body with a nil error, against its documented promise that a nil error always comes with the XML. Found byFuzzTypedMethods.- CI: gofmt, vet, staticcheck, gocyclo, gocognit, race-enabled tests on
Go 1.26 and 1.27, and the conformance job against
pain001 serve0.0.87 installed from hash-pinned requirements. - CI: an API-breakage job (
scripts/api-check.sh, gorelease against the last tag, a no-op until the first tag exists), and the conformance job now runsmake regression, adding every example and the benchmark smoke against a server started with an API key. - A tag-triggered release workflow (
.github/workflows/release.yml) with aworkflow_dispatchdry run: it verifies the signed annotated tag and every version restatement, runs the tests and the API check, builds the source archive, a CycloneDX SBOM andSHA256SUMS(scripts/release-artifacts.sh), attests their provenance, writes the GitHub release in the suite's format (scripts/release-notes.sh, Highlights from.github/release-highlights.md), audits it, and publishes the module by warming proxy.golang.org. Safe to re-run. - REUSE compliance (
REUSE.toml,LICENSES/) and codespell (.codespellrc) in the Docs lint workflow, next to markdownlint;make docs-lintruns all three..editorconfig,.pre-commit-config.yaml(hooks that call the same make targets) and a.devcontainer/that boots to a workingmake check. Dependabot now watches the Python tool locks inci/(not the server pin) and the devcontainer features. - The user manual: MkDocs Material from
docs/(mkdocs.yml), built with--strictin CI and deployed to GitHub Pages by.github/workflows/docs.ymlonce Pages is switched on, with the author link on every page (scripts/check-site-footer.sh). New pages: a usage guide, the example index,ARCHITECTURE.md,COMPARISON.md(the suite's shared table with evidence links),BENCHMARKS.md(method, environment and measured numbers),POLICIES.md,ROADMAP.md,packaging.md, and ADRs 0001 to 0004 (thin client, standard library only, error model, opt-in retries). RootDEVELOPMENT.md(every CI gate reproduced locally, test layout, release model, settings the maintainer creates) andGOVERNANCE.md(roles, decisions, continuity plan). - The README follows the workspace template in full: the suite's ecosystem comparison table, measured benchmark numbers, an example table covering every method, the five SDKs in the family map, and a registry badge that tracks the latest tag.
scripts/verify-release-versions, run bymake checkand CI: fails whenversion.go,CITATION.cff, theSECURITY.mdandSUPPORT.mdsupport tables, a Markdown install snippet or theCHANGELOG.mdheading disagree, or when the server pin and its lock name different pain001 releases.--releasealso requires the dated release heading.- A 100.0% statement-coverage floor:
make testrunsscripts/coverage.sh, which fails below it, on both Go versions in CI.halstead_test.goholds every function to a Halstead difficulty of 30, the last of the workspace's complexity ceilings without a gate. SUPPORT.md: where to ask, what to include, and which versions get fixes.- The README demo,
.github/demo.gif, rendered bymake demofrom.github/demo.tapewith vhs: the typed live tests andexamples/basicagainst apain001 servethe tape starts on loopback. CONTRIBUTING.md shows how to install the pinned server for it.
Fixed¶
Requestreported a body with data after its first JSON value (000,{"a":1} trailing,0followed by a form feed) as that value with no error, so a garbled response passed the conformance runner while the typed methods rejected it. It now returns an error for anything but JSON whitespace after the value. Found byFuzzRequest.
Changed¶
- CI tests against pain001 0.0.88, the release this SDK ships with
(
ci/server-requirements.in).