numinnex commented on code in PR #4401: URL: https://github.com/apache/iggy/pull/4401#discussion_r4194795394
########## gateways/kafka/src/protocol/handlers/describe_groups.rs: ########## @@ -0,0 +1,155 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +//! `DescribeGroups` (API key 15). +//! +//! Reports the members, assignment and state of groups this coordinator holds. A named group +//! that is not here is `Dead`: v6 also carries `GROUP_ID_NOT_FOUND`, and earlier versions do +//! not, matching Kafka 4.0's `describeGroups`. A v6 client treats error 0 as a real group. +//! +//! `include_authorized_operations` is not answered. The field stays at the omitted sentinel +//! (`i32::MIN`): there is no group ACL bitfield to report, and any other value fails the +//! encoder below v3. + +use bytes::Bytes; +use kafka_protocol::messages::describe_groups_response::{DescribedGroup, DescribedGroupMember}; +use kafka_protocol::messages::{DescribeGroupsRequest, DescribeGroupsResponse, GroupId}; +use kafka_protocol::protocol::StrBytes; + +use crate::error::Result; +use crate::group::{DescribeGroupsView, GroupDescription, MemberDescription}; +use crate::protocol::api::{ + API_KEY_DESCRIBE_GROUPS, ApiVersionRange, ERROR_GROUP_ID_NOT_FOUND, GatewayState, + HandleOutcome, is_supported_version, +}; +use crate::protocol::bounds_guard::validate_describe_groups_shape; +use crate::protocol::dedup::dedup_first_seen; +use crate::protocol::handlers::{ + decode_guarded, encode_message, respond_or_close, unsupported_version_response, +}; + +pub const RANGE: ApiVersionRange = ApiVersionRange { + api_key: API_KEY_DESCRIBE_GROUPS, + min_version: 0, + max_version: 6, +}; + +/// Kafka's `Dead` state. This coordinator never stores it: an absent group is reported as one. +const DEAD: &str = "Dead"; +/// First version whose response has `error_message`, and the first on which Kafka 4.0 sends +/// `GROUP_ID_NOT_FOUND` for a missing group. +const FIRST_ERROR_MESSAGE_VERSION: i16 = 6; + +pub async fn handle(state: &GatewayState, api_version: i16, body: Bytes) -> HandleOutcome { + if !is_supported_version(API_KEY_DESCRIBE_GROUPS, api_version) { + // No top-level error field to carry a code on, so this answers with an empty group + // list rather than a dedicated error response. Versions outside 0-6 fail in the + // encoder, which is what makes `unsupported_version_response` close the connection + // instead - a version this encoder accepts is not a version the firewall rejects. + return unsupported_version_response(API_KEY_DESCRIBE_GROUPS, api_version, |version| { + encode_response(version, Vec::new()) + }); + } + let request = + match decode_guarded::<DescribeGroupsRequest>(api_version, body, |version, body| { + validate_describe_groups_shape(version, body, state.max_frame_size) + }) { + Ok(request) => request, + Err(error) => { + // debug!, not warn!: attacker-controlled, not operator-actionable. + // The response has no top-level error field, and a failed decode yields no group + // id to hang `INVALID_REQUEST` on. An empty group list would look like success. + tracing::debug!(%error, api_version, "Failed to decode DescribeGroups request"); + return HandleOutcome::Close; + } + }; + + let requested: Vec<StrBytes> = request + .groups + .iter() + .map(|group_id| group_id.0.clone()) + .collect(); + // One result per distinct id. Repeating one group would otherwise copy its members into the + // response once per copy, and the shape guard only charges the id strings. + let group_ids = dedup_first_seen(&requested); + match state + .groups + .describe_groups(&group_ids, api_version, state.max_frame_size) + .await + { + DescribeGroupsView::ExceedsFrame { encoded_bytes } => { Review Comment: this prices the whole batch against the inbound `max_frame_size` and closes the connection for every group in the request. Outbound frames aren't capped anyway (server.rs:1053, only an i32 check). One legal group can reach this, since assignments are capped per blob at 64 KiB but never in aggregate, and the batch sum reaches it more easily: `kafka-consumer-groups.sh --describe --all-groups` sends every group in one request, and the client then retries into the same close until it times out. Price per group: a group too big on its own gets the summaryNoMetadata shape, groups past the batch budget get a per-group error, and the connection is never closed. ########## gateways/kafka/src/group/state.rs: ########## @@ -708,6 +821,32 @@ fn join_request_error(config: &GroupCoordinatorConfig, request: &JoinRequest) -> None } +/// `protocol_type`, a client-supplied `member_id`, `group_instance_id`, and each protocol +/// `name` are echoed as legacy strings - the last of these by `DescribeGroups` v0-v4, which +/// writes the stored group's selected protocol name as `protocol_data` with an i16 length, not +/// by `JoinGroup` itself. When the member id is generated, the instance id is the prefix and the +/// `-{uuid}` suffix has to fit in the same cap. +fn legacy_strings_too_long(request: &JoinRequest) -> bool { + if request.protocol_type.len() > MAX_LEGACY_STRING_BYTES Review Comment: `protocol_type` is capped only at i16::MAX and isn't counted in `retained_bytes` (:808). About 254 `require_known_member_id` joins with a 32 KiB `protocol_type` and ids that sort first (`!...`, sort at :1305) each create a pending-only group. ListGroups truncation then silently drops every real group with error 0, and describe-all lands in the close path. They stay listed past the pending deadline because list never ticks. Cap `protocol_type` at ~255 at join and count it in `retained_bytes`, which makes truncation unreachable. The PR body still says list "closes". ########## gateways/kafka/src/group/state.rs: ########## @@ -619,6 +677,61 @@ impl GroupState { self.sync_deadline = None; self.bump(); } + + fn description(&self, group_id: &StrBytes) -> GroupDescription { Review Comment: this returns `protocol_data`, member metadata and assignments in every phase, while Kafka fills them only in Stable and uses summaryNoMetadata otherwise. In PreparingRebalance the old assignment is still there (cleared only at :562), and `Member::rejoin` (:167) has already swapped protocols, so the view mixes generations. `--describe --members --verbose` shows stale partitions, and consumer_group_tests.rs:1608 pins the deviation. When `phase != Stable`, return empty protocol_data/metadata/assignment, and update the pricing and the test. ########## gateways/kafka/src/group/state.rs: ########## @@ -71,6 +85,16 @@ pub enum Phase { Stable, } +impl Phase { + const fn as_kafka_state(self) -> &'static str { Review Comment: `Empty` is never emitted. Every v4+ Java first join creates a group that holds only a pending member (:960) in PreparingRebalance, and `is_empty` counts pending ones (:288). So a group with 0 members shows PreparingRebalance, `--list --state Empty` never matches, and `--reset-offsets` refuses in that window. CONSUMER_GROUPS.md:27 ("a group with no members is removed") is false too. Report `Empty` when `members` is empty, accept it in the states filter, fix the doc, and add a TODO for offsets-only groups once #3542 lands. ########## gateways/kafka/src/group/mod.rs: ########## @@ -451,6 +489,37 @@ impl GroupCoordinator { state::leave_step(&mut groups, request, Instant::now()) } + /// Snapshot of each distinct group, in first-seen order. `None` means the group is not here. + /// + /// Ids are deduped before the lock is taken. Under the lock each remaining group is ticked + /// once and, when the encoded response fits `max_frame_size`, snapshotted once. Encoding + /// happens after this returns. `ExceedsFrame` means the lengths already stored would not + /// fit, and no member snapshot was built. + pub async fn describe_groups( + &self, + group_ids: &[StrBytes], + version: i16, + max_frame_size: usize, + ) -> DescribeGroupsView { + let mut groups = self.groups.lock().await; + state::describe_groups( + &mut groups, + group_ids, + version, + max_frame_size, + Instant::now(), + ) + } + + /// Every group currently in the map, ordered by group id. + /// + /// Does not expire sessions. Expiry runs on the request that names a group; a list names + /// none, and sweeping every group here would open rebalances as a side effect of reading. + pub async fn list_groups(&self) -> Vec<GroupListing> { Review Comment: a group whose members have all expired stays listed in its last phase (e.g. Stable) indefinitely, since nothing sweeps it, while DescribeGroups of the same id ticks (state.rs:1276) and answers Dead. The two admin views contradict each other, and attacker-created pending groups stay visible. Keep the no-mutation rule but skip groups whose session and pending deadlines are all `<= now`, with a paused-time test. Neither this documented contract nor the describe tick at state.rs:1276 is pinned today (both mutants survive). ########## gateways/kafka/src/protocol/handlers/list_groups.rs: ########## @@ -0,0 +1,196 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +//! `ListGroups` (API key 16). +//! +//! Lists the groups this coordinator holds. v4+ `states_filter` and v5 `types_filter` keep a +//! group only when the filter is empty or one entry matches, case-insensitively, after trim. +//! A filter value this coordinator does not use matches nothing, so the group is left out and +//! the response error stays 0. Kafka 4.0's `listGroups` does the same ("if invalid, no groups +//! are returned"). + +use bytes::Bytes; +use kafka_protocol::messages::list_groups_response::ListedGroup; +use kafka_protocol::messages::{GroupId, ListGroupsRequest, ListGroupsResponse}; +use kafka_protocol::protocol::StrBytes; + +use crate::error::Result; +use crate::group::GroupListing; +use crate::protocol::api::{ + API_KEY_LIST_GROUPS, ApiVersionRange, ERROR_INVALID_REQUEST, ERROR_UNSUPPORTED_VERSION, + GatewayState, HandleOutcome, is_supported_version, +}; +use crate::protocol::bounds_guard::validate_list_groups_shape; +use crate::protocol::handlers::{ + decode_guarded, encode_message, respond_or_close, unsupported_version_response, +}; +use crate::protocol::header::response_header_version; +use crate::protocol::wire_len::{kafka_compact_prefix, kafka_string_len}; + +pub const RANGE: ApiVersionRange = ApiVersionRange { + api_key: API_KEY_LIST_GROUPS, + min_version: 0, + max_version: 5, +}; + +/// `ListGroups` v5 `group_type` for the classic protocol this coordinator runs. +const CLASSIC_GROUP_TYPE: &str = "classic"; + +pub async fn handle(state: &GatewayState, api_version: i16, body: Bytes) -> HandleOutcome { + if !is_supported_version(API_KEY_LIST_GROUPS, api_version) { + return unsupported_version_response(API_KEY_LIST_GROUPS, api_version, |version| { + encode_error_response(version, ERROR_UNSUPPORTED_VERSION) + }); + } + let request = match decode_guarded::<ListGroupsRequest>(api_version, body, |version, body| { + validate_list_groups_shape(version, body, state.max_frame_size) + }) { + Ok(request) => request, + Err(error) => { + // debug!, not warn!: attacker-controlled, not operator-actionable. + tracing::debug!(%error, api_version, "Failed to decode ListGroups request"); + return respond_or_close( + encode_error_response(api_version, ERROR_INVALID_REQUEST), + "ListGroups", + ); + } + }; + + let listings: Vec<GroupListing> = state + .groups + .list_groups() + .await + .into_iter() + .filter(|group| { + selected(&request.states_filter, group.state) + && selected(&request.types_filter, CLASSIC_GROUP_TYPE) + }) + .collect(); + // `protocol_type` is echoed for every group. The shape guard never sees that list, so a + // coordinator holding many long types can still outgrow the frame - truncate rather than + // close, since this is server-sized state, not a request the client chose (same approach as + // `metadata::truncate_all_topics_to_frame_budget` for the identical problem). + let listings = truncate_listings_to_frame_budget(api_version, listings, state.max_frame_size); + let groups = listings.into_iter().map(listed_group).collect(); + respond_or_close(encode_response(api_version, groups), "ListGroups") +} + +fn selected(filter: &[StrBytes], value: &str) -> bool { + filter.is_empty() + || filter + .iter() + .any(|wanted| wanted.as_str().trim().eq_ignore_ascii_case(value)) +} + +/// Keeps as many listed groups as fit `max_frame_size`, dropping the rest rather than closing +/// the connection - same approach as `metadata::truncate_all_topics_to_frame_budget` for the +/// identical problem: this coordinator's own state, not a request the client chose, is what +/// grew the response past the budget. +fn truncate_listings_to_frame_budget( + version: i16, + mut listings: Vec<GroupListing>, + max_frame_size: usize, +) -> Vec<GroupListing> { + let mut cumulative_bytes = list_response_frame_len(version, &[]); + let mut keep = listings.len(); + for (index, group) in listings.iter().enumerate() { + let next = cumulative_bytes + listed_group_len(version, group); + if next > max_frame_size { + keep = index; + break; + } + cumulative_bytes = next; + } + if keep < listings.len() { + tracing::warn!( + total_groups = listings.len(), + kept_groups = keep, + max_frame_size, + "ListGroups response would exceed max_frame_size; truncating rather than closing \ + the connection" + ); + listings.truncate(keep); + } + listings +} + +/// Header plus body, the length `send_response` writes and `read_frame` compares to +/// `max_frame_size`. +fn list_response_frame_len(version: i16, groups: &[GroupListing]) -> usize { Review Comment: the pricing is unpinned. It's tested only at v0 with one group, and these mutants survive: flexible tag byte, v4 state length, header 5 -> 4. The arithmetic is right today (a temp v0-5 parity test matched), but nothing keeps it right. The describe parity test (state.rs:1951) uses one member, no instance id and no varint boundary, and re-implements the handler mapping. Add a permanent v0..=5 list parity test, and make the describe test call the handler mapping with an instance id and fields >= 127 B. ########## gateways/kafka/README.md: ########## @@ -13,8 +13,9 @@ Foundation layer for [apache/iggy#3421](https://github.com/apache/iggy/issues/34 > InitProducerId does real work too, with or without the bridge: it allocates > a producer id, so a stock idempotent producer starts instead of failing at > startup. > > Consumer group coordination is not a stub either: `FindCoordinator`, > `JoinGroup`, `Heartbeat`, -> `LeaveGroup` and `SyncGroup` are real, with real membership, rebalances, graceful leave and -> session expiry ([docs/CONSUMER_GROUPS.md](docs/CONSUMER_GROUPS.md)). With the bridge off, +> `LeaveGroup`, `SyncGroup`, `DescribeGroups` and `ListGroups` are real, with real membership, Review Comment: overclaims `kafka-consumer-groups.sh` support. The default `--describe` calls OffsetFetch (9), which isn't advertised (api.rs:275), so only `--list`, `--describe --members` and `--describe --state` work. List the working modes in CONSUMER_GROUPS.md, add MANUAL_TESTING rows, and fix the PR body. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
