Skip to content

ADR-004: CQS Persistent Dynamic Queue Configuration

Status: Accepted Date: 2026-05

Context

The CreateOrConfigureQueue gRPC API allows consumer services to dynamically provision queues. For these queues to be effective, they must persist across service restarts so that the changequeue-service continues to route and buffer events for these queues even while the consumer is offline or the service itself restarts. Static configuration in application.yml is immutable at runtime, requiring a secondary persistence mechanism for dynamic overrides.

Decision

We will store dynamic queue configurations in a registry.json file located in the same persistent storage (GCS or Local) used for queue notification backups.

  • On startup, the service will load application.yml as the baseline.
  • It will then load registry.json and merge its contents, with dynamic configurations taking precedence for queues of the same name.
  • Any call to CreateOrConfigureQueue will trigger an asynchronous write of the updated registry to the registry.json file.
  • The registry will store the queue_name, dto_types, and maxTreeDepth.

Consequences

  • Easier: New services can self-provision without deployment-time configuration changes or platform operator intervention.
  • Harder: The registry logic becomes slightly more complex, needing to merge two sources of configuration.
  • Trade-off: We accept a slight delay in persistence (asynchronous write) for dynamic configuration updates, which is consistent with our existing notification persistence model.