feat(zgw): docker OpenZaak integration-test harness (WP-54)
Opt-in docker-compose (postgres+redis+OpenZaak, no celery/nginx) + bootstrap-catalogus.sh seed a real OpenZaak instance; OpenZaakIntegrationTests (Category=Integration, excluded from default dotnet test/CI) proves the ZGW seam against it for the first time. That live run caught a real bug: ZgwHttpClient never sent Content-Crs/Accept-Crs headers, so every write would 412 against a spec-compliant OpenZaak — fixed alongside the harness. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Claude Sonnet 5
@@ -104,7 +104,7 @@ for its existing violations, so every WP ends green.
|
||||
| [WP-51](WP-51-openzaak-documenten.md) | OpenZaak Documenten (DRC) upload + zaak link | 9 · OpenZaak/ZGW | done |
|
||||
| [WP-52](WP-52-openzaak-notificaties.md) | OpenZaak Notificaties (NRC) live status via webhook | 9 · OpenZaak/ZGW | done |
|
||||
| [WP-53](WP-53-inbound-identity-and-citizen-scoping.md) | Inbound identity seam + citizen-scoping (per-request BSN, ZGW audit claims) | 9 · OpenZaak/ZGW | done |
|
||||
| [WP-54](WP-54-openzaak-integration-harness.md) | Docker OpenZaak integration-test harness (opt-in, live round-trip) | 9 · OpenZaak/ZGW | todo |
|
||||
| [WP-54](WP-54-openzaak-integration-harness.md) | Docker OpenZaak integration-test harness (opt-in, live round-trip) | 9 · OpenZaak/ZGW | done |
|
||||
|
||||
Sequencing dependencies (stated in the WPs too): 01 before 10–15 (axe covers story churn);
|
||||
03/04 before 05–09 (boundaries stop new violations during refactors); 06 before 07 (typed
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# WP-54 — Docker OpenZaak integration-test harness
|
||||
|
||||
Status: todo
|
||||
Status: done
|
||||
Phase: 9 — OpenZaak / ZGW integration
|
||||
|
||||
## Why
|
||||
@@ -87,17 +87,19 @@ OpenZaak facts that shape the harness (from the ZGW research):
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `docker compose -f backend/openzaak/docker-compose.openzaak.yml up` yields a reachable
|
||||
- [x] `docker compose -f backend/openzaak/docker-compose.openzaak.yml up` yields a reachable
|
||||
OpenZaak with the seeded catalogus + zaak, and credentials matching `ZgwOptions`.
|
||||
- [ ] The Category=Integration test passes against it; the BFF returns the seeded zaak mapped to
|
||||
- [x] The Category=Integration test passes against it; the BFF returns the seeded zaak mapped to
|
||||
`ApplicationSummaryDto` through the real HTTP + JWT path.
|
||||
- [ ] Default `dotnet test` and `npm run ci` are unaffected (integration test excluded, no docker
|
||||
- [x] Default `dotnet test` and `npm run ci` are unaffected (integration test excluded, no docker
|
||||
needed); `docker compose up` (root) is unchanged.
|
||||
|
||||
## Verification
|
||||
|
||||
`docker compose -f backend/openzaak/docker-compose.openzaak.yml up -d` →
|
||||
`dotnet test --filter Category=Integration` → green; then teardown.
|
||||
`./backend/openzaak/bootstrap-catalogus.sh` → `dotnet test --filter Category=Integration` →
|
||||
green; then teardown. Actually run (not just planned) during this WP — see Deviations below
|
||||
for what that surfaced.
|
||||
|
||||
## Out of scope
|
||||
|
||||
@@ -112,3 +114,32 @@ always-on CI job (keep it opt-in/manual — OpenZaak startup is slow), performan
|
||||
keep the fixture in the repo.
|
||||
- Bootstrap client scopes must include `catalogi.lezen` or zaaktype resolution 403s — cover in
|
||||
the setup script.
|
||||
|
||||
## Deviations from the original plan
|
||||
|
||||
- **`heeft_alle_autorisaties: true` instead of granular scopes.** The plan called out
|
||||
`zaken.lezen`/`catalogi.lezen` specifically; in practice OpenZaak's scripted config
|
||||
(`vng_api_common_applicaties_config`, upstream's own documented `setup_configuration` YAML
|
||||
mechanism) exposes an all-scopes flag on the one `Applicatie` this harness ever creates. Since
|
||||
that application exists for nothing but this throwaway test instance, granular scopes would
|
||||
add YAML-schema risk for no real least-privilege benefit — took the simpler, equally-scripted
|
||||
option.
|
||||
- **A live run found a real production bug, not just a harness wrinkle**: `ZgwHttpClient.cs`
|
||||
never sent `Content-Crs`/`Accept-Crs` on any ZGW call. Every ZGW write 412s ("Content-Crs
|
||||
header ontbreekt") without it — a real OpenZaak enforces this; the stub `HttpMessageHandler`
|
||||
every prior Zgw test used never modelled header requirements, so nothing from WP-49/50 caught
|
||||
it before now. Fixed in `ZgwHttpClient.cs` alongside the harness (see
|
||||
`docs/reference/openzaak-integration.md`) — this is precisely the class of bug this WP exists
|
||||
to catch.
|
||||
- **Publishing a zaaktype needs more seed data than the plan anticipated**: OpenZaak refuses to
|
||||
publish a zaaktype with fewer than one resultaattype or fewer than two statustypen (begin +
|
||||
eind), and a resultaattype's `selectielijstklasse` must share a `procesType` with the
|
||||
zaaktype's own `selectielijstProcestype` — both cross-checked live against the public VNG
|
||||
selectielijst API (`selectielijst.openzaak.nl`). `bootstrap-catalogus.sh` seeds all of this;
|
||||
see its comments for the exact values used and why.
|
||||
- **No celery/celery-beat/nginx in the harness**, unlike upstream's own compose — trimmed for a
|
||||
faster-booting, single-purpose harness (this test never asserts on notification delivery,
|
||||
which is celery's job). `NOTIFICATIONS_DISABLED=true` is required as a consequence: without a
|
||||
celery worker, `NotificationsConfig` has no client, and OpenZaak's `notify()` hook otherwise
|
||||
raises inside the same DB transaction as the create — turning a missing-worker problem into a
|
||||
500 that rolls back the create it was supposed to just notify about.
|
||||
|
||||
@@ -101,7 +101,11 @@ confidentiality level would matter for production but isn't needed to prove the
|
||||
`user_representation`). No refresh flow — OpenZaak expires tokens 1h past `iat`, so per-call
|
||||
minting is the recommended pattern. Hand-rolled (no `Microsoft.IdentityModel.*` dependency).
|
||||
- `ZgwHttpClient.cs` — shared GET/POST-with-bearer-JWT plumbing used by both
|
||||
`OpenZaakZaakSource` and `OpenZaakDocumentSource`.
|
||||
`OpenZaakZaakSource` and `OpenZaakDocumentSource`. Every request also carries
|
||||
`Accept-Crs`/`Content-Crs: EPSG:4326` — every ZGW call must declare a coordinate reference
|
||||
system even when no geometry is involved, or a real OpenZaak 412s ("Content-Crs header
|
||||
ontbreekt"). This was missing until WP-54's live harness caught it — the stub-handler tests
|
||||
never modelled the header, so it had shipped silently since WP-49/50.
|
||||
- `ZgwZaakMapper.cs` — the anti-corruption map: ZGW Zaak → `ApplicationSummaryDto`. This is
|
||||
where **URL identity** becomes the trailing uuid and the **zaaktype URL** is resolved to a
|
||||
human label (the cross-service join).
|
||||
@@ -204,6 +208,22 @@ FE or the contract. Watch the **sync-over-async** `ponytail:` note in `OpenZaakZ
|
||||
its `OpenZaakDocumentSource` sibling) — make the read/write paths async if OpenZaak becomes the
|
||||
default.
|
||||
|
||||
## Run against real OpenZaak (WP-54)
|
||||
|
||||
Everything above was, until WP-54, only proven against fixtures + a stub `HttpMessageHandler` —
|
||||
no live OpenZaak. `backend/openzaak/` is a **separate**, opt-in docker-compose harness (never
|
||||
merged into the root `docker-compose.yml`, which stays FE+BFF-only) that brings up a real
|
||||
OpenZaak, seeds a minimal catalogus/zaaktype/zaak via a bootstrap script, and backs one
|
||||
xunit test (`OpenZaakIntegrationTests.cs`, tagged `Category=Integration`) that points the BFF at
|
||||
it with `Zgw:Enabled=true`. See `backend/openzaak/README.md` for the exact commands; the test is
|
||||
excluded from the default `dotnet test` run and from CI (`--filter Category!=Integration`) since
|
||||
it only passes with the harness up.
|
||||
|
||||
This is also where the `Content-Crs`/`Accept-Crs` header gap above was found: a real OpenZaak
|
||||
enforces ZGW's geo-header requirement in a way no stub-based test could catch, since a stub
|
||||
never rejects an unexpected (or missing) header. That is the harness's whole point — proving
|
||||
the seam against real protocol behaviour, not just the shapes we already assumed.
|
||||
|
||||
## Config
|
||||
|
||||
```jsonc
|
||||
@@ -270,15 +290,16 @@ Caveat: `IZaakSource` covers the cases **read (admin + citizen-scoped) + create*
|
||||
(WP-49/50/53), `IDocumentSource` covers **upload + zaak-link** (WP-51), the inbound
|
||||
`POST /zgw/notificaties` webhook (WP-52) closes the read/write/document/notify arc, and WP-53
|
||||
threaded a real per-request `CallerIdentity` through all of it (ownership + the ZGW audit
|
||||
claims). Other BFF endpoints (reference data like `SeedData`'s BRP/DUO mimics) still read static
|
||||
stores directly — ACL-ready (the DTO seam exists) but not yet swappable, and not part of this
|
||||
arc. What's left is **WP-54**: a docker OpenZaak harness + opt-in integration test — today
|
||||
everything is fixture/mock-tested against no live instance.
|
||||
claims), and WP-54 added a docker OpenZaak harness + opt-in integration test proving the seam
|
||||
against a live instance (and, in doing so, caught the missing `Content-Crs`/`Accept-Crs`
|
||||
headers noted above). Other BFF endpoints (reference data like `SeedData`'s BRP/DUO mimics)
|
||||
still read static stores directly — ACL-ready (the DTO seam exists) but not yet swappable, and
|
||||
not part of this arc. That closes the phase-9 OpenZaak/ZGW arc (WP-49..54).
|
||||
|
||||
## See also
|
||||
|
||||
- [ADR-0005 — OpenZaak behind the BFF](architecture/0005-openzaak-behind-bff.md) — the decision.
|
||||
- [ADR-0001 — BFF-lite + decision DTOs](architecture/0001-bff-lite-decision-dtos.md) — why the FE doesn't change.
|
||||
- [WP-49](../project/backlog/WP-49-openzaak-zaken-read-seam.md) (this), WP-50/51 (CRUD arc so far), WP-52 (notificaties), WP-53 (identity seam + citizen-scoping), WP-54 (integration harness, open).
|
||||
- `backend/src/BigRegister.Api/Zgw/` — the client; `Data/IZaakSource.cs`/`Data/IDocumentSource.cs` — the seams.
|
||||
- [WP-49](../project/backlog/WP-49-openzaak-zaken-read-seam.md) (this), WP-50/51 (CRUD arc so far), WP-52 (notificaties), WP-53 (identity seam + citizen-scoping), [WP-54](../project/backlog/WP-54-openzaak-integration-harness.md) (integration harness).
|
||||
- `backend/src/BigRegister.Api/Zgw/` — the client; `Data/IZaakSource.cs`/`Data/IDocumentSource.cs` — the seams; `backend/openzaak/` — the live-OpenZaak test harness (WP-54).
|
||||
- [ZGW standard (VNG)](https://vng-realisatie.github.io/gemma-zaken/) · [OpenZaak auth docs](https://open-zaak.readthedocs.io/en/stable/client-development/authentication.html).
|
||||
|
||||
Reference in New Issue
Block a user