1// JoinGroupRequest issues a request to join a Kafka group. This will create a
2// group if one does not exist. If joining an existing group, this may trigger
3// a group rebalance.
4//
5// This will trigger a group rebalance if the request is from the group leader,
6// or if the request is from a group member with different metadata, or if the
7// request is with a new group member.
8//
9// Version 4 introduced replying to joins of existing groups with
10// MEMBER_ID_REQUIRED, which requires re-issuing the join group with the
11// returned member ID. See KIP-394 for more details.
12//
13// Version 5 introduced InstanceID, allowing for more "static" membership.
14// See KIP-345 for more details.
15JoinGroupRequest => key 11, max version 9, flexible v6+, group coordinator
16 // Group is the group to join.
17 Group: string
18 // SessionTimeoutMillis is how long a member in the group can go between
19 // heartbeats. If a member does not send a heartbeat within this timeout,
20 // the broker will remove the member from the group and initiate a rebalance.
21 SessionTimeoutMillis: int32
22 // RebalanceTimeoutMillis is how long the broker waits for members to join a group
23 // once a rebalance begins. Kafka waits for the longest rebalance of all
24 // members in the group. Member sessions are still alive; heartbeats will be
25 // replied to with REBALANCE_IN_PROGRESS. Those members must transition to
26 // joining within this rebalance timeout. Members that do not rejoin within
27 // this timeout will be removed from the group. Members must commit offsets
28 // within this timeout.
29 //
30 // The first join for a new group has a 3 second grace period for other
31 // members to join; this grace period is extended until the RebalanceTimeoutMillis
32 // is up or until 3 seconds lapse with no new members.
33 RebalanceTimeoutMillis: int32(-1) // v1+
34 // MemberID is the member ID to join the group with. When joining a group for
35 // the first time, use the empty string. The response will contain the member
36 // ID that should be used going forward.
37 MemberID: string
38 // InstanceID is a user configured ID that is used for making a group
39 // member "static", allowing many rebalances to be avoided.
40 InstanceID: nullable-string // v5+
41 // ProtocolType is the "type" of protocol being used for the join group.
42 // The initial group creation sets the type; all additional members must
43 // have the same type or they will be rejected.
44 //
45 // This is completely arbitrary, but the Java client and everything else
46 // uses "consumer" as the protocol type.
47 ProtocolType: string
48 // Protocols contains arbitrary information that group members use
49 // for rebalancing. All group members must agree on at least one protocol
50 // name.
51 Protocols: [=>]
52 // Name is a name of a protocol. This is arbitrary, but is used
53 // in the official client to agree on a partition balancing strategy.
54 //
55 // The official client uses range, roundrobin, or sticky (which was
56 // introduced in KIP-54).
57 Name: string
58 // Metadata is arbitrary information to pass along with this
59 // protocol name for this member.
60 //
61 // Note that while this is not documented in any protocol page,
62 // this is usually a serialized GroupMemberMetadata as described in
63 // https://cwiki.apache.org/confluence/display/KAFKA/Kafka+Client-side+Assignment+Proposal.
64 //
65 // The protocol metadata is where group members will communicate which
66 // topics they collectively as a group want to consume.
67 Metadata: bytes
68 // Reason is an optional reason the member is joining (or rejoining) the
69 // group (KIP-800, Kafka 3.2+).
70 Reason: nullable-string // v8+
71
72// JoinGroupResponse is returned from a JoinGroupRequest.
73JoinGroupResponse =>
74 ThrottleMillis(3) // v2+
75 // ErrorCode is the error for the join group request.
76 //
77 // GROUP_AUTHORIZATION_FAILED is returned if the client is not authorized
78 // to the group (no read perms).
79 //
80 // INVALID_GROUP_ID is returned in the requested group ID is invalid.
81 //
82 // COORDINATOR_NOT_AVAILABLE is returned if the coordinator is not available
83 // (due to the requested broker shutting down or it has not completed startup).
84 //
85 // COORDINATOR_LOAD_IN_PROGRESS is returned if the group is loading.
86 //
87 // NOT_COORDINATOR is returned if the requested broker is not the coordinator
88 // for the requested group.
89 //
90 // INVALID_SESSION_TIMEOUT is returned if the requested SessionTimeout is
91 // not within the broker's group.{min,max}.session.timeout.ms.
92 //
93 // INCONSISTENT_GROUP_PROTOCOL is returned if the requested protocols are
94 // incompatible with the existing group member's protocols, or if the join
95 // was for a new group but contained no protocols.
96 //
97 // UNKNOWN_MEMBER_ID is returned is the requested group is dead (likely
98 // just migrated to another coordinator or the group is temporarily unstable),
99 // or if the request was for a new group but contained a non-empty member ID,
100 // or if the group does not have the requested member ID (and the client must
101 // do the new-join-group dance).
102 //
103 // MEMBER_ID_REQUIRED is returned on the initial join of an existing group.
104 // This error was proposed in KIP-394 and introduced in Kafka 2.2.0 to
105 // prevent flaky clients from continually triggering rebalances and prevent
106 // these clients from consuming RAM with metadata. If a client sees
107 // this error, it should re-issue the join with the MemberID in the response.
108 // Non-flaky clients will join with this new member ID, but flaky clients
109 // will not join quickly enough before the pending member ID is rotated out
110 // due to hitting the session.timeout.ms.
111 //
112 // GROUP_MAX_SIZE_REACHED is returned as of Kafka 2.2.0 if the group has
113 // reached a broker's group.max.size.
114 ErrorCode: int16
115 // Generation is the current "generation" of this group.
116 Generation: int32(-1)
117 // ProtocolType is the "type" of protocol being used for this group.
118 ProtocolType: nullable-string // v7+
119 // Protocol is the agreed upon protocol name (i.e. "sticky", "range").
120 //
121 // v7 of this response changed this field to be nullable.
122 Protocol: nullable-string-v7+
123 // LeaderID is the leader member.
124 LeaderID: string
125 // True if the leader must skip running the assignment (KIP-814, Kafka 3.2+).
126 SkipAssignment: bool // v9+
127 // MemberID is the member of the receiving client.
128 MemberID: string
129 // Members contains all other members of this group. Only the group leader
130 // receives the members. The leader is responsible for balancing subscribed
131 // topic partitions and replying appropriately in a SyncGroup request.
132 Members: [=>]
133 // MemberID is a member in this group.
134 MemberID: string
135 // InstanceID is an instance ID of a member in this group (KIP-345).
136 InstanceID: nullable-string // v5+
137 // ProtocolMetadata is the metadata for this member for this protocol.
138 // This is usually of type GroupMemberMetadata.
139 ProtocolMetadata: bytes
View as plain text