eho/atomic-design-poc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(openzaak): bounded retry + flagged write divergence (WP-60)

Browse Source 
Local aanvraag/document writes and their paired ZGW writes aren't
transactional; a ZGW failure after the local write succeeds used to
diverge silently. ZgwHttpClient now retries transport-shaped failures
(not 500, which can follow a partial commit on the non-idempotent
statussen/rollen POSTs), and a ZGW failure that survives retry sets
Aanvraag.ZgwError plus a zgw:divergence audit row instead of failing
or diverging quietly. No outbox/reconcile job: three request-triggered
write paths don't justify a persisted queue that would also need to
carry citizen PII for the JWT audit claims.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
eho
2026-07-30 18:11:55 +02:00
co-authored by Claude Sonnet 5
parent 67abc58052
commit 3ff80c124f
18 changed files with 855 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/project/backlog/README.md
+9 -10
View File
@@ -110,7 +110,7 @@ for its existing violations, so every WP ends green.
| [WP-57](WP-57-openzaak-least-privilege-scopes.md) | Least-privilege client scopes | 10 · OpenZaak hardening | done |
| [WP-58](WP-58-openzaak-notifications.md) | Real notifications (celery + scripted abonnement) | 10 · OpenZaak hardening | done |
| [WP-59](WP-59-document-confidentialiteit-config.md) | Per-document-type confidentialiteit config | 10 · OpenZaak hardening | done |
| [WP-60](WP-60-write-divergence-resilience.md) | Write-divergence resilience (local + ZGW writes) | 10 · OpenZaak hardening | todo |
| [WP-60](WP-60-write-divergence-resilience.md) | Write-divergence resilience (local + ZGW writes) | 10 · OpenZaak hardening | done |
| [WP-61](WP-61-behandelportal-bootstrap.md) | Bootstrap the behandelportal app | 11 · Behandelportal | todo |
| [WP-62](WP-62-medewerker-identity-authz.md) | Backend: medewerker caller identity + authz seam | 11 · Behandelportal | todo |
| [WP-63](WP-63-aanvraag-status-lifecycle.md) | Backend: aanvraag status lifecycle as a published DTO | 11 · Behandelportal | todo |
@@ -149,17 +149,16 @@ deployment of 49–52) and **54** (a docker OpenZaak harness + opt-in integratio
CRUD arc and can land any time; 54 depends on 49 (something to read) and unlocks realistic
testing for the rest. Both are self-contained (each WP file carries its own current-state
handoff) and sized for a fresh Sonnet session.
Phase 10 (OpenZaak production hardening, WP-55..60) and Phase 11 (Behandelportal,
WP-61..66) are two independent tracks that can be worked concurrently — neither blocks
the other. Within phase 10: 55/59/60 are fully independent; 57 and 58 both build on 56's
provisioning mechanism, otherwise independent of each other. Within phase 11: 61
Phase 10 (OpenZaak production hardening, WP-55..60 — now **done**) and Phase 11
(Behandelportal, WP-61..66) are two independent tracks that can be worked concurrently —
neither blocks the other. Within phase 10: 55/59/60 were fully independent; 57 and 58 both
built on 56's provisioning mechanism, otherwise independent of each other. Within phase 11: 61
(bootstrap), 62 (backend medewerker identity), and 63 (backend status DTO) are
independent of each other and can land in any order; 64 needs all three (61 for the app
to exist, 62 for identity, 63 for the status it reads); 65 needs 64; 66 needs 65 and
benefits from — but doesn't strictly require — phase 10's WP-60 landing first (WP-66 is
a second, currently-unprotected write pair otherwise). WP-60 is the one slice in phase 10
sized for a `planner`-agent kickoff rather than direct implementation — its Decisions
block is deliberately left open (outbox vs. retry+reconcile).
to exist, 62 for identity, 63 for the status it reads); 65 needs 64; 66 needs 65 and — now
that WP-60 has landed (bounded retry + flagged divergence in `ZgwHttpClient`/`Program.cs`) —
inherits that retry for free, but must call `RecordZgwDivergence` on its own besluit write path
to get the flagging half too.
## WP template
docs/project/backlog/WP-59-document-confidentialiteit-config.md
+4 -4
View File
@@ -68,10 +68,10 @@ not "must every category be configured."
## Verification
`cd backend && dotnet test` (161/161 green, incl. the 2 new `OpenZaakDocumentSourceTests`
+ the new `StamdataValidationTests` reference entry); `dotnet format --verify-no-changes`
clean. Manual: `/beheer/stamdata` shows and edits the new table; an upload for a mapped
document type carries the mapped confidentiality level (test asserted).
`cd backend && dotnet test` (161/161 green, incl. the 2 new `OpenZaakDocumentSourceTests` plus
the new `StamdataValidationTests` reference entry); `dotnet format --verify-no-changes` clean.
Manual: `/beheer/stamdata` shows and edits the new table; an upload for a mapped document type
carries the mapped confidentiality level (test asserted).
## Out of scope
docs/project/backlog/WP-60-write-divergence-resilience.md
+36 -16
View File
@@ -1,6 +1,6 @@
# WP-60 — Write-divergence resilience (local + ZGW writes)
Status: todo
Status: done
Phase: 10 — OpenZaak production hardening
## Why
@@ -23,37 +23,57 @@ production.
## Decisions
Intentionally left open for kickoff — this is exactly the kind of ambiguous-root-cause,
multi-file design call the `planner` agent should make, not something pre-decided here.
Options to weigh at kickoff:
Picked **(b), narrowed further: bounded synchronous retry + flag, no reconcile job.** The
`planner` agent's kickoff review found the write side smaller than either option assumed:
- (a) an outbox table — write local + an outbox row in one local transaction, a background
worker drains the outbox to ZGW with retry.
- (b) a simpler synchronous retry-with-backoff at the call site, plus a reconciliation job
that periodically diffs local vs. ZGW state and flags/repairs divergence.
- The only ZGW writes are `OpenZaakZaakSource.CreateZaak` (zaak/status/rol, one POST sequence
per submit) and `OpenZaakDocumentSource.Upload`/`LinkToZaak` (DRC + zaakinformatieobject).
There is no standalone status-transition write path yet (that's WP-66) — Step 2 below is
corrected accordingly.
- Every path already does the local write first and never rolls it back on a ZGW failure — "the
ZGW half fails, local succeeded" is the only real scenario; the reverse can't happen.
- An outbox was rejected: three request-triggered write paths don't justify a persisted queue,
and a ZGW call's `CallerIdentity` (needed for the JWT's audit claims, WP-53) would mean PII
sitting in a new table — the "generic outbox framework" this WP's own Risks section warns
against.
- A reconcile job was judged unnecessary for the acceptance criteria: flagging (not silent
divergence) is sufficient, and repair is always possible on demand because a zaak's
`identificatie` equals the aanvraag's `Referentie` — no reconcile job ships in this WP.
Pick the smaller one that closes the gap — don't build a generic outbox framework if a
bounded retry+reconcile suffices for this POC's actual write volume.
Shipped: bounded retry (3 attempts, doubling backoff from 200ms) in `ZgwHttpClient` for
transport-shaped failures only (429/502/503/504/408 + connection errors/timeouts — deliberately
**not** 500, which can follow a partial commit on the non-idempotent `/statussen`/`/rollen`
POSTs); `Aanvraag.ZgwError` + a `zgw:divergence` audit row when a ZGW write still fails after
retry (`Program.cs`'s submit endpoint, two separate try/catches so a create-zaak failure doesn't
also skip the still-local document link); `OpenZaakDocumentSource.Upload` catches and logs
without a separate flag column (`DrcUrl == null` already means "not registered in ZGW yet").
Full reasoning + rejected sub-options: [openzaak-integration.md](../reference/openzaak-integration.md)'s
"Write resilience" section.
## Files
Likely `Data/ApplicationStore.cs`, a new reconciliation/outbox mechanism,
`Zgw/OpenZaakZaakSource.cs`, `Program.cs` (background job registration if needed).
`Zgw/ZgwHttpClient.cs` (retry), `Data/ApplicationStore.cs` (`ZgwError` column + migration),
`Program.cs` (submit endpoint rewire + `RecordZgwDivergence` + HttpClient timeouts),
`Zgw/OpenZaakDocumentSource.cs` (non-throwing upload). No new file for a mechanism — no
outbox/background worker shipped (see Decisions).
## Steps
1. Design review with the `planner` agent — pick outbox vs. retry+reconcile.
2. Implement the chosen mechanism for the create-zaak and status-transition write paths.
1. Design review with the `planner` agent — pick outbox vs. retry+reconcile. Done: retry+flag
(see Decisions).
2. Implement the chosen mechanism for the create-zaak and document (upload + link) write
paths — not "status-transition" as originally scoped here; that path doesn't exist yet
(arrives with WP-66).
3. Add a test that simulates a ZGW failure mid-write and asserts the system recovers
(retries successfully, or is left in a detectably-inconsistent-but-flagged state)
rather than silently diverging.
## Acceptance criteria
- [ ] A simulated ZGW failure after a successful local write no longer leaves permanent
- [x] A simulated ZGW failure after a successful local write no longer leaves permanent
silent divergence — either it retries to consistency or the divergence is
detectable/flagged.
- [ ] No new synchronous latency added to the happy path beyond what the chosen mechanism
- [x] No new synchronous latency added to the happy path beyond what the chosen mechanism
requires.
## Verification
docs/project/backlog/WP-66-behandelportal-openzaak-write.md
+7 -4
View File
@@ -62,8 +62,11 @@ Any further behandelportal screens beyond beoordeling.
## Risks
If Phase 10's WP-60 (write-divergence resilience) hasn't landed yet, this introduces a
second unprotected write pair — call this out explicitly if the two phases aren't
sequenced together in practice.
WP-60 (write-divergence resilience) has landed: bounded retry lives in `ZgwHttpClient`, so
this write pair inherits it automatically. It does **not** get the flagging half for free —
call `RecordZgwDivergence` (or the equivalent for whichever endpoint hosts the besluit write) on
this path's catch too, the same way `Program.cs`'s submit endpoint does for create-zaak/document
writes, or this becomes the "second, currently-unprotected write pair" WP-60's own scope note
anticipated.
Depends on: WP-65. Benefits from (but doesn't strictly require) WP-60.
Depends on: WP-65.