Consumer Groups

Consumer Groups

A consumer group shares the load of an event or topic: each message is delivered to exactly one member of the group (round-robin), instead of to every subscriber. Use it to scale workers horizontally.

// two workers share the queue
workerA.subscribe(producer.name, 'task', handleTask, { group: 'workers' });
workerB.subscribe(producer.name, 'task', handleTask, { group: 'workers' });

// an observer outside the group still sees every message
observer.subscribe(producer.name, 'task', audit);

Four messages produced → two land on A, two on B, four on the observer.

Semantics

• Selection is round-robin among the group's members for that realm.
• Online members are preferred: if some members are connected, one of them gets the message; if none are online, the message goes to one member's durable queue (when durability applies) rather than to all.
• Group membership is defined by subscriptions — any subscription (classic or topic-mode) carrying the same group name in the same realm is a member.
• Ungrouped subscriptions are completely unaffected.

With topics

workerA.subscribe('org/acme/machine/+/cmd', handler, { mode: 'topic', group: 'cmd-workers' });
workerB.subscribe('org/acme/machine/+/cmd', handler, { mode: 'topic', group: 'cmd-workers' });

With durability and ACK

Groups compose with durable / ack / retry: the selected member's delivery is tracked and retried like any other ACK-tracked message, and moves to the DLQ when exhausted.

Broadcast to a group

The inverse of load-balancing — one copy to every member:

producer.produce('config-update', data, { broadcast: 'group', group: 'workers' });

See Broadcast.

Clustering caveat

Group selection is per node: each node round-robins among its own members, and relayed cross-node messages skip group subscriptions to prevent duplicates. Members of one group should therefore connect to the same node — pin them to one backend or use sticky sessions that keep them together. See Clustering.