Internals: Group Coordinator

This chapter focuses on consumer-group mechanics.

Group State Model

Each group tracks:

• topic
• generation
• assignor
• members with heartbeat timestamps
• partition assignments

Lifecycle Commands

• JOIN: add/refresh member and possibly trigger rebalance
• SYNC: confirm generation and get assignment
• HEARTBEAT: maintain liveness in current generation
• LEAVE: explicit member removal and rebalance
• COMMIT: validated offset commit

Generation Rules

Generation increments when:

• new member joins
• member expires by session timeout
• member leaves
• assignor changes
• topic context changes for the group

Session Timeout Handling

Expired members are removed when coordinator evaluates group state.

Effects:

• generation bumps
• assignments recalculated
• stale members become invalid for commit/heartbeat/sync

Commit Fencing

COMMIT is rejected unless all are true:

• group and topic match
• generation is current
• member exists
• partition is assigned to that member

This is the key stale-writer safety mechanism.

Durability

Group metadata persists to groups.json.

On restart:

• generation and assignment state reloads
• members restore with last heartbeat timestamps
• lifecycle resumes from persisted state