Architecture¶
pain001-sdk-go is a thin, typed HTTP client for the pain001 REST API
(pain001 serve). The server does all the payment work; the client
encodes requests, sends them, and decodes the answers into Go types
and errors. This page is for contributors: where each concern lives
and how a call flows through it.
Layout¶
| Path | What it holds |
|---|---|
client.go |
Client, NewClient, the With* options, Request, and the transport loop (send, attempt, newRequest) |
methods.go |
One typed method per endpoint: Health, Validate, Generate, Check, Faces, ProjectFace, and the request bodies they send |
types.go |
Response types and the MessageType constants |
errors.go |
APIError, Issue, RefusalError and the mapping from a non-2xx body |
retry.go |
RetryPolicy, WithRetry, backoff and Retry-After parsing |
version.go |
Version and the User-Agent it produces |
doc.go |
Package documentation, rendered on pkg.go.dev |
internal/kit/ |
The conformance runner: loads conformance/cases.json, substitutes $file fixtures, checks status, equals, types and contains on JSON Pointers |
conformance/ |
Core's conformance kit, vendored byte for byte and pinned by SHA256SUMS |
examples/ |
One runnable program per method, run against a live server in CI |
*_test.go |
Unit tests against stub servers, live tests, fuzz targets, benchmarks and the size and Halstead gates |
testdata/ |
Fuzz regression inputs and the recorded responses the benchmarks decode |
scripts/ |
The release-version check, the coverage gate, the regression run, the API check and the release notes |
A call, end to end¶
caller ── Client.Generate(ctx, csv, ...) ─┐
│ methods.go: build filePayload
▼
Client.call ── Client.send ── per-call timeout (WithTimeout)
│
┌──────────┴───────────┐
│ attempt: │
│ newRequest: JSON, │
│ Accept, User-Agent, │
│ Authorization │
│ http.Client.Do │
│ read <= 64 MiB │
└──────────┬───────────┘
│ retrier.wait: GET only,
│ 429/503/connection error,
│ backoff or Retry-After
▼
Client.call: 2xx → json.Unmarshal into the type
else → newAPIError(status, body)
│
Generate: asRefusal(err) → *RefusalError on a
422 with success false;
2xx without XML → ErrNoDocument
Request shares send but skips call: it returns the status and the
body decoded with json.Number whatever the status, which is what the
conformance runner needs to compare numbers exactly.
Invariants¶
- No payment data leaves through errors or logs. The client logs
nothing.
APIError.Error()lists issue locations and messages, never the rejected input;RefusalError.Error()gives counts, never the findings. Two fuzz targets hold this. - Bounded resources. Each call has a deadline (30 seconds by default) and reads at most 64 MiB of response.
- One attempt unless asked. Retries need
WithRetryand apply to GET only (ADR 0004). - Standard library only.
go.modhas no requirements (ADR 0002). - Exported API is the breaking axis.
scripts/api-check.shruns gorelease against the last tag.
Tests and gates¶
- Unit tests run against
httpteststubs and a function transport, with no server, and cover 100% of statements (scripts/coverage.sh). - Live tests (
typed_test.go,conformance_test.go) and the examples run whenPAIN001_BASE_URLis set; CI sets it in the conformance job throughmake regression. size_test.goandhalstead_test.gohold the function-size and Halstead ceilings; gocyclo and gocognit hold the cyclomatic and cognitive ones.- Five fuzz targets feed arbitrary statuses and bodies through
Request, the typed methods and the error mapping.
Where the decisions are recorded¶
docs/adr/: the thin-client design, the dependency
policy, the error model and the retry policy.