Architecture¶
pain001-sdk-java is a thin, typed client for the pain001 REST API
(pain001 serve). This page is the map for contributors: what each part
does, how a call flows, and where the guarantees are enforced.
The shape¶
caller ──► Pain001Client ──► java.net.http.HttpClient ──► pain001 serve
│ typed method builds the JSON body (package-private helpers)
│ request(): send, optional RetryPolicy for GET, parse leniently
│ checked(): non-2xx ──► Pain001ApiException / GenerationRefusedException
▼
records (HealthResponse, ValidationResponse, GenerateResponse, ...)
▲
Json: the one place Jackson is used (parse, write, lenient field access)
There is no payment logic here (ADR 0001). The server generates and validates; the SDK sends and maps.
Source layout¶
| Path | What it holds |
|---|---|
src/main/java/com/pain001/sdk/Pain001Client.java |
The client, its builder, every typed method, the raw request, the retry loop |
src/main/java/com/pain001/sdk/RetryPolicy.java |
The opt-in retry policy: which answers are retried, the backoff, Retry-After |
src/main/java/com/pain001/sdk/Json.java |
Package-private Jackson wrapper: lenient parse, write, tolerant field readers |
src/main/java/com/pain001/sdk/*Response.java, RowError, CheckFinding, FaceInfo, LossReport |
Immutable records, each with a package-private from(JsonNode) decoder |
src/main/java/com/pain001/sdk/*Exception.java |
The error model (ADR 0003) |
src/main/java/com/pain001/sdk/MessageType.java |
Constants for the 13 message types; methods take strings so newer types work |
src/test/java/ |
Unit tests (stub servers on loopback), the kit runner, live tests |
src/fuzz/java/, src/fuzz/resources/ |
Jazzer fuzz tests and their committed seeds |
src/bench/java/, src/bench/resources/ |
JMH benchmarks (profile bench) and the recorded responses they decode |
examples/ |
One runnable program per method, run against a server in CI |
conformance/ |
Core's conformance kit, vendored byte for byte |
A call, step by step¶
- A typed method (
validate, say) builds its JSON body with a package-private helper (filePayload,checkPayload,facePayload) and callsrequest. buildRequestsetsAccept,Content-Typewhen there is a body,User-Agent: pain001-sdk-java/<version>, the bearer token when an API key is configured, and the per-request timeout. Redirects are never followed, so the key never goes to another host.requestsends it. With aRetryPolicyand aGET, a connection failure, timeout, 429 or 503 is retried after the policy's wait (ADR 0004); otherwise the first answer is final.- The body is parsed leniently: empty becomes JSON null, non-JSON (a proxy's HTML page) is kept as a JSON string.
- A typed method raises on a non-2xx status;
generatealso raisesGenerationRefusedExceptionfor a 422 refusal andNoDocumentExceptionfor a 2xx without XML. Then the record'sfromdecoder maps the tree, defaulting absent fields rather than failing, so a newer server's extra fields do not break an older SDK.
Where the guarantees are enforced¶
| Guarantee | Enforced by |
|---|---|
| The client agrees with the server | ConformanceTest runs every kit case against a live server in CI |
| Every typed method works end to end | TypedApiTest and make examples against a live server in CI |
| Hostile responses never escape the error contract | ClientResponseFuzzTest, ResponseDecodingFuzzTest (seeds in every build, 60 s fuzzing per PR) |
| 100 % line and branch coverage | JaCoCo check in mvn verify |
| Complexity ceilings | PMD (config/pmd/complexity.xml) in mvn verify |
| No warnings | javac -Xlint:all -Werror |
| Pinned supply chain | .mvn/checksums/, the enforcer plugin, actions pinned by SHA |
| Versions agree everywhere | scripts/verify-release-versions |
Extending¶
A new server endpoint becomes a typed method only once the kit has a case
for it; until then request reaches it. Add the method, its record with
a from decoder, a unit test against a stub server, a live test in
TypedApiTest, an example, and a benchmark in both benchmark classes.