From 448896206f3e5e8d03c8878b57989c902acfefad Mon Sep 17 00:00:00 2001 From: Niek Otten Date: Fri, 28 Aug 2026 10:54:14 +0200 Subject: [PATCH] feat(infra): Objecten publishes register events to NRC (refs #152) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds the four pieces ADR-0028 deliberately left absent, and turns `NOTIFICATIONS_DISABLED` back off: - `objecten-celery`, a worker on the Objecten image (mirrors `oz-celery`), plus `CELERY_BROKER_URL`/`RESULT_BACKEND` on objecten-redis db 1 (db 0 is the cache). Without it `notifications_api_common` queues the send and nothing ever ships it. - An `nrc` service + `notifications_config` in Objecten's setup_configuration, reusing the `big-reference-seed` credential OpenZaak publishes with. - The `objecten` kanaal in NRC's setup_configuration — the name is fixed by the Objects API (`NOTIFICATIONS_KANAAL`), and publishing to an unregistered kanaal is what the failing check reported first. - `SITE_DOMAIN: objecten.local:8000` + an `objecten.local` network alias: NRC validates `hoofdObject`/`resourceUrl` with Django's URLValidator, which rejects a single-label host, so `objecten:8000` is refused with "Voer een geldige URL in." The alias keeps the dotted host resolvable so the URL still dereferences. ADR-0029 records it; ADR-0028's ceiling now points there. Makes `make verify-objecten-notifications` (dc9ca2c) pass. --- .../adr-0028-objecten-holds-the-register.md | 4 +- .../adr-0029-objecten-publishes-to-nrc.md | 107 ++++++++++++++++++ infra/docker-compose.local.yml | 37 +++++- infra/docker-compose.yml | 37 +++++- infra/objecten/setup_configuration/data.yaml | 17 +++ .../setup_configuration/data.yaml | 12 +- 6 files changed, 199 insertions(+), 15 deletions(-) create mode 100644 docs/architecture/adr-0029-objecten-publishes-to-nrc.md diff --git a/docs/architecture/adr-0028-objecten-holds-the-register.md b/docs/architecture/adr-0028-objecten-holds-the-register.md index 8f2321b..624eaed 100644 --- a/docs/architecture/adr-0028-objecten-holds-the-register.md +++ b/docs/architecture/adr-0028-objecten-holds-the-register.md @@ -119,8 +119,8 @@ every message was dropped on the floor — a delivery path that looks wired and - ponytail ceiling: Objecten emits no notifications, so nothing downstream can react to a register write yet. -- Upgrade path: S-19b (#150) needs those notifications to source the projection from - Objecten, and turns them on together with the broker, worker, kanaal and abonnement. +- **Lifted by ADR-0029** (S-19b-1, #152): broker, worker, `objecten` kanaal and + notifications config now exist, and `NOTIFICATIONS_DISABLED` is `false`. ## Consequences diff --git a/docs/architecture/adr-0029-objecten-publishes-to-nrc.md b/docs/architecture/adr-0029-objecten-publishes-to-nrc.md new file mode 100644 index 0000000..7320eca --- /dev/null +++ b/docs/architecture/adr-0029-objecten-publishes-to-nrc.md @@ -0,0 +1,107 @@ +# ADR-0029: Objecten publishes register events to NRC + +- **Status:** Accepted +- **Date:** 2026-08-14 +- **Deciders:** Respellion engineering +- **Slice:** S-19b-1 (#152), first of the S-19b (#150) split +- **Supersedes in part:** ADR-0028's "Objecten's notifications are off for this slice" + +## Context + +ADR-0028 put the authoritative register record in the Objecten API and had the ACL write +it on approval. It also switched Objecten's notifications **off** — deliberately, with a +stated ceiling: there was no broker, no worker, no `objecten` kanaal and no abonnement, so +turning the client side on alone would have produced a delivery path that looks wired and +drops every message. + +S-19b-2 (#153) wants the read projection sourced from register writes rather than +re-derived from ZGW zaak events. That needs the notifications to actually arrive. This ADR +builds the four missing pieces and lifts the ceiling. + +## Decision + +**Objecten publishes to the same NRC OpenZaak already publishes to, on the `objecten` +kanaal, delivered by its own Celery worker — provisioned declaratively on both sides, +exactly as ADR-0007 did for OpenZaak.** + +- **Objecten** (`infra/objecten/setup_configuration/data.yaml`): a `zgw_consumers` service + `nrc` (api_type `nrc`) plus a `notifications_config` step naming it, and + `NOTIFICATIONS_DISABLED: "false"` in both compose files. +- **NRC** (`infra/opennotificaties/setup_configuration/data.yaml`): an `objecten` kanaal + alongside `zaken`. +- **`objecten-celery`**: a worker container on the Objecten image (`/celery_worker.sh`), + mirroring `oz-celery`, with `CELERY_BROKER_URL`/`CELERY_RESULT_BACKEND` on + `objecten-redis` db 1 (db 0 is already the cache). + +### One NRC, one credential, one kanaal per publisher + +Objecten reuses the `big-reference-seed` client OpenZaak publishes with. NRC verifies its +JWT and authorizes it against OpenZaak's Autorisaties API (ADR-0007), which grants that +client `heeft_alle_autorisaties` — so no second credential and no publisher-specific +authorization is needed. A second NRC, or a second credential, would buy isolation this +reference application has no use for. + +The kanaal name is **not ours to choose**: the Objects API sends +`NOTIFICATIONS_KANAAL = "objecten"`. NRC rejects a publish to an unregistered kanaal +(`"Kanaal met deze naam bestaat niet"`), which is precisely what the failing check for this +slice reported first. Its filter set (`object_type`) matches the kenmerken the Objects API +sends, so an abonnement can narrow to one objecttype instead of receiving every write. + +### `SITE_DOMAIN: objecten.local:8000` — NRC rejects single-label hosts + +NRC validates a notification's `hoofdObject`/`resourceUrl` with Django's `URLValidator`, +which refuses a **single-label** host. Objecten builds those URLs from `objects.utils.get_domain` +(i.e. `SITE_DOMAIN`), so with the compose service name they read `http://objecten:8000/...` +and every publish is refused with `"Voer een geldige URL in."` + +`SITE_DOMAIN` is therefore set to a dotted host, and the `objecten` service carries an +`objecten.local` network alias so that host still **resolves in-network** — a subscriber +that follows `resourceUrl` reaches the record it points at (which S-19b-2 will do). A +dotted name that didn't resolve would trade one broken link for a quieter one. + +This is the same class of constraint as ADR-0028's "the ACL's Objecttypen base URL must +match Objecten's configured `api_root`": these modules put request-derived hosts into data +that another module then validates or dereferences. + +### A worker, not a synchronous send + +`notifications_api_common` only schedules the send on transaction commit. Without a worker +the task sits in redis forever and every register write is silently undelivered — the exact +half-wired state ADR-0028 refused to ship. No `beat` for Objecten: it is a publisher, not a +subscriber, and `nrc-beat` already drains NRC's delivery queue. + +## Verification + +`make verify-objecten-notifications` (`infra/run-objecten-notifications-check.sh`, in the +CI `verify-stack` job) registers an abonnement on the `objecten` kanaal pointing at a +throwaway webhook sink, writes a `RegisterRecord` exactly as the ACL does on approval, and +asserts the notification reaches the sink. That is the whole chain in one assertion: +Objecten → `objecten-celery` → NRC → `nrc-beat` → the callback. Any missing piece — broker, +worker, kanaal, notifications config — shows up as a non-delivery rather than as a green +config. + +## Consequences + +**Positive** + +- A register write is now observable by anything that subscribes, which is what S-19b-2 + (#153) needs to make the projection a cache of Objecten rather than a re-derivation of ZGW. +- ADR-0028's ceiling is lifted: the delivery path is proven end to end, not merely configured. + +**Negative / costs** + +- One more long-running container (`objecten-celery`) on an already memory-tight CI runner. +- A second publisher on the shared `big-reference-seed` credential — a credential rotation + now touches two modules. +- One more hand-kept host constant: `SITE_DOMAIN` and the `objecten.local` alias must stay + in step, in both compose files. +- ponytail ceiling: notification delivery has no dead-letter or alerting — a failed publish + is visible only in the worker log. +- Upgrade path: if undelivered register events start mattering, subscribe an audit sink or + read NRC's own delivery admin rather than building a retry layer here. + +## Coupling rules touched (CLAUDE.md §8) + +None bent. This is infrastructure between two upstream modules, over their documented +APIs; no service reaches another's database. §8.6 (idempotency at every event boundary) +applies to whatever consumes the new kanaal — S-19b-2's problem, not this slice's. diff --git a/infra/docker-compose.local.yml b/infra/docker-compose.local.yml index e35732b..8d65cfa 100644 --- a/infra/docker-compose.local.yml +++ b/infra/docker-compose.local.yml @@ -691,12 +691,21 @@ services: CACHE_AXES: objecten-redis:6379/0 DISABLE_2FA: "true" OTEL_SDK_DISABLED: "true" - # S-19a: Objecten refuses every write while its Notificaties config is absent - # (notifications_api_common raises rather than skipping, so POST /objects 500s). Objecten → - # NRC is not wired yet — there is no broker, worker, kanaal or abonnement for it — so turn - # notifications off rather than fake a delivery path that silently drops every message. - # S-19b (#150) sources the projection from Objecten and turns this back on for real. - NOTIFICATIONS_DISABLED: "true" + # NRC validates hoofdObject/resourceUrl with Django's URLValidator, which rejects a + # single-label host — so notifications built from `objecten:8000` are refused with + # "Voer een geldige URL in." SITE_DOMAIN fixes the host Objecten puts in its notifications + # (objects.utils.get_domain), and the `objecten.local` network alias below keeps that host + # resolvable in-network so a subscriber can actually fetch the record it points at (S-19b-2). + SITE_DOMAIN: objecten.local:8000 + IS_HTTPS: "no" + CELERY_BROKER_URL: redis://objecten-redis:6379/1 + CELERY_RESULT_BACKEND: redis://objecten-redis:6379/1 + # Publish register-record events to NRC on the `objecten` kanaal (S-19b-1, ADR-0029). The NRC + # service + notifications_config are provisioned by setup_configuration + # (infra/objecten/setup_configuration/data.yaml), and objecten-celery below actually sends + # them — notifications_api_common only queues the task. See ADR-0028 for why S-19a left this + # off until all four pieces existed. + NOTIFICATIONS_DISABLED: "false" RUN_SETUP_CONFIG: "true" command: /setup_configuration.sh volumes: @@ -721,6 +730,22 @@ services: start_period: 30s ports: - "8021:8000" + depends_on: + objecten-init: + condition: service_completed_successfully + networks: + cg: + aliases: + - objecten.local + + # The celery worker that actually delivers Objecten's notifications to NRC (S-19b-1, ADR-0029). + # notifications_api_common only schedules the send on transaction commit; without a worker the + # task sits in redis forever and every register write is silently undelivered. Mirrors oz-celery. + # No beat: Objecten is a publisher, not a subscriber — nrc-beat drains the delivery queue. + objecten-celery: + image: docker.io/maykinmedia/objects-api:${OBJECTS_TAG:-3.4.0} + environment: *objecten-env-local + command: /celery_worker.sh depends_on: objecten-init: condition: service_completed_successfully diff --git a/infra/docker-compose.yml b/infra/docker-compose.yml index 024e879..b703ad2 100644 --- a/infra/docker-compose.yml +++ b/infra/docker-compose.yml @@ -717,12 +717,21 @@ services: CACHE_AXES: objecten-redis:6379/0 DISABLE_2FA: "true" OTEL_SDK_DISABLED: "true" - # S-19a: Objecten refuses every write while its Notificaties config is absent - # (notifications_api_common raises rather than skipping, so POST /objects 500s). Objecten → - # NRC is not wired yet — there is no broker, worker, kanaal or abonnement for it — so turn - # notifications off rather than fake a delivery path that silently drops every message. - # S-19b (#150) sources the projection from Objecten and turns this back on for real. - NOTIFICATIONS_DISABLED: "true" + # NRC validates hoofdObject/resourceUrl with Django's URLValidator, which rejects a + # single-label host — so notifications built from `objecten:8000` are refused with + # "Voer een geldige URL in." SITE_DOMAIN fixes the host Objecten puts in its notifications + # (objects.utils.get_domain), and the `objecten.local` network alias below keeps that host + # resolvable in-network so a subscriber can actually fetch the record it points at (S-19b-2). + SITE_DOMAIN: objecten.local:8000 + IS_HTTPS: "no" + CELERY_BROKER_URL: redis://objecten-redis:6379/1 + CELERY_RESULT_BACKEND: redis://objecten-redis:6379/1 + # Publish register-record events to NRC on the `objecten` kanaal (S-19b-1, ADR-0029). The NRC + # service + notifications_config are provisioned by setup_configuration + # (infra/objecten/setup_configuration/data.yaml), and objecten-celery below actually sends + # them — notifications_api_common only queues the task. See ADR-0028 for why S-19a left this + # off until all four pieces existed. + NOTIFICATIONS_DISABLED: "false" RUN_SETUP_CONFIG: "true" command: /setup_configuration.sh # data.yaml is streamed into this external volume by infra/seed-config.sh before start. @@ -750,6 +759,22 @@ services: start_period: 30s ports: - "8021:8000" + depends_on: + objecten-init: + condition: service_completed_successfully + networks: + cg: + aliases: + - objecten.local + + # The celery worker that actually delivers Objecten's notifications to NRC (S-19b-1, ADR-0029). + # notifications_api_common only schedules the send on transaction commit; without a worker the + # task sits in redis forever and every register write is silently undelivered. Mirrors oz-celery. + # No beat: Objecten is a publisher, not a subscriber — nrc-beat drains the delivery queue. + objecten-celery: + image: docker.io/maykinmedia/objects-api:${OBJECTS_TAG:-3.4.0} + environment: *objecten-env + command: /celery_worker.sh depends_on: objecten-init: condition: service_completed_successfully diff --git a/infra/objecten/setup_configuration/data.yaml b/infra/objecten/setup_configuration/data.yaml index 9f1b858..ff259c4 100644 --- a/infra/objecten/setup_configuration/data.yaml +++ b/infra/objecten/setup_configuration/data.yaml @@ -18,6 +18,16 @@ zgw_consumers: auth_type: api_key header_key: Authorization header_value: Token 0123456789abcdef0123456789abcdef01234567 + # (1b) The NRC Objecten publishes register-record events to (S-19b-1, ADR-0029). Same shape and + # same big-reference-seed credential OpenZaak publishes with — NRC verifies the JWT and + # authorizes it via OpenZaak's AC, which grants that client heeft_alle_autorisaties. + - identifier: nrc + label: Open Notificaties + api_type: nrc + api_root: http://nrc-web:8000/api/v1/ + auth_type: zgw + client_id: big-reference-seed + secret: insecure-dev-secret-change-me # (2) Permit the RegisterRecord objecttype (S-19a). Objecten refuses to store an object whose # objecttype it has not been configured with ("ObjectType with url=… is not configured"), and it @@ -40,3 +50,10 @@ tokenauth: email: admin@localhost organization: Respellion is_superuser: true + +# (4) Point Objecten's notifications at that NRC service (S-19b-1, ADR-0029). Requires +# NOTIFICATIONS_DISABLED=false plus a celery broker + worker — without the worker the message is +# queued and never sent, which is exactly the half-wired state S-19a refused to ship (ADR-0028). +notifications_config_enable: true +notifications_config: + notifications_api_service_identifier: nrc diff --git a/infra/opennotificaties/setup_configuration/data.yaml b/infra/opennotificaties/setup_configuration/data.yaml index 18abd80..e1557c0 100644 --- a/infra/opennotificaties/setup_configuration/data.yaml +++ b/infra/opennotificaties/setup_configuration/data.yaml @@ -29,7 +29,9 @@ autorisaties_api_config_enable: true autorisaties_api: authorizations_api_service_identifier: openzaak-ac -# 4. The kanaal OpenZaak publishes zaak events on. +# 4. The kanalen publishers announce on: `zaken` (OpenZaak) and `objecten` (Objecten, S-19b-1). +# Both authenticate with the big-reference-seed credential above, which OpenZaak's AC grants +# heeft_alle_autorisaties — so no separate publisher authorization is needed for Objecten. notifications_kanalen_config_enable: true notifications_kanalen_config: items: @@ -39,3 +41,11 @@ notifications_kanalen_config: - bronorganisatie - zaaktype - vertrouwelijkheidaanduiding + # 5. The kanaal Objecten publishes register-record events on (S-19b-1, ADR-0029). Its name is + # fixed by the Objects API itself (NOTIFICATIONS_KANAAL = "objecten"), not chosen here. The + # filter set matches what the Objects API sends as kenmerken, so an abonnement can narrow by + # objecttype rather than receiving every object write in the register. + - naam: objecten + documentatie_link: https://objects-and-objecttypes-api.readthedocs.io/ + filters: + - object_type