Story: Introduce per-entity NATS sub-registrars
Table of Contents
This page documents a story in Sprint 21. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
Replace the single monolithic registrar.cpp in ores.refdata.core with a
generated per-entity sub-registrar pattern. Each entity gets its own
code-generated <entity>_registrar.hpp/cpp that wires that entity's NATS
subjects to its handler. The top-level registrar.cpp becomes a thin
generated file that calls each sub-registrar. Isolation is complete: a
broken handler for one entity cannot block compilation of the rest of the
service.
This story was motivated by PR #1342, which regenerated all handlers with
an updated template and broke the entire ores.refdata.core build in one
commit. With per-entity sub-registrars each entity compiles independently,
so a template mismatch in one entity's handler only fails that entity.
The redesign also unblocks future work: service API updates (pagination, count, delete method names) can land entity-by-entity rather than requiring all 20+ entities to be correct simultaneously.
Status
| Field | Value |
|---|---|
| State | BACKLOG |
| Parent sprint | Sprint 21 |
| Now | Not yet started. |
| Waiting on | Nothing. |
| Next | Break the story into tasks. |
| Last touched | 2026-06-27 |
Acceptance
- A
<entity>_registrar.hpp/cpppair is generated for each refdata entity by thenats-handlerprofile. - The top-level
registrar.cppis generated and contains only calls to the per-entity sub-registrars; it includes no handler headers directly. - Each entity's
_registrar.cppincludes only its own handler header. - Removing one entity's handler header causes only that entity's registrar to fail to compile; the rest of the service builds cleanly.
- Hand-written custom protocol structs (e.g.
read_parties_for_cache_request) are preserved in a<entity>_protocol_extensions.hppfile that is not overwritten by codegen. - All existing NATS subjects and handler behaviour are preserved.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
Decisions
- Motivated by PR #1342 build failure — monolithic registrar means one bad handler breaks the whole build. Per-entity sub-registrars isolate the damage to a single translation unit.
- Custom protocol structs (e.g.
read_parties_for_cache_request) must not be in the generated protocol header; they belong in a separate*_protocol_extensions.hppnot touched by codegen.
Out of scope
- Service API changes (adding pagination, count, delete methods). Those are separate tasks per entity, unblocked once sub-registrars exist.
- Migrating
ores.iamorores.syntheticregistrars; onlyores.refdatain scope for this story.