Change Stream Fanout

Status: Unsupported in 0.2.0: dashboard manifest only. No canonical entitlement and no supported deployment contract.

:::danger Unsupported legacy concept

This page preserves a legacy dashboard concept. It has no canonical entitlement and no supported deployment contract. Do not infer a CRD, Operator reconciliation path, runtime implementation, or support commitment from the historical configuration and examples below.

:::

This page belongs to the immutable 0.2.0 Private Preview documentation.

At a glance

Property	Value
Pipeline phase	Response
Category	Streaming
Canonical minimum tier	No canonical entitlement
Legacy dashboard tier label	Business
Legacy rendered name	Change Stream Fanout
Legacy rendered summary	Multiplex a single change stream to N consumers — reduce server load by 10-50x.
Canonical entitlement	No
Supported deployment contract	No
Release status	Unsupported in 0.2.0: dashboard manifest only. No canonical entitlement and no supported deployment contract.

Release accuracy

• 0.2.0 Private Preview: Unsupported in 0.2.0: dashboard manifest only. No canonical entitlement and no supported deployment contract.

The detailed material below preserves every section rendered by the legacy dashboard. Where it conflicts with the release status above, the release status is authoritative. Legacy field names and examples are not a substitute for the selected bundle's CRD and runtime contract. Unsafe legacy wording is retained in metadata for traceability but is corrected in the rendered guidance.

Release-aware feature flow. The diagram is explanatory; the release status on this page is authoritative.

Diagram resources: Open the SVG full screen · Download the editable Excalidraw source

Performance impact

:::warning Legacy, unverified performance claims

These numbers are preserved for documentation parity with the legacy dashboard. They are not current benchmarks or service guarantees and have not been verified by the current test suite.

:::

Percentile	Legacy claim
P50	<1ms
P95	<3ms
P99	<5ms

Legacy note: Fanout is async — does not add latency to normal queries

Overview

The Change Stream Fanout step maintains a single change stream watcher per namespace and fans out events to multiple consumers via WebSocket connections. This eliminates the N-watcher problem where each microservice opens its own change stream, multiplying oplog reads.

Events are buffered per-consumer with configurable backpressure. Resume tokens are stored durably to survive proxy restarts.

When to use

• Multiple services consuming the same change stream (event-driven architectures)
• Reducing MongoDB oplog read amplification
• Building real-time notification systems without per-service watchers
• CDC (Change Data Capture) pipelines with multiple downstream targets

How it works

1. Proxy opens one change stream per configured namespace
2. Events are received and stored in a per-consumer ring buffer
3. Connected consumers receive events via WebSocket in order
4. If a consumer falls behind, backpressure drops oldest events (at_most_once) or blocks (at_least_once)
5. Resume tokens are persisted to survive restarts

Configuration

The table preserves the legacy dashboard field reference. “Not specified” means the legacy source did not declare required semantics.

Field	Legacy UI type	Legacy default	Required	Description
streams	json	—	Not specified	Stream definitions: {database, collection, consumers[]}
buffer_size	number	10000	Not specified	Max events buffered per consumer
delivery	select	at_least_once	Not specified	Delivery guarantee
resume_token_store	select	memory	Not specified	Where to persist resume tokens
filter_pipeline	json	—	Not specified	Aggregation pipeline to filter events

Settings reference

The legacy page did not render an additional anchored settings reference.

Examples

Multi-consumer CDC

steps:
  - id: builtin:change-stream-fanout
    config:
      delivery: at_least_once
      resume_token_store: redis
      redis_addr: redis:6379
      buffer_size: 50000
      streams:
        - database: orders
          collection: events
          consumers:
            - ws://notification-svc:8080/changes
            - ws://analytics-svc:8080/changes
            - ws://billing-svc:8080/changes

Best practices

• Use at_least_once delivery for critical events (notifications, billing)
• Use Redis or MongoDB for resume token storage in production
• Apply filter_pipeline to reduce event volume at source
• Monitor buffer fill rates — sustained 80%+ indicates consumers are too slow

Limitations

• WebSocket consumers must acknowledge events for at_least_once delivery
• Maximum 50 consumers per stream (server connection overhead)
• Cannot fan out change streams that use $match on encrypted fields

Security and operational guidance

• This is a legacy dashboard concept, not a canonically entitled Nexo component.
• No supported deployment contract, CRD mapping, Operator reconciliation path, or runtime execution guarantee is published.
• Treat every configuration example and performance number below as historical design material only.

Related steps

• metrics
• logging

Release availability

• 0.2.0 Private Preview: Unsupported in 0.2.0: dashboard manifest only. No canonical entitlement and no supported deployment contract.

See the component catalog for the complete comparison matrix.