not
5de8c1e292
## What & why The ACL was handed a **pinned zaaktype URL** (`Acl__Defaults__ZaaktypeUrl`) + informatieobjecttype URL. OpenZaak assigns those UUIDs at creation, so every stack had to seed the catalogus and then capture + inject the resulting URLs out of band (CI's `run-domain-check.sh`; the local `local-seed`→`acl.env` bootstrap from ADR-0020). Brittle, and a stale/placeholder URL failed opaquely (OpenZaak 400). Now **the ACL resolves them itself** from OpenZaak's Catalogi API by stable business key: - config `ZaaktypeIdentificatie` (`BIG-REGISTRATIE`) / `InformatieobjecttypeOmschrijving` (`Diploma`); - a `CachedZaaktypeCatalog` resolves **lazily on first use** and caches (success only, so a pre-publish miss is retried — no startup ordering coupling); - a clear "No published … found" error replaces the opaque placeholder 400. Design in **ADR-0021** (proposed in #117). Closes #113 Closes #117 ## Consequences (the payoff) No stack captures/injects a server-assigned URL any more — `docker-compose.yml`/`.local.yml`, `run-domain-check.sh` and `local-seed` all drop it; the local `acl.env` shrinks to a single line. **One thing S-27 can't remove** (confirmed empirically during this work): OpenZaak validates the `zaaktype` field on zaak-create with Django's URLValidator and **rejects a single-label host** (`http://openzaak:8000/…` → `zaaktype: bad-url`). So the ACL's **base URL** must still point at a URL-valid host (a container IP); that base-URL injection from ADR-0020 stays (local `acl.env` now carries only it; CI keeps `ACL_OPENZAAK_BASEURL`). ADR-0021 records this. ## Definition of Done - [x] Linked issues (#113 slice, #117 adr-proposal). - [x] TDD — resolver + gateway-lookup unit tests, updated `AclService` tests (50 unit tests green). - [x] Implementation makes them pass; refactor of both compose stacks + verify scripts follows. - [x] Conventional Commits referencing #113. - [ ] CI green — see below. - [x] `docker compose up` reaches green health — verified: fresh `make local` + `make verify-local` green with **no zaaktype-URL injection**; `acl.env` is base-URL-only. - [x] Docs — ADR-0021 + demo-script S-27 note. - [x] ADR added (ADR-0021). - [x] Demo note appended. ## Verification done locally - **50 unit tests** pass (resolver resolve/cache/retry-on-failure; gateway match/miss/blank-key; all `AclService` paths). - **6 ACL integration tests** pass against a live seeded OpenZaak — incl. resolving the zaaktype + Diploma iot by business key, and a clear error for an unknown identificatie. - **Fresh `make local` + `make verify-local`**: full flow (submit → werkbak → openbaar) green; `acl.env` = `Acl__OpenZaak__BaseUrl` only. - `make lint` clean; ACL mutation ratchet run locally (see checks). ## Notes for reviewers - `IZaakGateway` gains two resolve methods; `AclService` depends on the new `IZaaktypeCatalog` (singleton, so the cache persists). - Supersedes the pinned-URL mechanism; ADR-0021 documents that ADR-0020's `seed-env`/entrypoint shim are **simplified** (base-URL only), not deleted, because of the URLValidator constraint above. Reviewed-on: #118
4.0 KiB
4.0 KiB
ADR-0021: The ACL resolves its zaaktype by identificatie, not a pinned URL
- Status: Accepted
- Date: 2026-07-22
- Deciders: Respellion engineering
- Relates to: S-27 (#113), proposed in #117. The cleaner design deliberately split out of S-B04 (#110, ADR-0020), which fixed the local stack with an infra-only bootstrap.
Context
The ACL was handed a pinned zaaktype URL (Acl__Defaults__ZaaktypeUrl) and diploma
informatieobjecttype URL. OpenZaak assigns those UUIDs at creation, so the URL is not knowable when
the compose file is written — every stack had to seed the catalogus and then capture + inject the
resulting URLs out of band: run-domain-check.sh for CI, and the local-seed → acl.env bootstrap
(ADR-0020) for make local. Brittle, and a stale/placeholder URL failed opaquely (OpenZaak 400).
Decision
The ACL resolves its zaaktype (by identificatie) and diploma informatieobjecttype (by
omschrijving) from OpenZaak's Catalogi API, instead of being handed the URLs.
- Config:
AclDefaults.ZaaktypeUrl/InformatieobjecttypeUrl→ZaaktypeIdentificatie(BIG-REGISTRATIE) /InformatieobjecttypeOmschrijving(Diploma). - Lookup (gateway, §8.1):
GET /catalogi/api/v1/zaaktypen?status=definitief&identificatie=…→ the published zaaktype URL;GET /catalogi/api/v1/informatieobjecttypen?status=definitiefmatched onomschrijving. Reuses the gateway's existing catalogus-query machinery. - Timing = lazy + cached (
CachedZaaktypeCatalog). Resolve on first use (first zaak open / document store) and cache for the process lifetime. Lazy avoids a startup ordering coupling — the ACL never crash-loops when it boots before the catalogus is published. A failed resolution is not cached, so it is retried on the next call (e.g. once the zaaktype is published); a restart re-resolves. - Failure mode: no published match → a clear "No published zaaktype with identificatie '…' found in OpenZaak — is the BIG catalogus seeded and published?" error, replacing the opaque placeholder 400.
Consequences
Positive
- No stack captures or injects a server-assigned URL any more:
run-domain-check.shdrops theACL_ZAAKTYPE_URL/ACL_INFORMATIEOBJECTTYPE_URLcapture+inject,docker-compose.yml/.local.ymldrop the placeholder URL env, andlocal-seed/acl.envshrink to a single line. The ACL self-configures from the catalogus it already talks to. - The failure mode is legible (a named error instead of a 400 on a zeros-UUID).
Negative / costs
- The ACL still needs its OpenZaak BaseUrl pointed at a URL-valid host (a container IP), so
the base-URL injection from ADR-0020 stays (the local
acl.envnow carries only that; CI keepsACL_OPENZAAK_BASEURL). This is not something S-27 can remove: OpenZaak validates thezaaktypefield on zaak-create with Django's URLValidator and rejects a single-label host (http://openzaak:8000/…→zaaktype: bad-url, "Voer een geldige URL in.", confirmed empirically). So ADR-0020'sseed-envvolume + ACL entrypoint shim are simplified, not deleted. - New branching in the gateway/resolver → unit + integration test surface; the mutation ratchet covers it (§5).
- A seed step still creates + publishes the zaaktype (this ADR changes only discovery). Reaching OpenZaak's Catalogi API to seed likewise needs the IP host (its query params hit the same URLValidator) — unchanged from before.
Alternatives considered
- Resolve at startup (eager). Simpler cache, but reintroduces the ordering coupling (crash-loop if the catalogus isn't published yet). Rejected in favour of lazy.
- Per-request resolution (no cache). No stale-cache risk, but a Catalogi lookup on every ACL operation. Rejected; a process-lifetime cache with restart-to-refresh is enough here.
- Keep the pinned URL (status quo / ADR-0020 only). Rejected — the brittleness this ADR removes is exactly what S-27 was carved out to fix.