Protocol Bridging

Use this pattern when two systems need to exchange messages but speak different protocols or expect different formats. The platform sits in the middle, translating messages in each direction and (optionally) enriching them with routing metadata before delivery.

A typical bridge has two legs: one adapter for each side of the conversation, with a shared durable buffer (a broker topic) decoupling them. Each leg can fail, restart, and recover independently without blocking the other side.

One-way bridge (producer to consumer)

One system emits messages in its native format. The platform wraps each message in a structured envelope, attaches static routing headers (such as environment, tenant, or source identifiers), and publishes the result to a downstream topic in a format the consumer expects.

Stage	What happens
Ingest	The adapter receives a message from the source system.
Envelope	The pipeline wraps the original payload in a structured JSON envelope (optionally including the original headers).
Enrich	Static headers (environment, tenant identifier, bridge source) are attached as native record headers on the destination topic.
Publish	The enriched record is written to the target topic.

The source payload is preserved verbatim inside the envelope. Consumers that care about the original bytes can read them; consumers that only care about the envelope metadata can ignore the payload entirely.

Two-way bridge (round trip through a broker)

Both sides need to exchange messages. Two adapters cooperate: one translates from side A into the broker, the other translates from the broker back to side B (or back to side A for a request/response flow).

The shared topic is the durable hand-off: if either leg pauses, the other keeps reading or writing at its own pace. Each leg has its own redundancy configuration and its own observability (throughput, error rate, session health).

What the platform handles	What you configure
Format conversion in both directions	Two adapters (one per leg)
Message buffering between the legs	The shared broker topic
Per-leg failover, without coupling the legs	Transformation rules for each direction
Back-pressure through the broker when a leg slows down	Headers, envelope structure, and any filtering conditions

Deployment mode per leg

Every leg of a bridge picks its own deployment mode based on the protocol on that leg. The constraint is symmetric: if any connector on the adapter (source or target) requires exclusive single-owner access, the whole adapter for that leg must run as Single Writer. One leg's choice does not influence the other's; the broker between them absorbs the rate difference.

Leg composition	Deployment mode	Why
Stateful single-owner source paired with a broker target.	Single Writer.	The stateful source holds an exclusive session. Two replicas would produce duplicate logons or sequence-number corruption against the counterparty.
Broker source paired with a stateful single-owner target.	Single Writer.	The stateful target holds an exclusive session. The broker source is concurrent-safe on its own, but the weakest link forces the whole adapter to Single Writer.
Broker source paired with a broker target.	Scale Out.	Both sides tolerate concurrent replicas. The source broker's consumer-group mechanic distributes partitions across pods; the target broker has no single-writer constraint.
Stateful source paired with a stateful target.	Single Writer on both legs.	Both endpoints hold exclusive sessions. Concurrency on either side breaks the protocol.

Do not scale a stateful leg to Scale Out

A leg that pairs a concurrent-safe broker source with a stateful target may look scalable from the broker side. Running it in Scale Out produces duplicate concurrent sessions on the stateful side, corrupts sequence numbers, and causes the counterparty to reject one or both sessions. Keep the leg in Single Writer; scale throughput by sharding the stateful endpoint into multiple sessions and running one Single Writer adapter per shard.

To scale throughput across a stateful endpoint, shard the work into multiple single-owner sessions and run one Single Writer adapter per shard. The pool's aggregate throughput is the sum of the per-session capacities. The counterparty must agree to the sharding scheme because it controls which session each message flows on. See Scaling for session sharding.

Worked example: bridging two stateful venues through a broker

The canonical bridging topology connects inbound venue connectivity to a broker for downstream consumption and routes outbound messages from the broker back out to a second venue. The broker acts as the durable buffer between the two stateful legs.

Both legs hold a stateful session. The deployment-mode rule above forces Single Writer on both, even though the broker connector on each adapter would, on its own, tolerate Scale Out. The broker middle hop does not absolve either stateful leg of its single-owner constraint.

Concern	Inbound leg	Outbound leg
Source connector	Stateful (initiator or acceptor against the upstream venue).	Broker consumer.
Target connector	Broker producer.	Stateful (initiator against the downstream venue).
Pipeline	Receive, transform to internal format, send to the broker topic.	Read from the broker topic, transform to the venue's protocol, deliver.
Deployment mode	Single Writer. The stateful source holds an exclusive session.	Single Writer. The stateful target holds an exclusive session.

Each leg fails, restarts, and recovers independently without blocking the other. Each leg has its own redundancy and its own observability (throughput, error rate, session health).

Worked example: scaling a broker-to-broker bridge

When both legs are concurrent-safe brokers, the bridge runs in Scale Out. The source topic's partition count is the hard ceiling: throughput scales linearly with pod count only up to the partition count, and adding pods beyond it adds no throughput.

A consumer group is a set of consumers that collectively subscribe to one or more topics. The broker assigns each partition to exactly one consumer in the group at any moment. Three pods sharing a group identifier against a six-partition topic receive two partitions each. When a pod leaves, the broker redistributes its partitions to the survivors; when a pod joins, the broker rebalances in the opposite direction. The platform does not need to arbitrate which pod owns which partition because the broker already does.

Pod count relative to partition count	Outcome
Fewer pods than partitions	Each pod handles multiple partitions. Additional pods improve both throughput and failover coverage.
Equal to partition count	Each pod handles exactly one partition. Optimal parallelism.
More pods than partitions	Excess pods idle. Use them for failover headroom or reduce the replica count.

Two consumer groups consuming the same topic receive independent copies of every message. Use this to deliver one event stream to two independent processing pipelines (for example, a primary processor and an archival pipeline): give each adapter configuration a unique group identifier. Consumers within one group split work; consumers in different groups receive full copies.

When to use

Scenario	Pattern
A legacy system speaks one protocol; your new system speaks another.	One-way bridge.
A counterparty needs a request/response loop through your platform.	Two-way bridge.
You need to bridge two stateful venues with a durable buffer between them.	Two-way bridge with a broker topic and Single Writer on both legs.
You want to tag in-flight messages with environment or tenant metadata for downstream routing.	Add header enrichment to either pattern.
You need to scale a broker-to-broker bridge by replica count.	Scale Out on a partitioned source topic.

One-way bridge (producer to consumer)​

Two-way bridge (round trip through a broker)​

Deployment mode per leg​

Worked example: bridging two stateful venues through a broker​

Worked example: scaling a broker-to-broker bridge​

When to use​

See also​