@spec add_current_leader_epoch(struct(), Keyword.t(), integer()) :: struct()

Adds current_leader_epoch to partition requests for V9+.

V9 introduces current_leader_epoch in each partition request, allowing brokers to detect stale fetch requests from consumers that have not yet learned about a leader change.

The default value of -1 means "no epoch specified" (unknown).

@spec add_isolation_level(struct(), Keyword.t(), integer()) :: struct()

Adds isolation_level field for V4+ requests.

@spec add_max_bytes(struct(), map(), integer()) :: struct()

Adds max_bytes field for V3+ requests.

@spec add_rack_id(struct(), Keyword.t(), integer()) :: struct()

Adds rack_id for V11+ requests.

V11 introduces rack_id at the top level, enabling rack-aware fetch so brokers can prefer replicas closer to the consumer.

The default value is an empty string (no rack specified).

@spec add_session_fields(struct(), Keyword.t(), integer()) :: struct()

Adds session fields for V7+ requests (incremental fetch).

@spec build_request_v7_plus(struct(), Keyword.t(), integer()) :: struct()

Builds a Fetch request for V7+ versions with all applicable fields.

Handles the common pattern of V7+ requests which share:

• V3+ max_bytes
• V4+ isolation_level
• V5+ log_start_offset in partition data
• V7+ session fields (session_id, session_epoch, forgotten_topics_data)
• V9+ current_leader_epoch in partition data
• V11+ rack_id

This helper reduces duplication across V7-V11 request implementations which all share the same base logic.

@spec build_topics(map(), Keyword.t()) :: [map()]

Builds the topics structure for Fetch request.

For V0-V4:

[%{topic: "topic", partitions: [%{partition: 0, fetch_offset: 0, max_bytes: 1000000}]}]

For V5+:

[%{topic: "topic", partitions: [%{partition: 0, fetch_offset: 0, log_start_offset: 0, max_bytes: 1000000}]}]

@spec extract_common_fields(Keyword.t()) :: map()

Extracts common fields from request options.

Returns a map with:

• :topic - The topic to fetch from
• :partition - The partition to fetch from
• :offset - The offset to start fetching from
• :max_bytes - Maximum bytes to fetch per partition
• :max_wait_time - Maximum time to wait for messages in ms
• :min_bytes - Minimum bytes to accumulate before returning

@spec populate_request(struct(), map(), [map()]) :: struct()

Populates a request struct with common fields.