Skip to content

PATTERN Cited by 1 source

Single extractor, multi call-site

Pattern

Build one parser. Run it in N independent places. The places have different jobs (CI, runtime boot, post-boot validation), but they share one parser, and they all read from the same source of truth.

The pattern enforces single-source-of-truth discipline by topology: because every consumer of the configuration uses the same parser against the same source, there is no opportunity for the parser to disagree with itself across stages. The result: "a topic name can only be wrong in the contract. While the processes and lifecycle stages may differ, there is only one parser. Ultimately, being disciplined matters more than the infrastructure."

"The implementation itself is intentionally small. A ContractTopicExtractor discovers approved packages, loads each contract.yaml, and returns the union of declared topics. That extractor runs in 3 independent places." — Source: sources/2026-06-02-redpanda-how-omninode-uses-redpanda-to-scale-ai-agent-workflows

Disclosed call sites in OmniNode

Call site 1: Pre-deploy CI

"CI invokes the extractor and creates the declared topics against the broker. If a developer adds a new node but forgets to declare a required topic, the smoke tests fail before the change merges. This is the earliest enforcement point: the contracts are validated against a real broker before the runtime ever starts."

The CI call site catches: - Missing topic declarations (a node uses a topic but doesn't list it in its contract). - Non-canonical names (regex / enum check). - Conflicting declarations across nodes.

Call site 2: Runtime boot

"When the runtime starts, the provisioner invokes the same extractor. There is no fallback constant list or duplicated topic configuration. If the contracts are silent, the provisioner is silent. The runtime only knows about the topics that the contracts declare."

The runtime call site enforces: - The provisioner has no privileged knowledge — it only knows what the contracts say. - A topic that isn't in any contract is not provisioned, even if some legacy code path expected it.

Call site 3: Post-boot validation

"After provisioning, a startup validator queries the broker and compares the existing topics against the extractor output. If a declared topic is missing, say because topic creation partially failed during startup, the validator re-invokes provisioning. This is the cheapest recovery path in the system."

The post-boot call site catches: - Provisioning races (topic created but ack'd late). - Partial provisioning failures (some topics created, some not). - Drift between declared and actual broker state.

Why three call sites instead of one

Each call site has a different blast radius and a different recovery path:

Call site Detects Recovery
CI Pre-merge contract bugs Block the merge
Runtime boot Provisioner gaps Halt or retry boot
Post-boot Race conditions, partial failures Re-invoke provisioning

A single call site catches a single class of bug. Three independent call sites form a defense-in-depth: every contract change passes through CI; every cluster start re-runs provisioning; every running cluster re-validates after startup. The bug class (concepts/silent-wiring-failure) has no surviving niche.

The "single parser" property

Critically, all three call sites use the same extractor code. This eliminates the "two parsers disagree" failure mode that would otherwise re-introduce drift:

  • The CI parser and the runtime parser are not two implementations of the same logic; they are the same code path.
  • Adding a new validation rule (e.g., a new naming convention) updates one place; all three call sites get the rule.
  • A bug in the parser fails consistently across call sites (predictable) rather than inconsistently (unobservable drift).

Generalises beyond topic naming

The pattern applies to any configuration where: - A canonical declaration lives in source control (the contract, the manifest, the IaC file). - Multiple independent code paths need to know what's declared (build-time validation, runtime provisioning, runtime validation, monitoring, etc.). - Drift between declared and actual would be a silent bug class.

Examples elsewhere on the wiki:

The unifying property: one canonical source × one parser × N call sites = correctness by topology.

When to use it

  • The configuration is consumed by ≥3 distinct code paths.
  • Drift between any two of those paths produces silent bugs.
  • The configuration changes often enough that style-guide discipline isn't reliable.
  • The cost of building and maintaining one parser is less than the cost of N drift bugs.

When it's overkill

  • Configuration consumed by one code path — direct read is fine.
  • Drift is loud rather than silent (e.g., wrong DB schema makes queries fail loudly at startup).
  • The configuration is small and stable; PR review catches drift reliably.

Seen in

  • sources/2026-06-02-redpanda-how-omninode-uses-redpanda-to-scale-ai-agent-workflows (2026-06-02, OmniNode → Redpanda guest post) — canonical wiki instance. Discloses the ContractTopicExtractor running in three independent places (CI / runtime boot / post-boot validation), with the explicit slogan: "With multiple independent passes, a topic name can only be wrong in the contract. While the processes and lifecycle stages may differ, there is only one parser. Ultimately, being disciplined matters more than the infrastructure." Pairs with patterns/contract-driven-topic-provisioning as the topology that makes the pattern enforceable.
Last updated · 542 distilled / 1,571 read