Create consumers with Key_Shared subscription type and sticky hash range mode: use ConsumerBuilder.keySharedPolicy(KeySharedPolicy.stickyHashRange().ranges(Range.of(0, 65535))) divided across consumers
Assign non-overlapping ranges to each consumer instance: consumer-1 gets Range.of(0, 32767), consumer-2 gets Range.of(32768, 65535) — ranges must together cover 0 to 65535 with no gaps
Produce messages with explicit message keys set; the broker hashes the key into the range and routes to the consumer owning that range
When scaling: drain the consumer for the range being reassigned (let it process all in-flight messages), then stop it and update the remaining consumers with expanded ranges before starting the new consumer
Monitor per-consumer message rate via the Pulsar admin API (topics stats) and confirm key routing is balanced by inspecting permitsInFlightMessages per consumer
For auto-split mode (less control): omit stickyHashRange and use KeySharedPolicy.autoSplitHashRange() — the broker automatically distributes hash ranges but does not guarantee stable per-key assignment during rebalance
Known gotchas
In sticky hash range mode, a consumer that disconnects leaves its hash range unserved; messages for keys in that range queue up and are not delivered to other consumers — unlike auto-split mode where the broker reassigns the range
Ordering is guaranteed per key only if all messages for a key go to the same consumer; avoid mixing Key_Shared with redelivery (nack) on the same key without understanding that redelivered messages may temporarily arrive at the same consumer out of order relative to new messages
The broker rejects a Key_Shared subscription attempt if an existing consumer in the same subscription holds an overlapping range — coordinate range assignment before starting consumers in sticky mode
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp