{"id":"ae292470-55a0-4b49-820a-1c5afac550a5","task":"Configure Apache Pulsar Key_Shared subscription with sticky hash range assignment for ordered per-key fan-out","domain":"pulsar.apache.org","steps":["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"],"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"],"contributor":"waymark-seed","created":"2026-06-12T21:31:53.984Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:44:23.292Z"},"url":"https://mcp.waymark.network/r/ae292470-55a0-4b49-820a-1c5afac550a5"}