You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iggy.apache.org by "krishvishal (via GitHub)" <gi...@apache.org> on 2026/09/29 05:30:39 UTC

[PR] feat(gateways): answer Kafka Fetch with records from Iggy [iggy]

krishvishal opened a new pull request, #4336:
URL: https://github.com/apache/iggy/pull/4336

   Closes #3536.
   
   With `IGGY_KAFKA_BRIDGE_ENABLED=true`, Fetch now returns records from Iggy instead of the stub 6. Records are rebuilt with `from_iggy` from #4229, so keys, headers and timestamps come back the way Produce wrote them.
   
   ### How a Fetch runs
   
   - one `get_topic` per topic, shared across all Fetches, then a poll per partition in request order from the fetch offset
   - one uncompressed batch per partition, max 1000 records, polled 16 at a time
   - `max_wait_ms` (capped at 18s) and `min_bytes` behave like Kafka. A Produce through the gateway wakes a waiting Fetch right away. Native Iggy writes get picked up at the next probe, within ~200ms
   - no fetch sessions, `session_id` is always 0. A request continuing a session gets 70 and the client goes back to full requests
   
   ### Tests
   
   - `fetch_real_bridge_tests.rs`: 21 tests against a real `iggy-server`, through the handler, every version
   - `kafka_client_e2e_tests.rs`: kcat writes 3 records, kcat and `kafka-console-consumer.sh --partition 0 --offset earliest` read them back. That covers the acceptance criteria in the issue. Needs Docker and the two images, run with `KAFKA_E2E_REQUIRED=1`


-- 
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: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(gateways): answer Kafka Fetch with records from Iggy [iggy]

Posted by "ryerraguntla (via GitHub)" <gi...@apache.org>.
ryerraguntla commented on code in PR #4336:
URL: https://github.com/apache/iggy/pull/4336#discussion_r4133015997


##########
gateways/kafka/src/protocol/probe_board.rs:
##########
@@ -0,0 +1,368 @@
+// 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.
+
+//! The newest probe of each Kafka topic, shared by every Fetch.
+
+use std::collections::HashMap;
+use std::future::Future;
+use std::sync::{Arc, Mutex, PoisonError};
+use std::time::Duration;
+
+use tokio::sync::{Mutex as AsyncMutex, watch};
+use tokio::time::{Instant, timeout_at};
+
+use crate::bridge::iggy_bridge::TopicProbe;
+
+/// How long a probe counts as new, and how often a waiting Fetch asks for one.
+pub const PROBE_INTERVAL: Duration = Duration::from_millis(100);
+
+/// A topic's probe, or the Kafka code the probe failed with.
+pub type TopicProbed = Result<Arc<TopicProbe>, i16>;
+
+/// The board sweeps no map smaller than this.
+const MIN_SWEEP: usize = 1024;
+
+/// The oldest start a shared probe can have and still count as new at `now`.
+pub fn recent(now: Instant) -> Instant {
+    now.checked_sub(PROBE_INTERVAL).unwrap_or(now)
+}
+
+/// A probe, and when its `get_topic` started.
+#[derive(Debug)]
+pub struct Snapshot {
+    pub started: Instant,
+    pub probe: TopicProbed,
+}
+
+/// The newest probe of each Kafka topic, shared by every Fetch.
+///
+/// One refresh runs at a time per topic, in its own task, so a Fetch that gives up leaves no call
+/// behind in the SDK queue.
+#[derive(Default)]
+pub struct ProbeBoard {
+    topics: Mutex<Topics>,
+}
+
+/// Every topic on the board, and the size at which the next insert sweeps first.
+#[derive(Default)]
+struct Topics {
+    by_name: HashMap<String, Arc<Topic>>,
+    sweep_at: usize,
+}
+
+impl Topics {
+    /// Forgets each topic that no Fetch and no refresh holds, and whose probe is too old to share.
+    /// Any client can name topics, so the board must not keep them all.
+    fn sweep(&mut self, now: Instant) {
+        let since = recent(now);
+        self.by_name
+            .retain(|_, topic| Arc::strong_count(topic) > 1 || topic.newer_than(since));
+        // Twice what is left, so sweeps cost O(1) per insert.
+        self.sweep_at = self.by_name.len().saturating_mul(2).max(MIN_SWEEP);
+    }
+}
+
+#[derive(Default)]
+struct Topic {
+    newest: watch::Sender<Option<Arc<Snapshot>>>,
+    /// Held by the refresh that runs.
+    refresh: Arc<AsyncMutex<()>>,
+    /// When the last gateway write ended, so a Fetch that waits can probe at once.
+    written: watch::Sender<Option<Instant>>,
+}
+
+impl Topic {
+    /// Whether its newest probe started at `since` or later.
+    fn newer_than(&self, since: Instant) -> bool {
+        self.newest
+            .borrow()
+            .as_ref()
+            .is_some_and(|snapshot| snapshot.started >= since)
+    }
+}
+
+impl ProbeBoard {
+    /// A probe of `topic` that started at `since` or later. `None` if none comes by `deadline`.
+    ///
+    /// Runs `load` in a task when no refresh of `topic` runs.
+    pub async fn probe<F, Fut>(
+        &self,
+        topic: &str,
+        since: Instant,
+        deadline: Instant,
+        load: F,
+    ) -> Option<Arc<Snapshot>>
+    where
+        F: FnOnce() -> Fut,
+        Fut: Future<Output = TopicProbed> + Send + 'static,
+    {
+        let topic = self.topic(topic);
+        let mut newest = topic.newest.subscribe();
+        let mut load = Some(load);
+        loop {
+            if let Some(snapshot) = newest
+                .borrow_and_update()
+                .as_ref()
+                .filter(|snapshot| snapshot.started >= since)
+            {
+                return Some(Arc::clone(snapshot));
+            }
+            if Instant::now() >= deadline {
+                return None;
+            }
+            if load.is_some()
+                && let Ok(running) = Arc::clone(&topic.refresh).try_lock_owned()
+                && let Some(load) = load.take()
+            {
+                let topic = Arc::clone(&topic);
+                let pending = load();
+                tokio::spawn(async move {
+                    let started = Instant::now();
+                    let probe = pending.await;
+                    // Unlock first. A waiter that this wakes and that wants a newer probe must
+                    // find the lock free, or it waits out its deadline.
+                    drop(running);
+                    topic
+                        .newest
+                        .send_replace(Some(Arc::new(Snapshot { started, probe })));
+                });
+            }
+            timeout_at(deadline, newest.changed()).await.ok()?.ok()?;
+        }
+    }
+
+    /// The newest probe of `topic`, however old. Loads nothing.
+    pub fn newest(&self, topic: &str) -> Option<Arc<Snapshot>> {
+        let topics = self.topics.lock().unwrap_or_else(PoisonError::into_inner);
+        topics.by_name.get(topic)?.newest.borrow().clone()
+    }
+
+    /// Marks a gateway write to `topic` that ended just now. Wakes the Fetches that wait on it.
+    pub fn wrote(&self, topic: &str) {
+        let topics = self.topics.lock().unwrap_or_else(PoisonError::into_inner);
+        if let Some(topic) = topics.by_name.get(topic) {
+            topic.written.send_replace(Some(Instant::now()));
+        }
+    }
+
+    /// Changes on each [`Self::wrote`] for `topic` after this call, to the time of that write.
+    pub fn writes(&self, topic: &str) -> watch::Receiver<Option<Instant>> {

Review Comment:
   waiting Fetch's wake can be silently lost forever on a topic sweep (large topic counts). Falls back to 100ms polling, doesn't hang.



##########
gateways/kafka/src/protocol/handlers/fetch.rs:
##########
@@ -97,6 +179,1167 @@ pub fn encode_response(version: i16, req: &FetchRequest) -> Result<Bytes> {
     encode_inner(version, topics, ERROR_NONE)
 }
 
+fn decode(state: &GatewayState, version: i16, body: Bytes) -> Result<FetchRequest> {
+    decode_guarded::<FetchRequest>(version, body, |v, b| {
+        validate_fetch_shape(v, b, state.max_frame_size)
+    })
+}
+
+/// Whether `request` names every partition it wants. Anything else continues a session, and
+/// this gateway opens none: it always answers `session_id` 0.
+const fn is_full(version: i16, request: &FetchRequest) -> bool {
+    version < SESSION_MIN_VERSION || matches!(request.session_epoch, INITIAL_EPOCH | FINAL_EPOCH)
+}
+
+/// Reads every requested partition once. When that finds nothing, waits for records up to
+/// `max_wait_ms` and reads again.
+///
+/// Returns the read slot too, if the read took one. Keep it until the response is encoded.
+async fn fetch(
+    bridge: &Arc<IggyBridge>,
+    state: &GatewayState,
+    request: &FetchRequest,
+) -> (Vec<FetchableTopicResponse>, Option<FetchSlot>) {
+    let started = Instant::now();
+    let give_up_at = started + REQUEST_DEADLINE;
+    let fetch = Fetch::new(bridge, state, request, give_up_at);
+    // A shared probe will do: an offset past it goes to a poll, not straight to a 1.
+    let mut probes = fetch.probe_all(recent(started)).await;
+    let (mut answers, mut slot) = fetch.read(&probes).await;
+    if waits(request, &answers) {
+        // No slot while it waits.
+        drop(slot);
+        let held: Vec<bool> = answers
+            .iter()
+            .map(|answer| retried_at_once(answer.error_code))
+            .collect();
+        let wait_until = started + fetch.max_wait;
+        probes = fetch
+            .wait(probes, &held, request.min_bytes, wait_until)
+            .await;
+        // Kafka reads again when the wait ends, too.
+        (answers, slot) = fetch.read(&probes).await;
+    }
+    (group(request, &fetch.wanted, answers), slot)
+}
+
+/// Kafka answers at once when a partition fails, when the request allows no wait, or when the
+/// records read reach `min_bytes`. Otherwise it waits.
+///
+/// A 6 or a -1 waits too. See [`retried_at_once`].
+fn waits(request: &FetchRequest, answers: &[PartitionData]) -> bool {
+    let min_bytes = usize::try_from(request.min_bytes).unwrap_or(0);
+    let record_bytes: usize = answers
+        .iter()
+        .map(|answer| answer.records.as_ref().map_or(0, Bytes::len))
+        .sum();
+    request.max_wait_ms > 0
+        && !answers.is_empty()
+        && record_bytes < min_bytes
+        && answers
+            .iter()
+            .all(|answer| answer.error_code == ERROR_NONE || retried_at_once(answer.error_code))
+}
+
+/// Codes the Java consumer fetches again at once after. Sent at once, they make it spin, so they
+/// wait out the request instead.
+const fn retried_at_once(code: i16) -> bool {
+    matches!(
+        code,
+        ERROR_NOT_LEADER_OR_FOLLOWER | ERROR_UNKNOWN_SERVER_ERROR
+    )
+}
+
+fn wait_time(max_wait_ms: i32) -> Duration {
+    Duration::from_millis(u64::try_from(max_wait_ms).unwrap_or(0)).min(MAX_WAIT)
+}
+
+/// When a -1 hold that starts at `now` ends: after the request's wait, but at least
+/// [`PROBE_INTERVAL`] on. A consumer with a short wait then reads a stuck partition at most ten
+/// times a second.
+fn hold_until(now: Instant, max_wait: Duration) -> Instant {
+    now + max_wait.max(PROBE_INTERVAL)
+}
+
+/// The topics to load a new probe for: each one whose newest probe started before `since`, the
+/// oldest first, at most [`MAX_ROUND_TOPICS`].
+fn stale_topics(snapshots: &[Option<Arc<Snapshot>>], since: Instant) -> Vec<usize> {
+    let started = |topic: usize| snapshots[topic].as_ref().map(|snapshot| snapshot.started);
+    let mut stale: Vec<usize> = (0..snapshots.len())
+        .filter(|&topic| started(topic).is_none_or(|started| started < since))
+        .collect();
+    // No probe sorts first, then the oldest, so each topic gets its turn.
+    stale.sort_by_key(|&topic| started(topic));
+    stale.truncate(MAX_ROUND_TOPICS);
+    stale
+}
+
+/// The topics wait round `turn` probes: the next [`MAX_ROUND_TOPICS`] of `count`, in turn.
+fn round(turn: usize, count: usize) -> impl Iterator<Item = usize> {
+    let start = turn.saturating_mul(MAX_ROUND_TOPICS) % count.max(1);
+    (start..start + MAX_ROUND_TOPICS.min(count)).map(move |topic| topic % count)
+}
+
+/// Waits for the next gateway write to any of the topics behind `writes`, then returns the topics
+/// written, at most [`MAX_ROUND_TOPICS`], each with the time of its write, and marks them seen.
+/// Pends while no write can come.
+async fn next_writes(writes: &mut [watch::Receiver<Option<Instant>>]) -> Vec<(usize, Instant)> {
+    let first = {
+        let mut changes: Vec<_> = writes
+            .iter_mut()
+            .map(|write| Some(Box::pin(write.changed())))
+            .collect();
+        poll_fn(|context| {
+            for (topic, slot) in changes.iter_mut().enumerate() {
+                let Some(change) = slot else { continue };
+                match change.as_mut().poll(context) {
+                    // `changed` marks this write seen.
+                    Poll::Ready(Ok(())) => return Poll::Ready(topic),
+                    // The topic left the board, so no write wakes this one.
+                    Poll::Ready(Err(_)) => *slot = None,
+                    Poll::Pending => {}
+                }
+            }
+            Poll::Pending
+        })
+        .await
+    };
+    let mut written = vec![(first, written_at(&mut writes[first]))];
+    written.extend(
+        writes
+            .iter_mut()
+            .enumerate()
+            .filter(|(topic, write)| *topic != first && write.has_changed().unwrap_or(false))
+            .take(MAX_ROUND_TOPICS - 1)
+            .map(|(topic, write)| (topic, written_at(write))),
+    );
+    written
+}
+
+/// When the newest write that `write` shows ended. Marks it seen.
+fn written_at(write: &mut watch::Receiver<Option<Instant>>) -> Instant {
+    let seen = *write.borrow_and_update();
+    seen.unwrap_or_else(Instant::now)
+}
+
+/// One request: what it asks for, and what bounds it.
+struct Fetch<'a> {
+    bridge: &'a Arc<IggyBridge>,
+    state: &'a GatewayState,
+    wanted: Vec<Wanted<'a>>,
+    /// Each topic to probe once, in request order.
+    topics: Vec<&'a str>,
+    response_bytes: usize,
+    give_up_at: Instant,
+    /// The request's wait, at most [`MAX_WAIT`].
+    max_wait: Duration,
+}
+
+impl<'a> Fetch<'a> {
+    fn new(
+        bridge: &'a Arc<IggyBridge>,
+        state: &'a GatewayState,
+        request: &'a FetchRequest,
+        give_up_at: Instant,
+    ) -> Self {
+        let (wanted, topics) = wanted(request);
+        Self {
+            bridge,
+            state,
+            wanted,
+            topics,
+            response_bytes: response_bytes(request.max_bytes, state.max_frame_size),
+            give_up_at,
+            max_wait: wait_time(request.max_wait_ms),
+        }
+    }
+
+    /// Each topic's probe, started at `since` or later.
+    ///
+    /// Loads at most [`MAX_ROUND_TOPICS`] new probes, the oldest first. Other topics keep an older
+    /// probe, or answer 6 without one. So does a topic not probed before `give_up_at`.
+    async fn probe_all(&self, since: Instant) -> Probes {
+        let board = &self.state.probe_board;
+        let mut snapshots: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.newest(topic))
+            .collect();
+        for topic in stale_topics(&snapshots, since) {
+            snapshots[topic] = self
+                .probe_topic(self.topics[topic], since, self.give_up_at)
+                .await;
+        }
+        snapshots
+            .into_iter()
+            .map(|snapshot| {
+                snapshot.map_or(Err(ERROR_NOT_LEADER_OR_FOLLOWER), |snapshot| {
+                    snapshot.probe.clone()
+                })
+            })
+            .collect()
+    }
+
+    /// `topic`'s probe from the board, started at `since` or later. `None` if none comes by
+    /// `deadline`.
+    async fn probe_topic(
+        &self,
+        topic: &str,
+        since: Instant,
+        deadline: Instant,
+    ) -> Option<Arc<Snapshot>> {
+        let load = || {
+            let (bridge, name) = (Arc::clone(self.bridge), topic.to_owned());
+            async move {
+                let probe = bridge.probe(&name).await;
+                probe.map(Arc::new).map_err(|error| refusal(&name, &error))
+            }
+        };
+        self.state
+            .probe_board
+            .probe(topic, since, deadline, load)
+            .await
+    }
+
+    /// The probe of partition `index` of `topic`, started at `since` or later.
+    async fn probe_partition(
+        &self,
+        topic: &str,
+        index: u32,
+        since: Instant,
+    ) -> Option<PartitionProbe> {
+        let snapshot = self.probe_topic(topic, since, self.give_up_at).await?;
+        snapshot.probe.as_ref().ok()?.get(index)
+    }
+
+    /// Probes until the bytes waiting reach `min_bytes`, a partition fails, or `wait_until`
+    /// passes. Holds no slot while it waits.
+    ///
+    /// Each [`PROBE_INTERVAL`], a round probes the next [`MAX_ROUND_TOPICS`] topics. A gateway
+    /// write to a topic probes it at once. A topic not probed keeps its last probe.
+    ///
+    /// `held` marks partitions that answered 6 or -1. They wait it out and end no wait.
+    async fn wait(
+        &self,
+        mut probes: Probes,
+        held: &[bool],
+        min_bytes: i32,
+        wait_until: Instant,
+    ) -> Probes {
+        if held.iter().all(|&held| held) {
+            sleep_until(wait_until).await;
+            return self.probe_all(recent(Instant::now())).await;
+        }
+        let min_bytes = u64::try_from(min_bytes).unwrap_or(0);
+        let board = &self.state.probe_board;
+        let mut writes: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.writes(topic))
+            .collect();
+        let mut turn = 0;
+        // Kept across write wakes, so steady writes to one topic do not stop the rounds.
+        let mut round_at = (Instant::now() + PROBE_INTERVAL).min(wait_until);
+        while Instant::now() < wait_until {
+            let written = tokio::select! {
+                () = sleep_until(round_at) => None,
+                written = next_writes(&mut writes) => Some(written),
+            };
+            let timed = written.is_none();
+            // A write needs a probe that started after it. A round needs one newer than the last.
+            let due = written.unwrap_or_else(|| {
+                turn += 1;
+                let since = recent(Instant::now());
+                round(turn - 1, self.topics.len())
+                    .map(|topic| (topic, since))
+                    .collect()
+            });
+            for (topic, since) in due {
+                // A probe late for the round still lands on the board for the next Fetch.
+                let probe = self.probe_topic(self.topics[topic], since, wait_until);
+                if let Some(snapshot) = probe.await {
+                    probes[topic].clone_from(&snapshot.probe);
+                }
+            }
+            if timed {
+                round_at = (Instant::now() + PROBE_INTERVAL).min(wait_until);
+            }
+            if ready(&self.wanted, held, &probes, self.response_bytes, min_bytes) {
+                break;
+            }
+        }
+        probes
+    }
+
+    /// One answer per requested partition, in request order, and the read slot, if taken.
+    async fn read(&self, probes: &Probes) -> (Vec<PartitionData>, Option<FetchSlot>) {
+        Reader::new(self).read_all(probes).await
+    }
+}
+
+/// One requested partition.
+struct Wanted<'a> {
+    /// Its topic entry in the request.
+    entry: usize,
+    topic: &'a str,
+    partition: i32,
+    fetch_offset: i64,
+    max_bytes: usize,
+    /// Where its probe is, or the code it answers without asking Iggy.
+    probe_at: core::result::Result<ProbeAt, i16>,
+}
+
+/// Where a partition's probe is.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct ProbeAt {
+    /// Its topic's place in `Fetch::topics`.
+    topic: usize,
+    index: u32,
+}
+
+/// Each requested partition once, in request order, and each topic to probe once. A repeat
+/// keeps the first entry.
+///
+/// The Java consumer drops a whole response that leaves out a partition it asked for.
+fn wanted(request: &FetchRequest) -> (Vec<Wanted<'_>>, Vec<&str>) {
+    let total = request
+        .topics
+        .iter()
+        .map(|topic| topic.partitions.len())
+        .sum();
+    let mut seen = HashSet::with_capacity(total);
+    let mut wanted = Vec::with_capacity(total);
+    let mut topics = IndexSet::new();
+    for (entry, topic) in request.topics.iter().enumerate() {
+        let name = topic.topic.as_str();
+        // A name Kafka refuses answers 3 here, so it never takes a place on the probe board.
+        let named = validate_kafka_topic_name("kafka_topic", name)
+            .map_err(|_| ERROR_UNKNOWN_TOPIC_OR_PARTITION);
+        for partition in &topic.partitions {
+            if !seen.insert((name, partition.partition)) {
+                continue;
+            }
+            let probe_at = named
+                .and_then(|()| {
+                    u32::try_from(partition.partition).map_err(|_| ERROR_UNKNOWN_TOPIC_OR_PARTITION)
+                })
+                .map(|index| ProbeAt {
+                    topic: topics.insert_full(name).0,
+                    index,
+                });
+            wanted.push(Wanted {
+                entry,
+                topic: name,
+                partition: partition.partition,
+                fetch_offset: partition.fetch_offset,
+                max_bytes: usize::try_from(partition.partition_max_bytes).unwrap_or(0),
+                probe_at,
+            });
+        }
+    }
+    (wanted, topics.into_iter().collect())
+}
+
+/// Record bytes the whole response may carry: `max_bytes`, at most one frame.
+fn response_bytes(max_bytes: i32, max_frame_size: usize) -> usize {
+    usize::try_from(max_bytes).unwrap_or(0).min(max_frame_size)
+}
+
+/// Per topic in `Fetch::topics`, its probe, or one code for the whole topic.
+type Probes = Vec<TopicProbed>;
+
+/// Whether a partition now fails, as an error ends Kafka's wait too, or the bytes waiting reach
+/// `min_bytes`. Skips `held` partitions.
+fn ready(
+    wanted: &[Wanted<'_>],
+    held: &[bool],
+    probes: &Probes,
+    response_bytes: usize,
+    min_bytes: u64,
+) -> bool {
+    let mut waiting = 0u64;
+    for (want, _) in wanted.iter().zip(held).filter(|&(_, &held)| !held) {
+        match position(want, probes) {
+            Position::Refused(_) => return true,
+            // Past the end of this probe, or no message kept. A newer probe, or the read after
+            // the wait, decides.
+            Position::CaughtUp(_) | Position::Unsure { .. } => {}
+            Position::Behind { offset, probe, .. } => {
+                let budget = want.max_bytes.min(response_bytes);
+                waiting = waiting.saturating_add(bytes_waiting(offset, probe, budget));
+            }
+        }
+    }
+    waiting >= min_bytes
+}
+
+/// Estimated bytes past `offset`, at most `budget`. Kafka's delayed fetch counts the same way.
+fn bytes_waiting(offset: u64, probe: PartitionProbe, budget: usize) -> u64 {
+    probe
+        .high_watermark
+        .saturating_sub(offset)
+        .saturating_mul(probe.average_size)
+        .min(u64::try_from(budget).unwrap_or(u64::MAX))
+}
+
+/// Where a requested offset stands against the probe.
+#[derive(Debug, PartialEq, Eq)]
+enum Position {
+    /// Answer this code, with no records.
+    Refused(i16),
+    /// At the high watermark. Answer 0, with no records.
+    CaughtUp(PartitionProbe),
+    /// Records wait in partition `index` from `offset` on.
+    Behind {
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    },
+    /// The probe cannot place `offset`. One poll decides.
+    Unsure {
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    },
+}
+
+fn position(want: &Wanted<'_>, probes: &Probes) -> Position {
+    let at = match want.probe_at {
+        Ok(at) => at,
+        Err(code) => return Position::Refused(code),
+    };
+    // `Fetch::probe_all` probes every topic in `Fetch::topics`, in order.
+    let probe = match &probes[at.topic] {
+        Ok(topic) => match topic.get(at.index) {
+            Some(probe) => probe,
+            None => return Position::Refused(ERROR_UNKNOWN_TOPIC_OR_PARTITION),
+        },
+        Err(code) => return Position::Refused(*code),
+    };
+    if probe.is_loading() {
+        return Position::Refused(ERROR_NOT_LEADER_OR_FOLLOWER);
+    }
+    // Below the oldest retained offset is in range: Iggy reads from the first retained message,
+    // and Kafka consumers accept the gap.
+    match u64::try_from(want.fetch_offset) {
+        Ok(offset) if offset == probe.high_watermark => Position::CaughtUp(probe),
+        // Retention can remove every message, and a server with no stats reads the same. Past
+        // the end, a shared probe can predate records the consumer already read.
+        Ok(offset) if probe.messages_count == 0 || offset > probe.high_watermark => {
+            Position::Unsure {
+                index: at.index,
+                offset,
+                probe,
+            }
+        }
+        Ok(offset) => Position::Behind {
+            index: at.index,
+            offset,
+            probe,
+        },
+        Err(_) => Position::Refused(ERROR_OFFSET_OUT_OF_RANGE),
+    }
+}
+
+/// Reads partitions in request order, as Kafka does from v3, and spends one byte budget on them.
+struct Reader<'a> {
+    fetch: &'a Fetch<'a>,
+    bytes_left: usize,
+    /// No partition has answered with records yet, so the next one returns at least one, whatever
+    /// the limits say (KIP-74). A record larger than every limit would stall the consumer
+    /// otherwise.
+    owes_first_record: bool,
+    /// Taken at the first poll. A poll given up on keeps it until the poll ends.
+    slot: Option<FetchSlot>,
+}
+
+impl<'a> Reader<'a> {
+    const fn new(fetch: &'a Fetch<'a>) -> Self {
+        Self {
+            fetch,
+            bytes_left: fetch.response_bytes,
+            owes_first_record: true,
+            slot: None,
+        }
+    }
+
+    /// One answer per requested partition, in request order, and the slot, if taken.
+    async fn read_all(mut self, probes: &Probes) -> (Vec<PartitionData>, Option<FetchSlot>) {
+        let fetch = self.fetch;
+        let mut answers = Vec::with_capacity(fetch.wanted.len());
+        for want in &fetch.wanted {
+            let answer = match position(want, probes) {
+                Position::Refused(code) => refused(want.partition, code),
+                Position::CaughtUp(probe) => {
+                    served(want.partition, probe.high_watermark, Bytes::new())
+                }
+                Position::Behind { index, offset, .. } | Position::Unsure { index, offset, .. }
+                    if held(
+                        &fetch.state.stuck_offsets,
+                        want.topic,
+                        index,
+                        offset,
+                        Instant::now(),
+                    ) =>
+                {
+                    refused(want.partition, ERROR_UNKNOWN_SERVER_ERROR)
+                }
+                Position::Behind {
+                    index,
+                    offset,
+                    probe,
+                } => {
+                    let polled = Polled::new(offset, probe.high_watermark);
+                    self.read(want, index, offset, probe, polled).await
+                }
+                Position::Unsure {
+                    index,
+                    offset,
+                    probe,
+                } => self.settle(want, index, offset, probe).await,
+            };
+            answers.push(answer);
+        }
+        (answers, self.slot)
+    }
+
+    /// Polls one partition that has records waiting, and answers with what its budget holds.
+    async fn read(
+        &mut self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+        mut polled: Polled,
+    ) -> PartitionData {
+        let budget = want.max_bytes.min(self.bytes_left);
+        // Unless a record is owed, skip a poll that likely brings back nothing that fits.
+        let average = usize::try_from(probe.average_size).unwrap_or(usize::MAX);
+        if self.owes_first_record || budget >= average.max(1) {
+            while let Some(count) = next_page(&polled, budget, probe.average_size) {
+                let asked = Instant::now();
+                let Some(page) = self.poll(want.topic, index, polled.next, count).await else {
+                    break;
+                };
+                match page {
+                    // The probe showed records, yet the first poll found none.
+                    Ok(page) if page.messages.is_empty() && polled.messages.is_empty() => {
+                        return self
+                            .after_empty_poll(want, index, offset, probe, asked)
+                            .await;
+                    }
+                    Ok(page) => polled.add(page, count),
+                    Err(error) if polled.messages.is_empty() => {
+                        return self.refuse(want, index, offset, &error);
+                    }
+                    // Serve what the earlier polls brought.
+                    Err(_) => break,
+                }
+            }
+        }
+
+        let keep_one = self.owes_first_record;
+        let encoded = off_worker(polled.bytes >= CODEC_OFF_WORKER_BYTES, || {
+            encode_records(&polled.messages, offset, budget, keep_one)
+        });
+        match encoded {
+            Ok(batch) => {
+                self.bytes_left = self.bytes_left.saturating_sub(batch.len());
+                self.owes_first_record &= batch.is_empty();
+                served(want.partition, polled.high_watermark, batch)
+            }
+            Err(error) => {
+                let stuck = &self.fetch.state.stuck_offsets;
+                let now = Instant::now();
+                let first = hold(stuck, want.topic, index, offset, now, self.fetch.max_wait);
+                log_stuck(first, want.topic, index, offset, &error);
+                refused(want.partition, ERROR_UNKNOWN_SERVER_ERROR)
+            }
+        }
+    }
+
+    /// Reads a partition the probe cannot place, with a poll at `offset`.
+    ///
+    /// - Records: serve them. The probe missed them.
+    /// - Nothing, and Iggy's commit ends just before `offset`: caught up.
+    /// - Nothing else: a probe taken after the poll decides. See [`empty_poll`].
+    async fn settle(
+        &mut self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    ) -> PartitionData {
+        // Sized as a read's first page, since an empty answer costs the same round trip.
+        let budget = want.max_bytes.min(self.bytes_left);
+        let count = poll_count(budget, probe.average_size, u64::from(MAX_PAGE_COUNT));
+        let asked = Instant::now();
+        match self.poll(want.topic, index, offset, count).await {
+            // Never below the offset, or the consumer reports negative lag.
+            None => served(
+                want.partition,
+                probe.high_watermark.max(offset),
+                Bytes::new(),
+            ),
+            Some(Err(error)) => self.refuse(want, index, offset, &error),
+            Some(Ok(page)) if !page.messages.is_empty() => {
+                let mut polled = Polled::new(offset, probe.high_watermark);
+                polled.add(page, count);
+                self.read(want, index, offset, probe, polled).await
+            }
+            Some(Ok(page)) if caught_up(offset, page.current_offset) => {
+                served(want.partition, offset, Bytes::new())
+            }
+            Some(Ok(_)) => {
+                self.after_empty_poll(want, index, offset, probe, asked)
+                    .await
+            }
+        }
+    }
+
+    /// Answers an empty poll at `offset`, made at `asked`, from `before` and a probe taken after
+    /// it. See [`empty_poll`].
+    async fn after_empty_poll(
+        &self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        before: PartitionProbe,
+        asked: Instant,
+    ) -> PartitionData {
+        let after = self.fetch.probe_partition(want.topic, index, asked).await;

Review Comment:
   FETCH_SLOTS=4 — after_empty_poll holds a fetch slot while doing its own confirming get_topic; only 4 slots exist gateway-wide, so 4 idle-consumer fetches stall every other Fetch up to 20s.
   



##########
gateways/kafka/src/protocol/handlers/fetch.rs:
##########
@@ -97,6 +179,1167 @@ pub fn encode_response(version: i16, req: &FetchRequest) -> Result<Bytes> {
     encode_inner(version, topics, ERROR_NONE)
 }
 
+fn decode(state: &GatewayState, version: i16, body: Bytes) -> Result<FetchRequest> {
+    decode_guarded::<FetchRequest>(version, body, |v, b| {
+        validate_fetch_shape(v, b, state.max_frame_size)
+    })
+}
+
+/// Whether `request` names every partition it wants. Anything else continues a session, and
+/// this gateway opens none: it always answers `session_id` 0.
+const fn is_full(version: i16, request: &FetchRequest) -> bool {
+    version < SESSION_MIN_VERSION || matches!(request.session_epoch, INITIAL_EPOCH | FINAL_EPOCH)
+}
+
+/// Reads every requested partition once. When that finds nothing, waits for records up to
+/// `max_wait_ms` and reads again.
+///
+/// Returns the read slot too, if the read took one. Keep it until the response is encoded.
+async fn fetch(
+    bridge: &Arc<IggyBridge>,
+    state: &GatewayState,
+    request: &FetchRequest,
+) -> (Vec<FetchableTopicResponse>, Option<FetchSlot>) {
+    let started = Instant::now();
+    let give_up_at = started + REQUEST_DEADLINE;
+    let fetch = Fetch::new(bridge, state, request, give_up_at);
+    // A shared probe will do: an offset past it goes to a poll, not straight to a 1.
+    let mut probes = fetch.probe_all(recent(started)).await;
+    let (mut answers, mut slot) = fetch.read(&probes).await;
+    if waits(request, &answers) {
+        // No slot while it waits.
+        drop(slot);
+        let held: Vec<bool> = answers
+            .iter()
+            .map(|answer| retried_at_once(answer.error_code))
+            .collect();
+        let wait_until = started + fetch.max_wait;
+        probes = fetch
+            .wait(probes, &held, request.min_bytes, wait_until)
+            .await;
+        // Kafka reads again when the wait ends, too.
+        (answers, slot) = fetch.read(&probes).await;
+    }
+    (group(request, &fetch.wanted, answers), slot)
+}
+
+/// Kafka answers at once when a partition fails, when the request allows no wait, or when the
+/// records read reach `min_bytes`. Otherwise it waits.
+///
+/// A 6 or a -1 waits too. See [`retried_at_once`].
+fn waits(request: &FetchRequest, answers: &[PartitionData]) -> bool {
+    let min_bytes = usize::try_from(request.min_bytes).unwrap_or(0);
+    let record_bytes: usize = answers
+        .iter()
+        .map(|answer| answer.records.as_ref().map_or(0, Bytes::len))
+        .sum();
+    request.max_wait_ms > 0
+        && !answers.is_empty()
+        && record_bytes < min_bytes
+        && answers
+            .iter()
+            .all(|answer| answer.error_code == ERROR_NONE || retried_at_once(answer.error_code))
+}
+
+/// Codes the Java consumer fetches again at once after. Sent at once, they make it spin, so they
+/// wait out the request instead.
+const fn retried_at_once(code: i16) -> bool {
+    matches!(
+        code,
+        ERROR_NOT_LEADER_OR_FOLLOWER | ERROR_UNKNOWN_SERVER_ERROR
+    )
+}
+
+fn wait_time(max_wait_ms: i32) -> Duration {
+    Duration::from_millis(u64::try_from(max_wait_ms).unwrap_or(0)).min(MAX_WAIT)
+}
+
+/// When a -1 hold that starts at `now` ends: after the request's wait, but at least
+/// [`PROBE_INTERVAL`] on. A consumer with a short wait then reads a stuck partition at most ten
+/// times a second.
+fn hold_until(now: Instant, max_wait: Duration) -> Instant {
+    now + max_wait.max(PROBE_INTERVAL)
+}
+
+/// The topics to load a new probe for: each one whose newest probe started before `since`, the
+/// oldest first, at most [`MAX_ROUND_TOPICS`].
+fn stale_topics(snapshots: &[Option<Arc<Snapshot>>], since: Instant) -> Vec<usize> {
+    let started = |topic: usize| snapshots[topic].as_ref().map(|snapshot| snapshot.started);
+    let mut stale: Vec<usize> = (0..snapshots.len())
+        .filter(|&topic| started(topic).is_none_or(|started| started < since))
+        .collect();
+    // No probe sorts first, then the oldest, so each topic gets its turn.
+    stale.sort_by_key(|&topic| started(topic));
+    stale.truncate(MAX_ROUND_TOPICS);
+    stale
+}
+
+/// The topics wait round `turn` probes: the next [`MAX_ROUND_TOPICS`] of `count`, in turn.
+fn round(turn: usize, count: usize) -> impl Iterator<Item = usize> {
+    let start = turn.saturating_mul(MAX_ROUND_TOPICS) % count.max(1);
+    (start..start + MAX_ROUND_TOPICS.min(count)).map(move |topic| topic % count)
+}
+
+/// Waits for the next gateway write to any of the topics behind `writes`, then returns the topics
+/// written, at most [`MAX_ROUND_TOPICS`], each with the time of its write, and marks them seen.
+/// Pends while no write can come.
+async fn next_writes(writes: &mut [watch::Receiver<Option<Instant>>]) -> Vec<(usize, Instant)> {
+    let first = {
+        let mut changes: Vec<_> = writes
+            .iter_mut()
+            .map(|write| Some(Box::pin(write.changed())))
+            .collect();
+        poll_fn(|context| {
+            for (topic, slot) in changes.iter_mut().enumerate() {
+                let Some(change) = slot else { continue };
+                match change.as_mut().poll(context) {
+                    // `changed` marks this write seen.
+                    Poll::Ready(Ok(())) => return Poll::Ready(topic),
+                    // The topic left the board, so no write wakes this one.
+                    Poll::Ready(Err(_)) => *slot = None,
+                    Poll::Pending => {}
+                }
+            }
+            Poll::Pending
+        })
+        .await
+    };
+    let mut written = vec![(first, written_at(&mut writes[first]))];
+    written.extend(
+        writes
+            .iter_mut()
+            .enumerate()
+            .filter(|(topic, write)| *topic != first && write.has_changed().unwrap_or(false))
+            .take(MAX_ROUND_TOPICS - 1)
+            .map(|(topic, write)| (topic, written_at(write))),
+    );
+    written
+}
+
+/// When the newest write that `write` shows ended. Marks it seen.
+fn written_at(write: &mut watch::Receiver<Option<Instant>>) -> Instant {
+    let seen = *write.borrow_and_update();
+    seen.unwrap_or_else(Instant::now)
+}
+
+/// One request: what it asks for, and what bounds it.
+struct Fetch<'a> {
+    bridge: &'a Arc<IggyBridge>,
+    state: &'a GatewayState,
+    wanted: Vec<Wanted<'a>>,
+    /// Each topic to probe once, in request order.
+    topics: Vec<&'a str>,
+    response_bytes: usize,
+    give_up_at: Instant,
+    /// The request's wait, at most [`MAX_WAIT`].
+    max_wait: Duration,
+}
+
+impl<'a> Fetch<'a> {
+    fn new(
+        bridge: &'a Arc<IggyBridge>,
+        state: &'a GatewayState,
+        request: &'a FetchRequest,
+        give_up_at: Instant,
+    ) -> Self {
+        let (wanted, topics) = wanted(request);
+        Self {
+            bridge,
+            state,
+            wanted,
+            topics,
+            response_bytes: response_bytes(request.max_bytes, state.max_frame_size),
+            give_up_at,
+            max_wait: wait_time(request.max_wait_ms),
+        }
+    }
+
+    /// Each topic's probe, started at `since` or later.
+    ///
+    /// Loads at most [`MAX_ROUND_TOPICS`] new probes, the oldest first. Other topics keep an older
+    /// probe, or answer 6 without one. So does a topic not probed before `give_up_at`.
+    async fn probe_all(&self, since: Instant) -> Probes {
+        let board = &self.state.probe_board;
+        let mut snapshots: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.newest(topic))
+            .collect();
+        for topic in stale_topics(&snapshots, since) {
+            snapshots[topic] = self

Review Comment:
    Lines 461 / :369-372 — a transient get_topic blip overwrites a good probe with an error/None, turning a partition that actually had data into a false error answer.
   



##########
gateways/kafka/src/protocol/handlers/fetch.rs:
##########
@@ -97,6 +179,1167 @@ pub fn encode_response(version: i16, req: &FetchRequest) -> Result<Bytes> {
     encode_inner(version, topics, ERROR_NONE)
 }
 
+fn decode(state: &GatewayState, version: i16, body: Bytes) -> Result<FetchRequest> {
+    decode_guarded::<FetchRequest>(version, body, |v, b| {
+        validate_fetch_shape(v, b, state.max_frame_size)
+    })
+}
+
+/// Whether `request` names every partition it wants. Anything else continues a session, and
+/// this gateway opens none: it always answers `session_id` 0.
+const fn is_full(version: i16, request: &FetchRequest) -> bool {
+    version < SESSION_MIN_VERSION || matches!(request.session_epoch, INITIAL_EPOCH | FINAL_EPOCH)
+}
+
+/// Reads every requested partition once. When that finds nothing, waits for records up to
+/// `max_wait_ms` and reads again.
+///
+/// Returns the read slot too, if the read took one. Keep it until the response is encoded.
+async fn fetch(
+    bridge: &Arc<IggyBridge>,
+    state: &GatewayState,
+    request: &FetchRequest,
+) -> (Vec<FetchableTopicResponse>, Option<FetchSlot>) {
+    let started = Instant::now();
+    let give_up_at = started + REQUEST_DEADLINE;
+    let fetch = Fetch::new(bridge, state, request, give_up_at);
+    // A shared probe will do: an offset past it goes to a poll, not straight to a 1.
+    let mut probes = fetch.probe_all(recent(started)).await;
+    let (mut answers, mut slot) = fetch.read(&probes).await;
+    if waits(request, &answers) {
+        // No slot while it waits.
+        drop(slot);
+        let held: Vec<bool> = answers
+            .iter()
+            .map(|answer| retried_at_once(answer.error_code))
+            .collect();
+        let wait_until = started + fetch.max_wait;
+        probes = fetch
+            .wait(probes, &held, request.min_bytes, wait_until)
+            .await;
+        // Kafka reads again when the wait ends, too.
+        (answers, slot) = fetch.read(&probes).await;
+    }
+    (group(request, &fetch.wanted, answers), slot)
+}
+
+/// Kafka answers at once when a partition fails, when the request allows no wait, or when the
+/// records read reach `min_bytes`. Otherwise it waits.
+///
+/// A 6 or a -1 waits too. See [`retried_at_once`].
+fn waits(request: &FetchRequest, answers: &[PartitionData]) -> bool {
+    let min_bytes = usize::try_from(request.min_bytes).unwrap_or(0);
+    let record_bytes: usize = answers
+        .iter()
+        .map(|answer| answer.records.as_ref().map_or(0, Bytes::len))
+        .sum();
+    request.max_wait_ms > 0
+        && !answers.is_empty()
+        && record_bytes < min_bytes
+        && answers
+            .iter()
+            .all(|answer| answer.error_code == ERROR_NONE || retried_at_once(answer.error_code))
+}
+
+/// Codes the Java consumer fetches again at once after. Sent at once, they make it spin, so they
+/// wait out the request instead.
+const fn retried_at_once(code: i16) -> bool {
+    matches!(
+        code,
+        ERROR_NOT_LEADER_OR_FOLLOWER | ERROR_UNKNOWN_SERVER_ERROR
+    )
+}
+
+fn wait_time(max_wait_ms: i32) -> Duration {
+    Duration::from_millis(u64::try_from(max_wait_ms).unwrap_or(0)).min(MAX_WAIT)
+}
+
+/// When a -1 hold that starts at `now` ends: after the request's wait, but at least
+/// [`PROBE_INTERVAL`] on. A consumer with a short wait then reads a stuck partition at most ten
+/// times a second.
+fn hold_until(now: Instant, max_wait: Duration) -> Instant {
+    now + max_wait.max(PROBE_INTERVAL)
+}
+
+/// The topics to load a new probe for: each one whose newest probe started before `since`, the
+/// oldest first, at most [`MAX_ROUND_TOPICS`].
+fn stale_topics(snapshots: &[Option<Arc<Snapshot>>], since: Instant) -> Vec<usize> {
+    let started = |topic: usize| snapshots[topic].as_ref().map(|snapshot| snapshot.started);
+    let mut stale: Vec<usize> = (0..snapshots.len())
+        .filter(|&topic| started(topic).is_none_or(|started| started < since))
+        .collect();
+    // No probe sorts first, then the oldest, so each topic gets its turn.
+    stale.sort_by_key(|&topic| started(topic));
+    stale.truncate(MAX_ROUND_TOPICS);
+    stale
+}
+
+/// The topics wait round `turn` probes: the next [`MAX_ROUND_TOPICS`] of `count`, in turn.
+fn round(turn: usize, count: usize) -> impl Iterator<Item = usize> {
+    let start = turn.saturating_mul(MAX_ROUND_TOPICS) % count.max(1);
+    (start..start + MAX_ROUND_TOPICS.min(count)).map(move |topic| topic % count)
+}
+
+/// Waits for the next gateway write to any of the topics behind `writes`, then returns the topics
+/// written, at most [`MAX_ROUND_TOPICS`], each with the time of its write, and marks them seen.
+/// Pends while no write can come.
+async fn next_writes(writes: &mut [watch::Receiver<Option<Instant>>]) -> Vec<(usize, Instant)> {
+    let first = {
+        let mut changes: Vec<_> = writes
+            .iter_mut()
+            .map(|write| Some(Box::pin(write.changed())))
+            .collect();
+        poll_fn(|context| {
+            for (topic, slot) in changes.iter_mut().enumerate() {
+                let Some(change) = slot else { continue };
+                match change.as_mut().poll(context) {
+                    // `changed` marks this write seen.
+                    Poll::Ready(Ok(())) => return Poll::Ready(topic),
+                    // The topic left the board, so no write wakes this one.
+                    Poll::Ready(Err(_)) => *slot = None,
+                    Poll::Pending => {}
+                }
+            }
+            Poll::Pending
+        })
+        .await
+    };
+    let mut written = vec![(first, written_at(&mut writes[first]))];
+    written.extend(
+        writes
+            .iter_mut()
+            .enumerate()
+            .filter(|(topic, write)| *topic != first && write.has_changed().unwrap_or(false))
+            .take(MAX_ROUND_TOPICS - 1)
+            .map(|(topic, write)| (topic, written_at(write))),
+    );
+    written
+}
+
+/// When the newest write that `write` shows ended. Marks it seen.
+fn written_at(write: &mut watch::Receiver<Option<Instant>>) -> Instant {
+    let seen = *write.borrow_and_update();
+    seen.unwrap_or_else(Instant::now)
+}
+
+/// One request: what it asks for, and what bounds it.
+struct Fetch<'a> {
+    bridge: &'a Arc<IggyBridge>,
+    state: &'a GatewayState,
+    wanted: Vec<Wanted<'a>>,
+    /// Each topic to probe once, in request order.
+    topics: Vec<&'a str>,
+    response_bytes: usize,
+    give_up_at: Instant,
+    /// The request's wait, at most [`MAX_WAIT`].
+    max_wait: Duration,
+}
+
+impl<'a> Fetch<'a> {
+    fn new(
+        bridge: &'a Arc<IggyBridge>,
+        state: &'a GatewayState,
+        request: &'a FetchRequest,
+        give_up_at: Instant,
+    ) -> Self {
+        let (wanted, topics) = wanted(request);
+        Self {
+            bridge,
+            state,
+            wanted,
+            topics,
+            response_bytes: response_bytes(request.max_bytes, state.max_frame_size),
+            give_up_at,
+            max_wait: wait_time(request.max_wait_ms),
+        }
+    }
+
+    /// Each topic's probe, started at `since` or later.
+    ///
+    /// Loads at most [`MAX_ROUND_TOPICS`] new probes, the oldest first. Other topics keep an older
+    /// probe, or answer 6 without one. So does a topic not probed before `give_up_at`.
+    async fn probe_all(&self, since: Instant) -> Probes {
+        let board = &self.state.probe_board;
+        let mut snapshots: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.newest(topic))
+            .collect();
+        for topic in stale_topics(&snapshots, since) {
+            snapshots[topic] = self
+                .probe_topic(self.topics[topic], since, self.give_up_at)
+                .await;
+        }
+        snapshots
+            .into_iter()
+            .map(|snapshot| {
+                snapshot.map_or(Err(ERROR_NOT_LEADER_OR_FOLLOWER), |snapshot| {
+                    snapshot.probe.clone()
+                })
+            })
+            .collect()
+    }
+
+    /// `topic`'s probe from the board, started at `since` or later. `None` if none comes by
+    /// `deadline`.
+    async fn probe_topic(
+        &self,
+        topic: &str,
+        since: Instant,
+        deadline: Instant,
+    ) -> Option<Arc<Snapshot>> {
+        let load = || {
+            let (bridge, name) = (Arc::clone(self.bridge), topic.to_owned());
+            async move {
+                let probe = bridge.probe(&name).await;
+                probe.map(Arc::new).map_err(|error| refusal(&name, &error))
+            }
+        };
+        self.state
+            .probe_board
+            .probe(topic, since, deadline, load)
+            .await
+    }
+
+    /// The probe of partition `index` of `topic`, started at `since` or later.
+    async fn probe_partition(
+        &self,
+        topic: &str,
+        index: u32,
+        since: Instant,
+    ) -> Option<PartitionProbe> {
+        let snapshot = self.probe_topic(topic, since, self.give_up_at).await?;
+        snapshot.probe.as_ref().ok()?.get(index)
+    }
+
+    /// Probes until the bytes waiting reach `min_bytes`, a partition fails, or `wait_until`
+    /// passes. Holds no slot while it waits.
+    ///
+    /// Each [`PROBE_INTERVAL`], a round probes the next [`MAX_ROUND_TOPICS`] topics. A gateway
+    /// write to a topic probes it at once. A topic not probed keeps its last probe.
+    ///
+    /// `held` marks partitions that answered 6 or -1. They wait it out and end no wait.
+    async fn wait(
+        &self,
+        mut probes: Probes,
+        held: &[bool],
+        min_bytes: i32,
+        wait_until: Instant,
+    ) -> Probes {
+        if held.iter().all(|&held| held) {
+            sleep_until(wait_until).await;
+            return self.probe_all(recent(Instant::now())).await;
+        }
+        let min_bytes = u64::try_from(min_bytes).unwrap_or(0);
+        let board = &self.state.probe_board;
+        let mut writes: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.writes(topic))
+            .collect();
+        let mut turn = 0;
+        // Kept across write wakes, so steady writes to one topic do not stop the rounds.
+        let mut round_at = (Instant::now() + PROBE_INTERVAL).min(wait_until);
+        while Instant::now() < wait_until {
+            let written = tokio::select! {
+                () = sleep_until(round_at) => None,
+                written = next_writes(&mut writes) => Some(written),
+            };
+            let timed = written.is_none();
+            // A write needs a probe that started after it. A round needs one newer than the last.
+            let due = written.unwrap_or_else(|| {
+                turn += 1;
+                let since = recent(Instant::now());
+                round(turn - 1, self.topics.len())
+                    .map(|topic| (topic, since))
+                    .collect()
+            });
+            for (topic, since) in due {
+                // A probe late for the round still lands on the board for the next Fetch.
+                let probe = self.probe_topic(self.topics[topic], since, wait_until);
+                if let Some(snapshot) = probe.await {
+                    probes[topic].clone_from(&snapshot.probe);
+                }
+            }
+            if timed {
+                round_at = (Instant::now() + PROBE_INTERVAL).min(wait_until);
+            }
+            if ready(&self.wanted, held, &probes, self.response_bytes, min_bytes) {
+                break;
+            }
+        }
+        probes
+    }
+
+    /// One answer per requested partition, in request order, and the read slot, if taken.
+    async fn read(&self, probes: &Probes) -> (Vec<PartitionData>, Option<FetchSlot>) {
+        Reader::new(self).read_all(probes).await
+    }
+}
+
+/// One requested partition.
+struct Wanted<'a> {
+    /// Its topic entry in the request.
+    entry: usize,
+    topic: &'a str,
+    partition: i32,
+    fetch_offset: i64,
+    max_bytes: usize,
+    /// Where its probe is, or the code it answers without asking Iggy.
+    probe_at: core::result::Result<ProbeAt, i16>,
+}
+
+/// Where a partition's probe is.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct ProbeAt {
+    /// Its topic's place in `Fetch::topics`.
+    topic: usize,
+    index: u32,
+}
+
+/// Each requested partition once, in request order, and each topic to probe once. A repeat
+/// keeps the first entry.
+///
+/// The Java consumer drops a whole response that leaves out a partition it asked for.
+fn wanted(request: &FetchRequest) -> (Vec<Wanted<'_>>, Vec<&str>) {
+    let total = request
+        .topics
+        .iter()
+        .map(|topic| topic.partitions.len())
+        .sum();
+    let mut seen = HashSet::with_capacity(total);
+    let mut wanted = Vec::with_capacity(total);
+    let mut topics = IndexSet::new();
+    for (entry, topic) in request.topics.iter().enumerate() {
+        let name = topic.topic.as_str();
+        // A name Kafka refuses answers 3 here, so it never takes a place on the probe board.
+        let named = validate_kafka_topic_name("kafka_topic", name)
+            .map_err(|_| ERROR_UNKNOWN_TOPIC_OR_PARTITION);
+        for partition in &topic.partitions {
+            if !seen.insert((name, partition.partition)) {
+                continue;
+            }
+            let probe_at = named
+                .and_then(|()| {
+                    u32::try_from(partition.partition).map_err(|_| ERROR_UNKNOWN_TOPIC_OR_PARTITION)
+                })
+                .map(|index| ProbeAt {
+                    topic: topics.insert_full(name).0,
+                    index,
+                });
+            wanted.push(Wanted {
+                entry,
+                topic: name,
+                partition: partition.partition,
+                fetch_offset: partition.fetch_offset,
+                max_bytes: usize::try_from(partition.partition_max_bytes).unwrap_or(0),
+                probe_at,
+            });
+        }
+    }
+    (wanted, topics.into_iter().collect())
+}
+
+/// Record bytes the whole response may carry: `max_bytes`, at most one frame.
+fn response_bytes(max_bytes: i32, max_frame_size: usize) -> usize {
+    usize::try_from(max_bytes).unwrap_or(0).min(max_frame_size)
+}
+
+/// Per topic in `Fetch::topics`, its probe, or one code for the whole topic.
+type Probes = Vec<TopicProbed>;
+
+/// Whether a partition now fails, as an error ends Kafka's wait too, or the bytes waiting reach
+/// `min_bytes`. Skips `held` partitions.
+fn ready(
+    wanted: &[Wanted<'_>],
+    held: &[bool],
+    probes: &Probes,
+    response_bytes: usize,
+    min_bytes: u64,
+) -> bool {
+    let mut waiting = 0u64;
+    for (want, _) in wanted.iter().zip(held).filter(|&(_, &held)| !held) {
+        match position(want, probes) {
+            Position::Refused(_) => return true,
+            // Past the end of this probe, or no message kept. A newer probe, or the read after
+            // the wait, decides.
+            Position::CaughtUp(_) | Position::Unsure { .. } => {}
+            Position::Behind { offset, probe, .. } => {
+                let budget = want.max_bytes.min(response_bytes);
+                waiting = waiting.saturating_add(bytes_waiting(offset, probe, budget));
+            }
+        }
+    }
+    waiting >= min_bytes
+}
+
+/// Estimated bytes past `offset`, at most `budget`. Kafka's delayed fetch counts the same way.
+fn bytes_waiting(offset: u64, probe: PartitionProbe, budget: usize) -> u64 {
+    probe
+        .high_watermark
+        .saturating_sub(offset)
+        .saturating_mul(probe.average_size)
+        .min(u64::try_from(budget).unwrap_or(u64::MAX))
+}
+
+/// Where a requested offset stands against the probe.
+#[derive(Debug, PartialEq, Eq)]
+enum Position {
+    /// Answer this code, with no records.
+    Refused(i16),
+    /// At the high watermark. Answer 0, with no records.
+    CaughtUp(PartitionProbe),
+    /// Records wait in partition `index` from `offset` on.
+    Behind {
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    },
+    /// The probe cannot place `offset`. One poll decides.
+    Unsure {
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    },
+}
+
+fn position(want: &Wanted<'_>, probes: &Probes) -> Position {
+    let at = match want.probe_at {
+        Ok(at) => at,
+        Err(code) => return Position::Refused(code),
+    };
+    // `Fetch::probe_all` probes every topic in `Fetch::topics`, in order.
+    let probe = match &probes[at.topic] {
+        Ok(topic) => match topic.get(at.index) {
+            Some(probe) => probe,
+            None => return Position::Refused(ERROR_UNKNOWN_TOPIC_OR_PARTITION),
+        },
+        Err(code) => return Position::Refused(*code),
+    };
+    if probe.is_loading() {
+        return Position::Refused(ERROR_NOT_LEADER_OR_FOLLOWER);
+    }
+    // Below the oldest retained offset is in range: Iggy reads from the first retained message,
+    // and Kafka consumers accept the gap.
+    match u64::try_from(want.fetch_offset) {
+        Ok(offset) if offset == probe.high_watermark => Position::CaughtUp(probe),
+        // Retention can remove every message, and a server with no stats reads the same. Past
+        // the end, a shared probe can predate records the consumer already read.
+        Ok(offset) if probe.messages_count == 0 || offset > probe.high_watermark => {
+            Position::Unsure {
+                index: at.index,
+                offset,
+                probe,
+            }
+        }
+        Ok(offset) => Position::Behind {
+            index: at.index,
+            offset,
+            probe,
+        },
+        Err(_) => Position::Refused(ERROR_OFFSET_OUT_OF_RANGE),
+    }
+}
+
+/// Reads partitions in request order, as Kafka does from v3, and spends one byte budget on them.
+struct Reader<'a> {
+    fetch: &'a Fetch<'a>,
+    bytes_left: usize,
+    /// No partition has answered with records yet, so the next one returns at least one, whatever
+    /// the limits say (KIP-74). A record larger than every limit would stall the consumer
+    /// otherwise.
+    owes_first_record: bool,
+    /// Taken at the first poll. A poll given up on keeps it until the poll ends.
+    slot: Option<FetchSlot>,
+}
+
+impl<'a> Reader<'a> {
+    const fn new(fetch: &'a Fetch<'a>) -> Self {
+        Self {
+            fetch,
+            bytes_left: fetch.response_bytes,
+            owes_first_record: true,
+            slot: None,
+        }
+    }
+
+    /// One answer per requested partition, in request order, and the slot, if taken.
+    async fn read_all(mut self, probes: &Probes) -> (Vec<PartitionData>, Option<FetchSlot>) {
+        let fetch = self.fetch;
+        let mut answers = Vec::with_capacity(fetch.wanted.len());
+        for want in &fetch.wanted {
+            let answer = match position(want, probes) {
+                Position::Refused(code) => refused(want.partition, code),
+                Position::CaughtUp(probe) => {
+                    served(want.partition, probe.high_watermark, Bytes::new())
+                }
+                Position::Behind { index, offset, .. } | Position::Unsure { index, offset, .. }
+                    if held(
+                        &fetch.state.stuck_offsets,
+                        want.topic,
+                        index,
+                        offset,
+                        Instant::now(),
+                    ) =>
+                {
+                    refused(want.partition, ERROR_UNKNOWN_SERVER_ERROR)
+                }
+                Position::Behind {
+                    index,
+                    offset,
+                    probe,
+                } => {
+                    let polled = Polled::new(offset, probe.high_watermark);
+                    self.read(want, index, offset, probe, polled).await
+                }
+                Position::Unsure {
+                    index,
+                    offset,
+                    probe,
+                } => self.settle(want, index, offset, probe).await,
+            };
+            answers.push(answer);
+        }
+        (answers, self.slot)
+    }
+
+    /// Polls one partition that has records waiting, and answers with what its budget holds.
+    async fn read(
+        &mut self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+        mut polled: Polled,
+    ) -> PartitionData {
+        let budget = want.max_bytes.min(self.bytes_left);
+        // Unless a record is owed, skip a poll that likely brings back nothing that fits.
+        let average = usize::try_from(probe.average_size).unwrap_or(usize::MAX);
+        if self.owes_first_record || budget >= average.max(1) {
+            while let Some(count) = next_page(&polled, budget, probe.average_size) {
+                let asked = Instant::now();
+                let Some(page) = self.poll(want.topic, index, polled.next, count).await else {
+                    break;
+                };
+                match page {
+                    // The probe showed records, yet the first poll found none.
+                    Ok(page) if page.messages.is_empty() && polled.messages.is_empty() => {
+                        return self
+                            .after_empty_poll(want, index, offset, probe, asked)
+                            .await;
+                    }
+                    Ok(page) => polled.add(page, count),
+                    Err(error) if polled.messages.is_empty() => {
+                        return self.refuse(want, index, offset, &error);
+                    }
+                    // Serve what the earlier polls brought.
+                    Err(_) => break,
+                }
+            }
+        }
+
+        let keep_one = self.owes_first_record;
+        let encoded = off_worker(polled.bytes >= CODEC_OFF_WORKER_BYTES, || {
+            encode_records(&polled.messages, offset, budget, keep_one)
+        });
+        match encoded {
+            Ok(batch) => {
+                self.bytes_left = self.bytes_left.saturating_sub(batch.len());
+                self.owes_first_record &= batch.is_empty();
+                served(want.partition, polled.high_watermark, batch)
+            }
+            Err(error) => {
+                let stuck = &self.fetch.state.stuck_offsets;
+                let now = Instant::now();
+                let first = hold(stuck, want.topic, index, offset, now, self.fetch.max_wait);

Review Comment:
   Lines 754,858, 1088 — process-wide stuck-offset tracking: one client's error poisons the read for every other client, and two consumers at different offsets stomp each other's throttle entry.
   



##########
gateways/kafka/src/protocol/handlers/fetch.rs:
##########
@@ -97,6 +179,1167 @@ pub fn encode_response(version: i16, req: &FetchRequest) -> Result<Bytes> {
     encode_inner(version, topics, ERROR_NONE)
 }
 
+fn decode(state: &GatewayState, version: i16, body: Bytes) -> Result<FetchRequest> {
+    decode_guarded::<FetchRequest>(version, body, |v, b| {
+        validate_fetch_shape(v, b, state.max_frame_size)
+    })
+}
+
+/// Whether `request` names every partition it wants. Anything else continues a session, and
+/// this gateway opens none: it always answers `session_id` 0.
+const fn is_full(version: i16, request: &FetchRequest) -> bool {
+    version < SESSION_MIN_VERSION || matches!(request.session_epoch, INITIAL_EPOCH | FINAL_EPOCH)
+}
+
+/// Reads every requested partition once. When that finds nothing, waits for records up to
+/// `max_wait_ms` and reads again.
+///
+/// Returns the read slot too, if the read took one. Keep it until the response is encoded.
+async fn fetch(
+    bridge: &Arc<IggyBridge>,
+    state: &GatewayState,
+    request: &FetchRequest,
+) -> (Vec<FetchableTopicResponse>, Option<FetchSlot>) {
+    let started = Instant::now();
+    let give_up_at = started + REQUEST_DEADLINE;
+    let fetch = Fetch::new(bridge, state, request, give_up_at);
+    // A shared probe will do: an offset past it goes to a poll, not straight to a 1.
+    let mut probes = fetch.probe_all(recent(started)).await;
+    let (mut answers, mut slot) = fetch.read(&probes).await;
+    if waits(request, &answers) {
+        // No slot while it waits.
+        drop(slot);
+        let held: Vec<bool> = answers
+            .iter()
+            .map(|answer| retried_at_once(answer.error_code))
+            .collect();
+        let wait_until = started + fetch.max_wait;
+        probes = fetch
+            .wait(probes, &held, request.min_bytes, wait_until)
+            .await;
+        // Kafka reads again when the wait ends, too.
+        (answers, slot) = fetch.read(&probes).await;
+    }
+    (group(request, &fetch.wanted, answers), slot)
+}
+
+/// Kafka answers at once when a partition fails, when the request allows no wait, or when the
+/// records read reach `min_bytes`. Otherwise it waits.
+///
+/// A 6 or a -1 waits too. See [`retried_at_once`].
+fn waits(request: &FetchRequest, answers: &[PartitionData]) -> bool {
+    let min_bytes = usize::try_from(request.min_bytes).unwrap_or(0);
+    let record_bytes: usize = answers
+        .iter()
+        .map(|answer| answer.records.as_ref().map_or(0, Bytes::len))
+        .sum();
+    request.max_wait_ms > 0
+        && !answers.is_empty()
+        && record_bytes < min_bytes
+        && answers
+            .iter()
+            .all(|answer| answer.error_code == ERROR_NONE || retried_at_once(answer.error_code))
+}
+
+/// Codes the Java consumer fetches again at once after. Sent at once, they make it spin, so they
+/// wait out the request instead.
+const fn retried_at_once(code: i16) -> bool {
+    matches!(
+        code,
+        ERROR_NOT_LEADER_OR_FOLLOWER | ERROR_UNKNOWN_SERVER_ERROR
+    )
+}
+
+fn wait_time(max_wait_ms: i32) -> Duration {
+    Duration::from_millis(u64::try_from(max_wait_ms).unwrap_or(0)).min(MAX_WAIT)
+}
+
+/// When a -1 hold that starts at `now` ends: after the request's wait, but at least
+/// [`PROBE_INTERVAL`] on. A consumer with a short wait then reads a stuck partition at most ten
+/// times a second.
+fn hold_until(now: Instant, max_wait: Duration) -> Instant {
+    now + max_wait.max(PROBE_INTERVAL)
+}
+
+/// The topics to load a new probe for: each one whose newest probe started before `since`, the
+/// oldest first, at most [`MAX_ROUND_TOPICS`].
+fn stale_topics(snapshots: &[Option<Arc<Snapshot>>], since: Instant) -> Vec<usize> {
+    let started = |topic: usize| snapshots[topic].as_ref().map(|snapshot| snapshot.started);
+    let mut stale: Vec<usize> = (0..snapshots.len())
+        .filter(|&topic| started(topic).is_none_or(|started| started < since))
+        .collect();
+    // No probe sorts first, then the oldest, so each topic gets its turn.
+    stale.sort_by_key(|&topic| started(topic));
+    stale.truncate(MAX_ROUND_TOPICS);
+    stale
+}
+
+/// The topics wait round `turn` probes: the next [`MAX_ROUND_TOPICS`] of `count`, in turn.
+fn round(turn: usize, count: usize) -> impl Iterator<Item = usize> {
+    let start = turn.saturating_mul(MAX_ROUND_TOPICS) % count.max(1);
+    (start..start + MAX_ROUND_TOPICS.min(count)).map(move |topic| topic % count)
+}
+
+/// Waits for the next gateway write to any of the topics behind `writes`, then returns the topics
+/// written, at most [`MAX_ROUND_TOPICS`], each with the time of its write, and marks them seen.
+/// Pends while no write can come.
+async fn next_writes(writes: &mut [watch::Receiver<Option<Instant>>]) -> Vec<(usize, Instant)> {
+    let first = {
+        let mut changes: Vec<_> = writes
+            .iter_mut()
+            .map(|write| Some(Box::pin(write.changed())))
+            .collect();
+        poll_fn(|context| {
+            for (topic, slot) in changes.iter_mut().enumerate() {
+                let Some(change) = slot else { continue };
+                match change.as_mut().poll(context) {
+                    // `changed` marks this write seen.
+                    Poll::Ready(Ok(())) => return Poll::Ready(topic),
+                    // The topic left the board, so no write wakes this one.
+                    Poll::Ready(Err(_)) => *slot = None,
+                    Poll::Pending => {}
+                }
+            }
+            Poll::Pending
+        })
+        .await
+    };
+    let mut written = vec![(first, written_at(&mut writes[first]))];
+    written.extend(
+        writes
+            .iter_mut()
+            .enumerate()
+            .filter(|(topic, write)| *topic != first && write.has_changed().unwrap_or(false))
+            .take(MAX_ROUND_TOPICS - 1)
+            .map(|(topic, write)| (topic, written_at(write))),
+    );
+    written
+}
+
+/// When the newest write that `write` shows ended. Marks it seen.
+fn written_at(write: &mut watch::Receiver<Option<Instant>>) -> Instant {
+    let seen = *write.borrow_and_update();
+    seen.unwrap_or_else(Instant::now)
+}
+
+/// One request: what it asks for, and what bounds it.
+struct Fetch<'a> {
+    bridge: &'a Arc<IggyBridge>,
+    state: &'a GatewayState,
+    wanted: Vec<Wanted<'a>>,
+    /// Each topic to probe once, in request order.
+    topics: Vec<&'a str>,
+    response_bytes: usize,
+    give_up_at: Instant,
+    /// The request's wait, at most [`MAX_WAIT`].
+    max_wait: Duration,
+}
+
+impl<'a> Fetch<'a> {
+    fn new(
+        bridge: &'a Arc<IggyBridge>,
+        state: &'a GatewayState,
+        request: &'a FetchRequest,
+        give_up_at: Instant,
+    ) -> Self {
+        let (wanted, topics) = wanted(request);
+        Self {
+            bridge,
+            state,
+            wanted,
+            topics,
+            response_bytes: response_bytes(request.max_bytes, state.max_frame_size),
+            give_up_at,
+            max_wait: wait_time(request.max_wait_ms),
+        }
+    }
+
+    /// Each topic's probe, started at `since` or later.
+    ///
+    /// Loads at most [`MAX_ROUND_TOPICS`] new probes, the oldest first. Other topics keep an older
+    /// probe, or answer 6 without one. So does a topic not probed before `give_up_at`.
+    async fn probe_all(&self, since: Instant) -> Probes {
+        let board = &self.state.probe_board;
+        let mut snapshots: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.newest(topic))
+            .collect();
+        for topic in stale_topics(&snapshots, since) {
+            snapshots[topic] = self
+                .probe_topic(self.topics[topic], since, self.give_up_at)
+                .await;
+        }
+        snapshots
+            .into_iter()
+            .map(|snapshot| {
+                snapshot.map_or(Err(ERROR_NOT_LEADER_OR_FOLLOWER), |snapshot| {
+                    snapshot.probe.clone()
+                })
+            })
+            .collect()
+    }
+
+    /// `topic`'s probe from the board, started at `since` or later. `None` if none comes by
+    /// `deadline`.
+    async fn probe_topic(
+        &self,
+        topic: &str,
+        since: Instant,
+        deadline: Instant,
+    ) -> Option<Arc<Snapshot>> {
+        let load = || {
+            let (bridge, name) = (Arc::clone(self.bridge), topic.to_owned());
+            async move {
+                let probe = bridge.probe(&name).await;
+                probe.map(Arc::new).map_err(|error| refusal(&name, &error))
+            }
+        };
+        self.state
+            .probe_board
+            .probe(topic, since, deadline, load)
+            .await
+    }
+
+    /// The probe of partition `index` of `topic`, started at `since` or later.
+    async fn probe_partition(
+        &self,
+        topic: &str,
+        index: u32,
+        since: Instant,
+    ) -> Option<PartitionProbe> {
+        let snapshot = self.probe_topic(topic, since, self.give_up_at).await?;
+        snapshot.probe.as_ref().ok()?.get(index)
+    }
+
+    /// Probes until the bytes waiting reach `min_bytes`, a partition fails, or `wait_until`
+    /// passes. Holds no slot while it waits.
+    ///
+    /// Each [`PROBE_INTERVAL`], a round probes the next [`MAX_ROUND_TOPICS`] topics. A gateway
+    /// write to a topic probes it at once. A topic not probed keeps its last probe.
+    ///
+    /// `held` marks partitions that answered 6 or -1. They wait it out and end no wait.
+    async fn wait(
+        &self,
+        mut probes: Probes,
+        held: &[bool],
+        min_bytes: i32,
+        wait_until: Instant,
+    ) -> Probes {
+        if held.iter().all(|&held| held) {
+            sleep_until(wait_until).await;
+            return self.probe_all(recent(Instant::now())).await;
+        }
+        let min_bytes = u64::try_from(min_bytes).unwrap_or(0);
+        let board = &self.state.probe_board;
+        let mut writes: Vec<_> = self

Review Comment:
   Check this with  README.md:276's  "wakes a waiting Fetch at once" — subscribe-after-first-read misses the wake window. Fix the Contradiction. 
   



-- 
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: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(gateways): answer Kafka Fetch with records from Iggy [iggy]

Posted by "krishvishal (via GitHub)" <gi...@apache.org>.
krishvishal merged PR #4336:
URL: https://github.com/apache/iggy/pull/4336


-- 
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: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(gateways): answer Kafka Fetch with records from Iggy [iggy]

Posted by "ryerraguntla (via GitHub)" <gi...@apache.org>.
ryerraguntla commented on code in PR #4336:
URL: https://github.com/apache/iggy/pull/4336#discussion_r4143802761


##########
gateways/kafka/src/bridge/iggy_bridge/offsets.rs:
##########
@@ -169,3 +88,19 @@ impl IggyBridge {
         watermark
     }
 }
+
+/// One past the last committed offset of `partition`, or 0 when it is empty.
+///
+/// Fetch and `ListOffsets` both use this, so a consumer that seeks to LATEST fetches in range.
+///
+/// - Empty needs both counters: retention lowers `messages_count`, never `current_offset`.
+/// - Known gap: `(0, 0)` also comes back when the only message, at 0, expired, or when the server
+///   has no stats for the partition yet.
+/// - Not the offset of the next write: the server can reserve offsets past it.
+pub(super) const fn high_watermark(partition: &Partition) -> u64 {

Review Comment:
   ListOffsets LATEST answers 0 for the (0,0) shape Fetch treats as maybe-loading. That is the landing point of the replay above. 



##########
gateways/kafka/src/bridge/iggy_bridge/fetch.rs:
##########
@@ -17,5 +17,370 @@
 
 //! Fetch-side bridge calls.
 //!
-//! Empty until the Fetch handler lands. Separate from `produce.rs` so the two never edit one
-//! file.
+//! Separate from `produce.rs` so the two never edit one file.
+
+use std::sync::{Arc, Mutex, PoisonError};
+
+use iggy::prelude::{
+    Client, Consumer, IggyClient, IggyError, MessageClient, Partition, PolledMessages,
+    PollingStrategy, TopicClient,
+};
+use tokio::sync::{OnceCell, OwnedSemaphorePermit, Semaphore};
+use tokio::time::{Instant, timeout_at};
+
+use super::offsets::high_watermark;
+use super::{IggyBridge, TopicTarget, connect_client, in_slot, with_request_timeout};
+use crate::bridge::config::IggyBridgeConfig;
+use crate::bridge::error::BridgeError;
+
+/// Fetch reads that poll at once. Each has its own Iggy client, so a poll that Iggy holds up
+/// stalls only its own slot.
+const FETCH_SLOTS: usize = 4;
+
+/// The Fetch read slots, with a client for each.
+pub(super) struct FetchPool {
+    permits: Arc<Semaphore>,
+    /// The clients of the free slots.
+    idle: Mutex<Vec<FetchClient>>,
+    /// Every slot's client, for `close`.
+    all: Vec<FetchClient>,
+}
+
+impl FetchPool {
+    pub(super) fn new() -> Self {
+        let all: Vec<FetchClient> = (0..FETCH_SLOTS).map(|_| FetchClient::default()).collect();
+        Self {
+            permits: Arc::new(Semaphore::new(FETCH_SLOTS)),
+            idle: Mutex::new(all.clone()),
+            all,
+        }
+    }
+
+    /// A free slot. `None` if none frees by `deadline`.
+    async fn take(self: &Arc<Self>, deadline: Instant) -> Option<FetchSlot> {
+        let permit = timeout_at(deadline, Arc::clone(&self.permits).acquire_owned())
+            .await
+            .ok()?
+            .ok()?;
+        let client = self
+            .idle
+            .lock()
+            .unwrap_or_else(PoisonError::into_inner)
+            .pop()?;
+        Some(FetchSlot {
+            client,
+            pool: Arc::clone(self),
+            _permit: permit,
+        })
+    }
+
+    /// Shuts down each client that connected, and returns the first error. A client that fails to
+    /// shut down stops none of the others.
+    pub(super) async fn close(&self) -> Result<(), BridgeError> {
+        let mut closed = Ok(());
+        for client in self.all.iter().filter_map(|client| client.0.get()) {
+            let shutdown = with_request_timeout(client.shutdown()).await;
+            closed = closed.and(shutdown);
+        }
+        closed
+    }
+}
+
+/// The Iggy client of one read slot. It connects at the slot's first poll, so a bridge that never
+/// fetches opens no extra connection.
+#[derive(Clone, Default)]
+struct FetchClient(Arc<OnceCell<IggyClient>>);
+
+impl FetchClient {
+    async fn connected(&self, config: &IggyBridgeConfig) -> Result<&IggyClient, BridgeError> {
+        self.0.get_or_try_init(|| connect_client(config)).await
+    }
+}
+
+/// One Fetch read slot. Dropping it frees the slot.
+pub struct FetchSlot {
+    client: FetchClient,
+    pool: Arc<FetchPool>,
+    _permit: OwnedSemaphorePermit,
+}
+
+impl Drop for FetchSlot {
+    fn drop(&mut self) {
+        // Before the permit goes, so the next holder finds a client.
+        self.pool
+            .idle
+            .lock()
+            .unwrap_or_else(PoisonError::into_inner)
+            .push(self.client.clone());
+    }
+}
+
+/// One partition as a Fetch sees it before it reads.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct PartitionProbe {
+    /// Same value `high_watermarks` reports.
+    pub high_watermark: u64,
+    /// Stored bytes per retained message. 0 when the partition retains none.
+    pub average_size: u64,
+    /// 0 when retention removed every message, or when the server has no stats for the partition.
+    pub messages_count: u64,
+}
+
+impl PartitionProbe {
+    /// Iggy counts the messages of a partition it loads before it restores the offset, so the high
+    /// watermark reads too low until the load ends.
+    ///
+    /// A commit between Iggy's reads of the offset and the count looks the same for one probe.
+    /// [`IggyBridge::probe`] reads twice to tell them apart.
+    #[must_use]
+    pub const fn is_loading(&self) -> bool {
+        self.messages_count > self.high_watermark
+    }
+}
+
+impl From<&Partition> for PartitionProbe {
+    fn from(partition: &Partition) -> Self {
+        Self {
+            high_watermark: high_watermark(partition),
+            average_size: partition
+                .size
+                .as_bytes_u64()
+                .checked_div(partition.messages_count)
+                .unwrap_or(0),
+            messages_count: partition.messages_count,
+        }
+    }
+}
+
+/// Every partition of one topic, by id.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct TopicProbe {
+    partitions: Vec<(u32, PartitionProbe)>,
+}
+
+impl TopicProbe {
+    /// The probe of partition `id`, if the topic has it.
+    #[must_use]
+    pub fn get(&self, id: u32) -> Option<PartitionProbe> {
+        self.partitions
+            .binary_search_by_key(&id, |&(found, _)| found)
+            .ok()
+            .map(|found| self.partitions[found].1)
+    }
+
+    #[must_use]
+    pub fn partitions_count(&self) -> u32 {
+        u32::try_from(self.partitions.len()).unwrap_or(u32::MAX)
+    }
+}
+
+impl FromIterator<(u32, PartitionProbe)> for TopicProbe {
+    fn from_iter<I: IntoIterator<Item = (u32, PartitionProbe)>>(partitions: I) -> Self {
+        let mut partitions: Vec<_> = partitions.into_iter().collect();
+        partitions.sort_unstable_by_key(|&(id, _)| id);
+        Self { partitions }
+    }
+}
+
+impl IggyBridge {
+    /// A Fetch read slot, with its own client. `None` if none frees by `deadline`.
+    pub(crate) async fn fetch_slot(&self, deadline: Instant) -> Option<FetchSlot> {
+        self.fetch_pool.take(deadline).await
+    }
+
+    /// Probes every partition of the topic `kafka_topic` maps to, with one `get_topic` call, or
+    /// two when a partition reads as loading.
+    ///
+    /// # Errors
+    ///
+    /// [`BridgeError::InvalidKafkaTopicName`] if the name fails Kafka's rules.
+    /// [`BridgeError::Iggy`] if the stream or topic is missing, or the call fails.
+    /// [`BridgeError::Timeout`] past `REQUEST_TIMEOUT`.
+    pub(crate) async fn probe(&self, kafka_topic: &str) -> Result<TopicProbe, BridgeError> {
+        let target = self.topic_target(kafka_topic)?;
+        let probe = self.probe_target(&target).await?;
+        // A load lasts. A commit that raced the read does not.
+        if probe
+            .partitions
+            .iter()
+            .any(|(_, partition)| partition.is_loading())
+        {
+            return self.probe_target(&target).await;
+        }
+        Ok(probe)
+    }
+
+    async fn probe_target(&self, target: &TopicTarget) -> Result<TopicProbe, BridgeError> {
+        let details =
+            with_request_timeout(self.client.get_topic(&target.stream_id, &target.topic_id))

Review Comment:
   probes share the lockstep client with Produce, Metadata, and ListOffsets. Wait rounds cost about 10 get_topic/s per waited topic. Fix: probe on a dedicated client, and cap the probe wait well short of give_up_at.  Checkt at mod.rs.106 as well.



##########
gateways/kafka/src/protocol/handlers/fetch.rs:
##########
@@ -97,6 +187,1222 @@ pub fn encode_response(version: i16, req: &FetchRequest) -> Result<Bytes> {
     encode_inner(version, topics, ERROR_NONE)
 }
 
+fn decode(state: &GatewayState, version: i16, body: Bytes) -> Result<FetchRequest> {
+    decode_guarded::<FetchRequest>(version, body, |v, b| {
+        validate_fetch_shape(v, b, state.max_frame_size)
+    })
+}
+
+/// Whether `request` names every partition it wants. Anything else continues a session, and
+/// this gateway opens none: it always answers `session_id` 0.
+const fn is_full(version: i16, request: &FetchRequest) -> bool {
+    version < SESSION_MIN_VERSION || matches!(request.session_epoch, INITIAL_EPOCH | FINAL_EPOCH)
+}
+
+/// Reads every requested partition once. When that finds nothing, waits for records up to
+/// `max_wait_ms` and reads again.
+///
+/// Returns the read slot too, if the read took one. Keep it until the response is encoded.
+async fn fetch(
+    bridge: &Arc<IggyBridge>,
+    state: &GatewayState,
+    stuck_offsets: &Mutex<StuckOffsets>,
+    request: &FetchRequest,
+) -> (Vec<FetchableTopicResponse>, Option<FetchSlot>) {
+    let started = Instant::now();
+    let give_up_at = started + REQUEST_DEADLINE;
+    let fetch = Fetch::new(bridge, state, stuck_offsets, request, give_up_at);
+    // A shared probe will do: an offset past it goes to a poll, not straight to a 1.
+    let since = recent(started);
+    let mut probes = fetch.probe_all(since).await;
+    let (mut answers, mut slot) = fetch.read(&probes).await;
+    if waits(request, &answers) {
+        // No slot while it waits.
+        drop(slot);
+        let held: Vec<bool> = answers
+            .iter()
+            .map(|answer| retried_at_once(answer.error_code))
+            .collect();
+        let wait_until = started + fetch.max_wait;
+        probes = fetch
+            .wait(probes, &held, request.min_bytes, since, wait_until)
+            .await;
+        // Kafka reads again when the wait ends, too.
+        (answers, slot) = fetch.read(&probes).await;
+    }
+    (group(request, &fetch.wanted, answers), slot)
+}
+
+/// Kafka answers at once when a partition fails, when the request allows no wait, or when the
+/// records read reach `min_bytes`. Otherwise it waits.
+///
+/// A 6 or a -1 waits too. See [`retried_at_once`].
+fn waits(request: &FetchRequest, answers: &[PartitionData]) -> bool {
+    let min_bytes = usize::try_from(request.min_bytes).unwrap_or(0);
+    let record_bytes: usize = answers
+        .iter()
+        .map(|answer| answer.records.as_ref().map_or(0, Bytes::len))
+        .sum();
+    request.max_wait_ms > 0
+        && !answers.is_empty()
+        && record_bytes < min_bytes
+        && answers
+            .iter()
+            .all(|answer| answer.error_code == ERROR_NONE || retried_at_once(answer.error_code))
+}
+
+/// Codes the Java consumer fetches again at once after. Sent at once, they make it spin, so they
+/// wait out the request instead.
+const fn retried_at_once(code: i16) -> bool {
+    matches!(
+        code,
+        ERROR_NOT_LEADER_OR_FOLLOWER | ERROR_UNKNOWN_SERVER_ERROR
+    )
+}
+
+fn wait_time(max_wait_ms: i32) -> Duration {
+    Duration::from_millis(u64::try_from(max_wait_ms).unwrap_or(0)).min(MAX_WAIT)
+}
+
+/// When a -1 hold that starts at `now` ends: after the request's wait, but at least
+/// [`PROBE_INTERVAL`] on. A consumer with a short wait then reads a stuck partition at most ten
+/// times a second.
+fn hold_until(now: Instant, max_wait: Duration) -> Instant {
+    now + max_wait.max(PROBE_INTERVAL)
+}
+
+/// The topics to load a new probe for: each one whose newest probe started before `since`, the
+/// oldest first, at most [`MAX_ROUND_TOPICS`].
+fn stale_topics(snapshots: &[Option<Arc<Snapshot>>], since: Instant) -> Vec<usize> {
+    let started = |topic: usize| snapshots[topic].as_ref().map(|snapshot| snapshot.started);
+    let mut stale: Vec<usize> = (0..snapshots.len())
+        .filter(|&topic| started(topic).is_none_or(|started| started < since))
+        .collect();
+    // No probe sorts first, then the oldest, so each topic gets its turn.
+    stale.sort_by_key(|&topic| started(topic));
+    stale.truncate(MAX_ROUND_TOPICS);
+    stale
+}
+
+/// The topics wait round `turn` probes: the next [`MAX_ROUND_TOPICS`] of `count`, in turn.
+fn round(turn: usize, count: usize) -> impl Iterator<Item = usize> {
+    let start = turn.saturating_mul(MAX_ROUND_TOPICS) % count.max(1);
+    (start..start + MAX_ROUND_TOPICS.min(count)).map(move |topic| topic % count)
+}
+
+/// Waits for the next gateway write to any of the topics behind `writes`, then returns the topics
+/// written, at most [`MAX_ROUND_TOPICS`], each with the time of its write, and marks them seen.
+/// Pends while no write can come.
+async fn next_writes(writes: &mut [watch::Receiver<Option<Instant>>]) -> Vec<(usize, Instant)> {
+    let first = {
+        let mut changes: Vec<_> = writes
+            .iter_mut()
+            .map(|write| Some(Box::pin(write.changed())))
+            .collect();
+        poll_fn(|context| {
+            for (topic, slot) in changes.iter_mut().enumerate() {
+                let Some(change) = slot else { continue };
+                match change.as_mut().poll(context) {
+                    // `changed` marks this write seen.
+                    Poll::Ready(Ok(())) => return Poll::Ready(topic),
+                    // Only a dropped board ends the channel. The board keeps a watched topic.
+                    Poll::Ready(Err(_)) => *slot = None,
+                    Poll::Pending => {}
+                }
+            }
+            Poll::Pending
+        })
+        .await
+    };
+    let mut written = vec![(first, written_at(&mut writes[first]))];
+    written.extend(
+        writes
+            .iter_mut()
+            .enumerate()
+            .filter(|(topic, write)| *topic != first && write.has_changed().unwrap_or(false))
+            .take(MAX_ROUND_TOPICS - 1)
+            .map(|(topic, write)| (topic, written_at(write))),
+    );
+    written
+}
+
+/// When the newest write that `write` shows ended. Marks it seen.
+fn written_at(write: &mut watch::Receiver<Option<Instant>>) -> Instant {
+    let seen = *write.borrow_and_update();
+    seen.unwrap_or_else(Instant::now)
+}
+
+/// The topics behind `writes` whose last gateway write ended at `since` or later, each with the
+/// time of that write, at most [`MAX_ROUND_TOPICS`].
+fn writes_since(
+    writes: &[watch::Receiver<Option<Instant>>],
+    since: Instant,
+) -> Vec<(usize, Instant)> {
+    writes
+        .iter()
+        .enumerate()
+        .filter_map(|(topic, write)| {
+            let written = (*write.borrow())?;
+            (written >= since).then_some((topic, written))
+        })
+        .take(MAX_ROUND_TOPICS)
+        .collect()
+}
+
+/// One request: what it asks for, and what bounds it.
+struct Fetch<'a> {
+    bridge: &'a Arc<IggyBridge>,
+    state: &'a GatewayState,
+    /// The connection's, not the gateway's. See [`ConnectionState`].
+    stuck_offsets: &'a Mutex<StuckOffsets>,
+    wanted: Vec<Wanted<'a>>,
+    /// Each topic to probe once, in request order.
+    topics: Vec<&'a str>,
+    response_bytes: usize,
+    give_up_at: Instant,
+    /// The request's wait, at most [`MAX_WAIT`].
+    max_wait: Duration,
+}
+
+impl<'a> Fetch<'a> {
+    fn new(
+        bridge: &'a Arc<IggyBridge>,
+        state: &'a GatewayState,
+        stuck_offsets: &'a Mutex<StuckOffsets>,
+        request: &'a FetchRequest,
+        give_up_at: Instant,
+    ) -> Self {
+        let (wanted, topics) = wanted(request);
+        Self {
+            bridge,
+            state,
+            stuck_offsets,
+            wanted,
+            topics,
+            response_bytes: response_bytes(request.max_bytes, state.max_frame_size),
+            give_up_at,
+            max_wait: wait_time(request.max_wait_ms),
+        }
+    }
+
+    /// Each topic's probe, started at `since` or later.
+    ///
+    /// Loads at most [`MAX_ROUND_TOPICS`] new probes, the oldest first. Other topics keep an older
+    /// probe, or answer 6 without one. So does a topic not probed before `give_up_at`.
+    async fn probe_all(&self, since: Instant) -> Probes {
+        let board = &self.state.probe_board;
+        let mut snapshots: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.newest(topic))
+            .collect();
+        for topic in stale_topics(&snapshots, since) {
+            let probe = self.probe_topic(self.topics[topic], since, self.give_up_at);
+            if let Some(snapshot) = probe.await {
+                snapshots[topic] = Some(snapshot);
+            }
+        }
+        snapshots
+            .into_iter()
+            .map(|snapshot| {
+                snapshot.map_or(Err(ERROR_NOT_LEADER_OR_FOLLOWER), |snapshot| {
+                    readable(&snapshot)
+                })
+            })
+            .collect()
+    }
+
+    /// `topic`'s probe from the board, started at `since` or later. `None` if none comes by
+    /// `deadline`.
+    async fn probe_topic(
+        &self,
+        topic: &str,
+        since: Instant,
+        deadline: Instant,
+    ) -> Option<Arc<Snapshot>> {
+        let load = || {
+            let (bridge, name) = (Arc::clone(self.bridge), topic.to_owned());
+            async move {
+                let probe = bridge.probe(&name).await;
+                probe.map(Arc::new).map_err(|error| refusal(&name, &error))
+            }
+        };
+        self.state
+            .probe_board
+            .probe(topic, since, deadline, load)
+            .await
+    }
+
+    /// The probe of partition `index` of `topic`, started at `since` or later.
+    ///
+    /// Never the last good probe of a failed refresh: [`empty_poll`] proves nothing from a probe
+    /// taken before the poll, and a stale one would answer an in-range offset 1.
+    async fn probe_partition(
+        &self,
+        topic: &str,
+        index: u32,
+        since: Instant,
+    ) -> Option<PartitionProbe> {
+        let snapshot = self.probe_topic(topic, since, self.give_up_at).await?;
+        snapshot.probe.as_ref().ok()?.get(index)
+    }
+
+    /// Probes until the bytes waiting reach `min_bytes`, a partition fails, or `wait_until`
+    /// passes. Holds no slot while it waits.
+    ///
+    /// Each [`PROBE_INTERVAL`], a round probes the next [`MAX_ROUND_TOPICS`] topics. A gateway
+    /// write to a topic probes it at once. A topic not probed keeps its last probe.
+    ///
+    /// `held` marks partitions that answered 6 or -1. They wait it out and end no wait.
+    ///
+    /// `probed_since` is the oldest start of a fresh probe in hand. A write that ended after it may
+    /// not show in the probes, and subscribing marks it seen, so those topics probe at once. An
+    /// older probe, kept when a refresh failed, is stale by the first round.
+    async fn wait(
+        &self,
+        mut probes: Probes,
+        held: &[bool],
+        min_bytes: i32,
+        probed_since: Instant,
+        wait_until: Instant,
+    ) -> Probes {
+        if held.iter().all(|&held| held) {
+            sleep_until(wait_until).await;
+            return self.probe_all(recent(Instant::now())).await;
+        }
+        let min_bytes = u64::try_from(min_bytes).unwrap_or(0);
+        let board = &self.state.probe_board;
+        let mut writes: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.writes(topic))
+            .collect();
+        let mut missed = writes_since(&writes, probed_since);
+        let mut turn = 0;
+        // Kept across write wakes, so steady writes to one topic do not stop the rounds.
+        let mut round_at = (Instant::now() + PROBE_INTERVAL).min(wait_until);
+        while Instant::now() < wait_until {
+            let written = if missed.is_empty() {
+                tokio::select! {
+                    () = sleep_until(round_at) => None,
+                    written = next_writes(&mut writes) => Some(written),
+                }
+            } else {
+                Some(std::mem::take(&mut missed))
+            };
+            let timed = written.is_none();
+            // A write needs a probe that started after it. A round needs one newer than the last.
+            let due = written.unwrap_or_else(|| {
+                turn += 1;
+                let since = recent(Instant::now());
+                round(turn - 1, self.topics.len())
+                    .map(|topic| (topic, since))
+                    .collect()
+            });
+            for (topic, since) in due {
+                // A probe late for the round still lands on the board for the next Fetch.
+                let probe = self.probe_topic(self.topics[topic], since, wait_until);
+                if let Some(snapshot) = probe.await {
+                    probes[topic] = readable(&snapshot);
+                }
+            }
+            if timed {
+                round_at = (Instant::now() + PROBE_INTERVAL).min(wait_until);
+            }
+            if ready(&self.wanted, held, &probes, self.response_bytes, min_bytes) {
+                break;
+            }
+        }
+        probes
+    }
+
+    /// One answer per requested partition, in request order, and the read slot, if taken.
+    async fn read(&self, probes: &Probes) -> (Vec<PartitionData>, Option<FetchSlot>) {
+        Reader::new(self).read_all(probes).await
+    }
+}
+
+/// One requested partition.
+struct Wanted<'a> {
+    /// Its topic entry in the request.
+    entry: usize,
+    topic: &'a str,
+    partition: i32,
+    fetch_offset: i64,
+    max_bytes: usize,
+    /// Where its probe is, or the code it answers without asking Iggy.
+    probe_at: core::result::Result<ProbeAt, i16>,
+}
+
+/// Where a partition's probe is.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct ProbeAt {
+    /// Its topic's place in `Fetch::topics`.
+    topic: usize,
+    index: u32,
+}
+
+/// Each requested partition once, in request order, and each topic to probe once. A repeat
+/// keeps the first entry.
+///
+/// The Java consumer drops a whole response that leaves out a partition it asked for.
+fn wanted(request: &FetchRequest) -> (Vec<Wanted<'_>>, Vec<&str>) {
+    let total = request
+        .topics
+        .iter()
+        .map(|topic| topic.partitions.len())
+        .sum();
+    let mut seen = HashSet::with_capacity(total);
+    let mut wanted = Vec::with_capacity(total);
+    let mut topics = IndexSet::new();
+    for (entry, topic) in request.topics.iter().enumerate() {
+        let name = topic.topic.as_str();
+        // A name Kafka refuses answers 3 here, so it never takes a place on the probe board.
+        let named = validate_kafka_topic_name("kafka_topic", name)
+            .map_err(|_| ERROR_UNKNOWN_TOPIC_OR_PARTITION);
+        for partition in &topic.partitions {
+            if !seen.insert((name, partition.partition)) {
+                continue;
+            }
+            let probe_at = named
+                .and_then(|()| {
+                    u32::try_from(partition.partition).map_err(|_| ERROR_UNKNOWN_TOPIC_OR_PARTITION)
+                })
+                .map(|index| ProbeAt {
+                    topic: topics.insert_full(name).0,
+                    index,
+                });
+            wanted.push(Wanted {
+                entry,
+                topic: name,
+                partition: partition.partition,
+                fetch_offset: partition.fetch_offset,
+                max_bytes: usize::try_from(partition.partition_max_bytes).unwrap_or(0),
+                probe_at,
+            });
+        }
+    }
+    (wanted, topics.into_iter().collect())
+}
+
+/// Record bytes the whole response may carry: `max_bytes`, at most one frame.
+fn response_bytes(max_bytes: i32, max_frame_size: usize) -> usize {
+    usize::try_from(max_bytes).unwrap_or(0).min(max_frame_size)
+}
+
+/// Per topic in `Fetch::topics`, its probe, or one code for the whole topic.
+type Probes = Vec<TopicProbed>;
+
+/// The probe to read with. A refresh that failed with a code the consumer retries at once gives
+/// way to the last good probe, so a blip in `get_topic` leaves the polls to decide rather than
+/// answering 6 or -1 for partitions that hold records.
+fn readable(snapshot: &Snapshot) -> TopicProbed {
+    match (&snapshot.probe, &snapshot.last_good) {
+        (Err(code), Some(good)) if retried_at_once(*code) => Ok(Arc::clone(good)),
+        (probe, _) => probe.clone(),
+    }
+}
+
+/// Whether a partition now fails, as an error ends Kafka's wait too, or the bytes waiting reach
+/// `min_bytes`. Skips `held` partitions.
+fn ready(
+    wanted: &[Wanted<'_>],
+    held: &[bool],
+    probes: &Probes,
+    response_bytes: usize,
+    min_bytes: u64,
+) -> bool {
+    let mut waiting = 0u64;
+    for (want, _) in wanted.iter().zip(held).filter(|&(_, &held)| !held) {
+        match position(want, probes) {
+            Position::Refused(_) => return true,
+            // Past the end of this probe, or no message kept. A newer probe, or the read after
+            // the wait, decides.
+            Position::CaughtUp(_) | Position::Unsure { .. } => {}
+            Position::Behind { offset, probe, .. } => {
+                let budget = want.max_bytes.min(response_bytes);
+                waiting = waiting.saturating_add(bytes_waiting(offset, probe, budget));
+            }
+        }
+    }
+    waiting >= min_bytes
+}
+
+/// Estimated bytes past `offset`, at most `budget`. Kafka's delayed fetch counts the same way.
+fn bytes_waiting(offset: u64, probe: PartitionProbe, budget: usize) -> u64 {
+    probe
+        .high_watermark
+        .saturating_sub(offset)
+        .saturating_mul(probe.average_size)
+        .min(u64::try_from(budget).unwrap_or(u64::MAX))
+}
+
+/// Where a requested offset stands against the probe.
+#[derive(Debug, PartialEq, Eq)]
+enum Position {
+    /// Answer this code, with no records.
+    Refused(i16),
+    /// At the high watermark. Answer 0, with no records.
+    CaughtUp(PartitionProbe),
+    /// Records wait in partition `index` from `offset` on.
+    Behind {
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    },
+    /// The probe cannot place `offset`. One poll decides.
+    Unsure {
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    },
+}
+
+fn position(want: &Wanted<'_>, probes: &Probes) -> Position {
+    let at = match want.probe_at {
+        Ok(at) => at,
+        Err(code) => return Position::Refused(code),
+    };
+    // `Fetch::probe_all` probes every topic in `Fetch::topics`, in order.
+    let probe = match &probes[at.topic] {
+        Ok(topic) => match topic.get(at.index) {
+            Some(probe) => probe,
+            None => return Position::Refused(ERROR_UNKNOWN_TOPIC_OR_PARTITION),
+        },
+        Err(code) => return Position::Refused(*code),
+    };
+    if probe.is_loading() {

Review Comment:
   is_loading answers 6 with no bound, no spell, no log. ListOffsets does the same (offsets.rs:53). Persistent stats drift stalls a consumer with no trace. **Fix**: spell plus log_not_ready, warn after grace, then fall through to a poll. 



##########
gateways/kafka/src/bridge/iggy_bridge/fetch.rs:
##########
@@ -17,5 +17,370 @@
 
 //! Fetch-side bridge calls.
 //!
-//! Empty until the Fetch handler lands. Separate from `produce.rs` so the two never edit one
-//! file.
+//! Separate from `produce.rs` so the two never edit one file.
+
+use std::sync::{Arc, Mutex, PoisonError};
+
+use iggy::prelude::{
+    Client, Consumer, IggyClient, IggyError, MessageClient, Partition, PolledMessages,
+    PollingStrategy, TopicClient,
+};
+use tokio::sync::{OnceCell, OwnedSemaphorePermit, Semaphore};
+use tokio::time::{Instant, timeout_at};
+
+use super::offsets::high_watermark;
+use super::{IggyBridge, TopicTarget, connect_client, in_slot, with_request_timeout};
+use crate::bridge::config::IggyBridgeConfig;
+use crate::bridge::error::BridgeError;
+
+/// Fetch reads that poll at once. Each has its own Iggy client, so a poll that Iggy holds up
+/// stalls only its own slot.
+const FETCH_SLOTS: usize = 4;
+
+/// The Fetch read slots, with a client for each.
+pub(super) struct FetchPool {
+    permits: Arc<Semaphore>,
+    /// The clients of the free slots.
+    idle: Mutex<Vec<FetchClient>>,
+    /// Every slot's client, for `close`.
+    all: Vec<FetchClient>,
+}
+
+impl FetchPool {
+    pub(super) fn new() -> Self {
+        let all: Vec<FetchClient> = (0..FETCH_SLOTS).map(|_| FetchClient::default()).collect();
+        Self {
+            permits: Arc::new(Semaphore::new(FETCH_SLOTS)),
+            idle: Mutex::new(all.clone()),
+            all,
+        }
+    }
+
+    /// A free slot. `None` if none frees by `deadline`.
+    async fn take(self: &Arc<Self>, deadline: Instant) -> Option<FetchSlot> {
+        let permit = timeout_at(deadline, Arc::clone(&self.permits).acquire_owned())
+            .await
+            .ok()?
+            .ok()?;
+        let client = self
+            .idle
+            .lock()
+            .unwrap_or_else(PoisonError::into_inner)
+            .pop()?;
+        Some(FetchSlot {
+            client,
+            pool: Arc::clone(self),
+            _permit: permit,
+        })
+    }
+
+    /// Shuts down each client that connected, and returns the first error. A client that fails to
+    /// shut down stops none of the others.
+    pub(super) async fn close(&self) -> Result<(), BridgeError> {
+        let mut closed = Ok(());
+        for client in self.all.iter().filter_map(|client| client.0.get()) {
+            let shutdown = with_request_timeout(client.shutdown()).await;
+            closed = closed.and(shutdown);
+        }
+        closed
+    }
+}
+
+/// The Iggy client of one read slot. It connects at the slot's first poll, so a bridge that never
+/// fetches opens no extra connection.
+#[derive(Clone, Default)]
+struct FetchClient(Arc<OnceCell<IggyClient>>);
+
+impl FetchClient {
+    async fn connected(&self, config: &IggyBridgeConfig) -> Result<&IggyClient, BridgeError> {
+        self.0.get_or_try_init(|| connect_client(config)).await

Review Comment:
   he four slot clients and the shared client each connect with leader redirection and are not pinned to one node, while README.md:235 assumes they are. An empty poll on a lagging node can answer 1 at hwm>1 (handlers/fetch.rs:992-995). 



##########
gateways/kafka/src/bridge/iggy_bridge/fetch.rs:
##########
@@ -17,5 +17,370 @@
 
 //! Fetch-side bridge calls.
 //!
-//! Empty until the Fetch handler lands. Separate from `produce.rs` so the two never edit one
-//! file.
+//! Separate from `produce.rs` so the two never edit one file.
+
+use std::sync::{Arc, Mutex, PoisonError};
+
+use iggy::prelude::{
+    Client, Consumer, IggyClient, IggyError, MessageClient, Partition, PolledMessages,
+    PollingStrategy, TopicClient,
+};
+use tokio::sync::{OnceCell, OwnedSemaphorePermit, Semaphore};
+use tokio::time::{Instant, timeout_at};
+
+use super::offsets::high_watermark;
+use super::{IggyBridge, TopicTarget, connect_client, in_slot, with_request_timeout};
+use crate::bridge::config::IggyBridgeConfig;
+use crate::bridge::error::BridgeError;
+
+/// Fetch reads that poll at once. Each has its own Iggy client, so a poll that Iggy holds up
+/// stalls only its own slot.
+const FETCH_SLOTS: usize = 4;
+
+/// The Fetch read slots, with a client for each.
+pub(super) struct FetchPool {
+    permits: Arc<Semaphore>,
+    /// The clients of the free slots.
+    idle: Mutex<Vec<FetchClient>>,
+    /// Every slot's client, for `close`.
+    all: Vec<FetchClient>,
+}
+
+impl FetchPool {
+    pub(super) fn new() -> Self {
+        let all: Vec<FetchClient> = (0..FETCH_SLOTS).map(|_| FetchClient::default()).collect();
+        Self {
+            permits: Arc::new(Semaphore::new(FETCH_SLOTS)),
+            idle: Mutex::new(all.clone()),
+            all,
+        }
+    }
+
+    /// A free slot. `None` if none frees by `deadline`.
+    async fn take(self: &Arc<Self>, deadline: Instant) -> Option<FetchSlot> {
+        let permit = timeout_at(deadline, Arc::clone(&self.permits).acquire_owned())
+            .await
+            .ok()?
+            .ok()?;
+        let client = self
+            .idle
+            .lock()
+            .unwrap_or_else(PoisonError::into_inner)
+            .pop()?;
+        Some(FetchSlot {
+            client,
+            pool: Arc::clone(self),
+            _permit: permit,
+        })
+    }
+
+    /// Shuts down each client that connected, and returns the first error. A client that fails to
+    /// shut down stops none of the others.
+    pub(super) async fn close(&self) -> Result<(), BridgeError> {
+        let mut closed = Ok(());
+        for client in self.all.iter().filter_map(|client| client.0.get()) {
+            let shutdown = with_request_timeout(client.shutdown()).await;
+            closed = closed.and(shutdown);
+        }
+        closed
+    }
+}
+
+/// The Iggy client of one read slot. It connects at the slot's first poll, so a bridge that never
+/// fetches opens no extra connection.
+#[derive(Clone, Default)]
+struct FetchClient(Arc<OnceCell<IggyClient>>);
+
+impl FetchClient {
+    async fn connected(&self, config: &IggyBridgeConfig) -> Result<&IggyClient, BridgeError> {
+        self.0.get_or_try_init(|| connect_client(config)).await
+    }
+}
+
+/// One Fetch read slot. Dropping it frees the slot.
+pub struct FetchSlot {
+    client: FetchClient,
+    pool: Arc<FetchPool>,
+    _permit: OwnedSemaphorePermit,
+}
+
+impl Drop for FetchSlot {
+    fn drop(&mut self) {
+        // Before the permit goes, so the next holder finds a client.
+        self.pool
+            .idle
+            .lock()
+            .unwrap_or_else(PoisonError::into_inner)
+            .push(self.client.clone());
+    }
+}
+
+/// One partition as a Fetch sees it before it reads.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct PartitionProbe {
+    /// Same value `high_watermarks` reports.
+    pub high_watermark: u64,
+    /// Stored bytes per retained message. 0 when the partition retains none.
+    pub average_size: u64,
+    /// 0 when retention removed every message, or when the server has no stats for the partition.
+    pub messages_count: u64,
+}
+
+impl PartitionProbe {
+    /// Iggy counts the messages of a partition it loads before it restores the offset, so the high
+    /// watermark reads too low until the load ends.
+    ///
+    /// A commit between Iggy's reads of the offset and the count looks the same for one probe.
+    /// [`IggyBridge::probe`] reads twice to tell them apart.
+    #[must_use]
+    pub const fn is_loading(&self) -> bool {
+        self.messages_count > self.high_watermark
+    }
+}
+
+impl From<&Partition> for PartitionProbe {
+    fn from(partition: &Partition) -> Self {
+        Self {
+            high_watermark: high_watermark(partition),
+            average_size: partition
+                .size
+                .as_bytes_u64()
+                .checked_div(partition.messages_count)
+                .unwrap_or(0),
+            messages_count: partition.messages_count,
+        }
+    }
+}
+
+/// Every partition of one topic, by id.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct TopicProbe {
+    partitions: Vec<(u32, PartitionProbe)>,
+}
+
+impl TopicProbe {
+    /// The probe of partition `id`, if the topic has it.
+    #[must_use]
+    pub fn get(&self, id: u32) -> Option<PartitionProbe> {
+        self.partitions
+            .binary_search_by_key(&id, |&(found, _)| found)
+            .ok()
+            .map(|found| self.partitions[found].1)
+    }
+
+    #[must_use]
+    pub fn partitions_count(&self) -> u32 {
+        u32::try_from(self.partitions.len()).unwrap_or(u32::MAX)
+    }
+}
+
+impl FromIterator<(u32, PartitionProbe)> for TopicProbe {
+    fn from_iter<I: IntoIterator<Item = (u32, PartitionProbe)>>(partitions: I) -> Self {
+        let mut partitions: Vec<_> = partitions.into_iter().collect();
+        partitions.sort_unstable_by_key(|&(id, _)| id);
+        Self { partitions }
+    }
+}
+
+impl IggyBridge {
+    /// A Fetch read slot, with its own client. `None` if none frees by `deadline`.
+    pub(crate) async fn fetch_slot(&self, deadline: Instant) -> Option<FetchSlot> {
+        self.fetch_pool.take(deadline).await
+    }
+
+    /// Probes every partition of the topic `kafka_topic` maps to, with one `get_topic` call, or
+    /// two when a partition reads as loading.
+    ///
+    /// # Errors
+    ///
+    /// [`BridgeError::InvalidKafkaTopicName`] if the name fails Kafka's rules.
+    /// [`BridgeError::Iggy`] if the stream or topic is missing, or the call fails.
+    /// [`BridgeError::Timeout`] past `REQUEST_TIMEOUT`.
+    pub(crate) async fn probe(&self, kafka_topic: &str) -> Result<TopicProbe, BridgeError> {
+        let target = self.topic_target(kafka_topic)?;
+        let probe = self.probe_target(&target).await?;
+        // A load lasts. A commit that raced the read does not.
+        if probe
+            .partitions
+            .iter()
+            .any(|(_, partition)| partition.is_loading())
+        {
+            return self.probe_target(&target).await;
+        }
+        Ok(probe)
+    }
+
+    async fn probe_target(&self, target: &TopicTarget) -> Result<TopicProbe, BridgeError> {
+        let details =
+            with_request_timeout(self.client.get_topic(&target.stream_id, &target.topic_id))
+                .await?
+                // A missing stream reads as `None` too. Both answer the same Kafka code.
+                .ok_or_else(|| {
+                    BridgeError::Iggy(IggyError::TopicNameNotFound(
+                        target.topic_id.to_string(),
+                        target.stream_id.to_string(),
+                    ))
+                })?;
+        Ok(details
+            .partitions
+            .iter()
+            .map(|partition| (partition.id, PartitionProbe::from(partition)))
+            .collect())
+    }
+
+    /// Reads up to `count` messages of `partition`, from `offset` on, with the client of `slot`.
+    /// Hands the slot back with the result. `None` if no result comes by `deadline`.
+    ///
+    /// A plain consumer without auto commit, so Iggy stores no offset. Always an explicit
+    /// offset, never `Next` (see `docs/OFFSET_STORAGE.md`).
+    ///
+    /// The errors are those of [`Self::probe`]. A partition the topic lacks is
+    /// [`BridgeError::Iggy`] here. The poll stops at `deadline` too, so a result that comes then
+    /// is [`BridgeError::Timeout`].
+    pub(crate) async fn poll(
+        self: &Arc<Self>,
+        slot: FetchSlot,
+        kafka_topic: &str,
+        partition: u32,
+        offset: u64,
+        count: u32,
+        deadline: Instant,
+    ) -> Option<(Result<PolledMessages, BridgeError>, FetchSlot)> {
+        let (bridge, client, topic) = (
+            Arc::clone(self),
+            slot.client.clone(),
+            kafka_topic.to_owned(),
+        );
+        let poll = async move {
+            bridge
+                .poll_with(&client, &topic, partition, offset, count, deadline)
+                .await
+        };
+        in_slot(slot, deadline, poll).await
+    }
+
+    async fn poll_with(
+        &self,
+        client: &FetchClient,
+        kafka_topic: &str,
+        partition: u32,
+        offset: u64,
+        count: u32,
+        deadline: Instant,
+    ) -> Result<PolledMessages, BridgeError> {
+        let target = self.topic_target(kafka_topic)?;
+        let (consumer, strategy) = (Consumer::default(), PollingStrategy::offset(offset));
+        let poll = async {
+            client
+                .connected(&self.config)
+                .await?
+                .poll_messages(
+                    &target.stream_id,
+                    &target.topic_id,
+                    Some(partition),
+                    &consumer,
+                    &strategy,
+                    count,
+                    false,
+                )
+                .await
+                .map_err(BridgeError::Iggy)
+        };
+        // The SDK replays a poll that Iggy refuses for up to 30 s. Stop with the request, so the
+        // slot frees.
+        match timeout_at(deadline, poll).await {

Review Comment:
    inner timeout_at frees the slot while the detached SDK poll still holds the client stream lock, up to 30s (core/sdk/src/tcp/tcp_client.rs:1512-1513). Idle pool is LIFO (pop :69, push :114), so the next Fetch gets the wedged client and serves empty or 6. Docs claim the opposite (mod.rs:86-87, handlers/fetch.rs:707-708, README.md:270-271). **Fix**: drop the inner timeout_at so in_slot keeps the slot until the SDK returns, bounded like send_in_slot (produce.rs:96), or swap in a fresh FetchClient on timeout.



##########
gateways/kafka/tests/fetch_real_bridge_tests.rs:
##########
@@ -0,0 +1,727 @@
+// 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.
+
+//! Fetch (API key 1) driven through the whole handler against a real `iggy-server`.
+//!
+//! Records go in through the Iggy SDK, mapped by `to_iggy`, and come back as a response that
+//! `kafka_protocol`'s client-side decoder reads, the way a consumer would.
+
+use std::collections::BTreeMap;
+use std::sync::Arc;
+use std::time::Duration;
+
+use bytes::{Bytes, BytesMut};
+use iggy::prelude::{HeaderKey, HeaderValue, Identifier, IggyMessage, MessageClient, Partitioning};
+use kafka_protocol::indexmap::IndexMap;
+use kafka_protocol::messages::fetch_request::{FetchPartition, FetchTopic};
+use kafka_protocol::messages::fetch_response::PartitionData;
+use kafka_protocol::messages::produce_request::{PartitionProduceData, TopicProduceData};
+use kafka_protocol::messages::{
+    FetchRequest, FetchResponse, ProduceRequest, ProduceResponse, TopicName,
+};
+use kafka_protocol::protocol::{Decodable, Encodable, StrBytes};
+use kafka_protocol::records::{
+    Compression, NO_PARTITION_LEADER_EPOCH, NO_PRODUCER_EPOCH, NO_PRODUCER_ID, NO_SEQUENCE, Record,
+    RecordBatchDecoder, RecordBatchEncoder, RecordEncodeOptions, TimestampType,
+};
+use serial_test::serial;
+use tokio::time::Instant;
+use tokio_util::sync::CancellationToken;
+
+use iggy_gateway_kafka::bridge::IggyBridge;
+use iggy_gateway_kafka::group::{GroupCoordinator, GroupCoordinatorConfig};
+use iggy_gateway_kafka::protocol::api::{
+    API_KEY_FETCH, API_KEY_PRODUCE, BrokerAdvertise, GatewayState, handle_request_bounded,
+};
+use iggy_gateway_kafka::records::{MAPPING_VERSION, TimestampWindow, VERSION_HEADER, to_iggy};
+
+#[path = "common/iggy_server.rs"]
+mod iggy_server;
+
+use iggy_server::{TestServer, raw_client};
+
+/// The stream every unmapped Kafka topic resolves to, per `TopicMapping`'s default rule.
+const STREAM: &str = "kafka";
+const TOPIC: &str = "orders";
+const CREATE_TIME: i64 = 1_700_000_000_123;
+const MAX_FRAME_SIZE: usize = 8 * 1024 * 1024;
+/// The highest version a consumer without topic ids sends.
+const VERSION: i16 = 12;
+/// Java's `max.partition.fetch.bytes` default.
+const PARTITION_MAX_BYTES: i32 = 1024 * 1024;
+/// A Fetch that finds records or an error answers well inside this.
+const PROMPT: Duration = Duration::from_secs(5);
+
+/// Spelled out rather than imported: a test reading its expected code from the same constant the
+/// handler answers with cannot catch that constant changing.
+const ERROR_UNKNOWN_SERVER_ERROR: i16 = -1;
+const ERROR_NONE: i16 = 0;
+const ERROR_OFFSET_OUT_OF_RANGE: i16 = 1;
+const ERROR_UNKNOWN_TOPIC_OR_PARTITION: i16 = 3;
+const ERROR_NOT_LEADER_OR_FOLLOWER: i16 = 6;
+const ERROR_FETCH_SESSION_ID_NOT_FOUND: i16 = 70;
+const UNKNOWN_OFFSET: i64 = -1;
+
+/// A live gateway with the topic in place, since Fetch creates nothing.
+async fn gateway_with_topic(server: &TestServer, partitions: u32) -> GatewayState {
+    let bridge = IggyBridge::connect(server.test_config())
+        .await
+        .expect("bridge should connect to a ready server");
+    bridge
+        .ensure_stream_and_topic(TOPIC, partitions)
+        .await
+        .expect("the topic must exist before fetching from it");
+    GatewayState::new(
+        BrokerAdvertise::default(),
+        Some(Arc::new(bridge)),
+        MAX_FRAME_SIZE,
+        false,
+        0,
+        GroupCoordinator::new(GroupCoordinatorConfig::default(), CancellationToken::new()),
+    )
+}
+
+fn record(key: Option<&[u8]>, value: Option<&[u8]>, headers: &[(&str, Option<&[u8]>)]) -> Record {
+    Record {
+        transactional: false,
+        control: false,
+        delete_horizon: false,
+        partition_leader_epoch: NO_PARTITION_LEADER_EPOCH,
+        producer_id: NO_PRODUCER_ID,
+        producer_epoch: NO_PRODUCER_EPOCH,
+        timestamp_type: TimestampType::Creation,
+        offset: 0,
+        sequence: NO_SEQUENCE,
+        timestamp: CREATE_TIME,
+        key: key.map(Bytes::copy_from_slice),
+        value: value.map(Bytes::copy_from_slice),
+        headers: headers
+            .iter()
+            .map(|(name, value)| {
+                (
+                    StrBytes::from_string((*name).to_string()),
+                    value.map(Bytes::copy_from_slice),
+                )
+            })
+            .collect::<IndexMap<_, _>>(),
+    }
+}
+
+/// A keyed record holding `value`.
+fn keyed(value: &[u8]) -> Record {
+    record(Some(b"k"), Some(value), &[])
+}
+
+/// Stores `records` in `partition` the way Produce does: `to_iggy`, then one send.
+async fn store(server: &TestServer, partition: u32, records: &[Record]) {
+    let window = TimestampWindow::of(records);
+    let mut messages: Vec<IggyMessage> = records
+        .iter()
+        .map(|record| to_iggy(record, window).expect("the record maps"))
+        .collect();
+    send(server, partition, &mut messages).await;
+}
+
+async fn send(server: &TestServer, partition: u32, messages: &mut [IggyMessage]) {
+    raw_client(server)
+        .await
+        .send_messages(
+            &Identifier::named(STREAM).expect("valid stream name"),
+            &Identifier::named(TOPIC).expect("valid topic name"),
+            &Partitioning::partition_id(partition),
+            messages,
+        )
+        .await
+        .expect("store the messages");
+}
+
+/// A consumer's full request for `topic`, each partition as `(index, fetch_offset)`.
+fn request(topic: &str, partitions: &[(i32, i64)]) -> FetchRequest {
+    FetchRequest::default()
+        .with_max_wait_ms(10_000)
+        .with_min_bytes(1)
+        .with_max_bytes(52_428_800)
+        .with_session_epoch(0)
+        .with_topics(vec![
+            FetchTopic::default()
+                .with_topic(TopicName(StrBytes::from_string(topic.to_string())))
+                .with_partitions(
+                    partitions
+                        .iter()
+                        .map(|&(partition, fetch_offset)| {
+                            FetchPartition::default()
+                                .with_partition(partition)
+                                .with_fetch_offset(fetch_offset)
+                                .with_partition_max_bytes(PARTITION_MAX_BYTES)
+                        })
+                        .collect(),
+                ),
+        ])
+}
+
+/// Sends `request` through the handler at `version`, and decodes the answer as a consumer does.
+async fn fetch_at(state: &GatewayState, version: i16, request: &FetchRequest) -> FetchResponse {
+    let mut body = BytesMut::new();
+    request
+        .encode(&mut body, version)
+        .expect("the request encodes at this version");
+    let mut response = handle_request_bounded(state, API_KEY_FETCH, version, body.freeze())

Review Comment:
   every handler test goes through handle_request_bounded, which builds a fresh ConnectionState per call. The per-connection -1 hold is never exercised through the handler. **Fix**: two ConnectionStates through handle_connection_request. 



##########
gateways/kafka/src/protocol/handlers/fetch.rs:
##########
@@ -97,6 +187,1222 @@ pub fn encode_response(version: i16, req: &FetchRequest) -> Result<Bytes> {
     encode_inner(version, topics, ERROR_NONE)
 }
 
+fn decode(state: &GatewayState, version: i16, body: Bytes) -> Result<FetchRequest> {
+    decode_guarded::<FetchRequest>(version, body, |v, b| {
+        validate_fetch_shape(v, b, state.max_frame_size)
+    })
+}
+
+/// Whether `request` names every partition it wants. Anything else continues a session, and
+/// this gateway opens none: it always answers `session_id` 0.
+const fn is_full(version: i16, request: &FetchRequest) -> bool {
+    version < SESSION_MIN_VERSION || matches!(request.session_epoch, INITIAL_EPOCH | FINAL_EPOCH)
+}
+
+/// Reads every requested partition once. When that finds nothing, waits for records up to
+/// `max_wait_ms` and reads again.
+///
+/// Returns the read slot too, if the read took one. Keep it until the response is encoded.
+async fn fetch(
+    bridge: &Arc<IggyBridge>,
+    state: &GatewayState,
+    stuck_offsets: &Mutex<StuckOffsets>,
+    request: &FetchRequest,
+) -> (Vec<FetchableTopicResponse>, Option<FetchSlot>) {
+    let started = Instant::now();
+    let give_up_at = started + REQUEST_DEADLINE;
+    let fetch = Fetch::new(bridge, state, stuck_offsets, request, give_up_at);
+    // A shared probe will do: an offset past it goes to a poll, not straight to a 1.
+    let since = recent(started);
+    let mut probes = fetch.probe_all(since).await;
+    let (mut answers, mut slot) = fetch.read(&probes).await;
+    if waits(request, &answers) {
+        // No slot while it waits.
+        drop(slot);
+        let held: Vec<bool> = answers
+            .iter()
+            .map(|answer| retried_at_once(answer.error_code))
+            .collect();
+        let wait_until = started + fetch.max_wait;
+        probes = fetch
+            .wait(probes, &held, request.min_bytes, since, wait_until)
+            .await;
+        // Kafka reads again when the wait ends, too.
+        (answers, slot) = fetch.read(&probes).await;
+    }
+    (group(request, &fetch.wanted, answers), slot)
+}
+
+/// Kafka answers at once when a partition fails, when the request allows no wait, or when the
+/// records read reach `min_bytes`. Otherwise it waits.
+///
+/// A 6 or a -1 waits too. See [`retried_at_once`].
+fn waits(request: &FetchRequest, answers: &[PartitionData]) -> bool {
+    let min_bytes = usize::try_from(request.min_bytes).unwrap_or(0);
+    let record_bytes: usize = answers
+        .iter()
+        .map(|answer| answer.records.as_ref().map_or(0, Bytes::len))
+        .sum();
+    request.max_wait_ms > 0
+        && !answers.is_empty()
+        && record_bytes < min_bytes
+        && answers
+            .iter()
+            .all(|answer| answer.error_code == ERROR_NONE || retried_at_once(answer.error_code))
+}
+
+/// Codes the Java consumer fetches again at once after. Sent at once, they make it spin, so they
+/// wait out the request instead.
+const fn retried_at_once(code: i16) -> bool {
+    matches!(
+        code,
+        ERROR_NOT_LEADER_OR_FOLLOWER | ERROR_UNKNOWN_SERVER_ERROR
+    )
+}
+
+fn wait_time(max_wait_ms: i32) -> Duration {
+    Duration::from_millis(u64::try_from(max_wait_ms).unwrap_or(0)).min(MAX_WAIT)
+}
+
+/// When a -1 hold that starts at `now` ends: after the request's wait, but at least
+/// [`PROBE_INTERVAL`] on. A consumer with a short wait then reads a stuck partition at most ten
+/// times a second.
+fn hold_until(now: Instant, max_wait: Duration) -> Instant {
+    now + max_wait.max(PROBE_INTERVAL)
+}
+
+/// The topics to load a new probe for: each one whose newest probe started before `since`, the
+/// oldest first, at most [`MAX_ROUND_TOPICS`].
+fn stale_topics(snapshots: &[Option<Arc<Snapshot>>], since: Instant) -> Vec<usize> {
+    let started = |topic: usize| snapshots[topic].as_ref().map(|snapshot| snapshot.started);
+    let mut stale: Vec<usize> = (0..snapshots.len())
+        .filter(|&topic| started(topic).is_none_or(|started| started < since))
+        .collect();
+    // No probe sorts first, then the oldest, so each topic gets its turn.
+    stale.sort_by_key(|&topic| started(topic));
+    stale.truncate(MAX_ROUND_TOPICS);
+    stale
+}
+
+/// The topics wait round `turn` probes: the next [`MAX_ROUND_TOPICS`] of `count`, in turn.
+fn round(turn: usize, count: usize) -> impl Iterator<Item = usize> {
+    let start = turn.saturating_mul(MAX_ROUND_TOPICS) % count.max(1);
+    (start..start + MAX_ROUND_TOPICS.min(count)).map(move |topic| topic % count)
+}
+
+/// Waits for the next gateway write to any of the topics behind `writes`, then returns the topics
+/// written, at most [`MAX_ROUND_TOPICS`], each with the time of its write, and marks them seen.
+/// Pends while no write can come.
+async fn next_writes(writes: &mut [watch::Receiver<Option<Instant>>]) -> Vec<(usize, Instant)> {
+    let first = {
+        let mut changes: Vec<_> = writes
+            .iter_mut()
+            .map(|write| Some(Box::pin(write.changed())))
+            .collect();
+        poll_fn(|context| {
+            for (topic, slot) in changes.iter_mut().enumerate() {
+                let Some(change) = slot else { continue };
+                match change.as_mut().poll(context) {
+                    // `changed` marks this write seen.
+                    Poll::Ready(Ok(())) => return Poll::Ready(topic),
+                    // Only a dropped board ends the channel. The board keeps a watched topic.
+                    Poll::Ready(Err(_)) => *slot = None,
+                    Poll::Pending => {}
+                }
+            }
+            Poll::Pending
+        })
+        .await
+    };
+    let mut written = vec![(first, written_at(&mut writes[first]))];
+    written.extend(
+        writes
+            .iter_mut()
+            .enumerate()
+            .filter(|(topic, write)| *topic != first && write.has_changed().unwrap_or(false))
+            .take(MAX_ROUND_TOPICS - 1)
+            .map(|(topic, write)| (topic, written_at(write))),
+    );
+    written
+}
+
+/// When the newest write that `write` shows ended. Marks it seen.
+fn written_at(write: &mut watch::Receiver<Option<Instant>>) -> Instant {
+    let seen = *write.borrow_and_update();
+    seen.unwrap_or_else(Instant::now)
+}
+
+/// The topics behind `writes` whose last gateway write ended at `since` or later, each with the
+/// time of that write, at most [`MAX_ROUND_TOPICS`].
+fn writes_since(
+    writes: &[watch::Receiver<Option<Instant>>],
+    since: Instant,
+) -> Vec<(usize, Instant)> {
+    writes
+        .iter()
+        .enumerate()
+        .filter_map(|(topic, write)| {
+            let written = (*write.borrow())?;
+            (written >= since).then_some((topic, written))
+        })
+        .take(MAX_ROUND_TOPICS)
+        .collect()
+}
+
+/// One request: what it asks for, and what bounds it.
+struct Fetch<'a> {
+    bridge: &'a Arc<IggyBridge>,
+    state: &'a GatewayState,
+    /// The connection's, not the gateway's. See [`ConnectionState`].
+    stuck_offsets: &'a Mutex<StuckOffsets>,
+    wanted: Vec<Wanted<'a>>,
+    /// Each topic to probe once, in request order.
+    topics: Vec<&'a str>,
+    response_bytes: usize,
+    give_up_at: Instant,
+    /// The request's wait, at most [`MAX_WAIT`].
+    max_wait: Duration,
+}
+
+impl<'a> Fetch<'a> {
+    fn new(
+        bridge: &'a Arc<IggyBridge>,
+        state: &'a GatewayState,
+        stuck_offsets: &'a Mutex<StuckOffsets>,
+        request: &'a FetchRequest,
+        give_up_at: Instant,
+    ) -> Self {
+        let (wanted, topics) = wanted(request);
+        Self {
+            bridge,
+            state,
+            stuck_offsets,
+            wanted,
+            topics,
+            response_bytes: response_bytes(request.max_bytes, state.max_frame_size),
+            give_up_at,
+            max_wait: wait_time(request.max_wait_ms),
+        }
+    }
+
+    /// Each topic's probe, started at `since` or later.
+    ///
+    /// Loads at most [`MAX_ROUND_TOPICS`] new probes, the oldest first. Other topics keep an older
+    /// probe, or answer 6 without one. So does a topic not probed before `give_up_at`.
+    async fn probe_all(&self, since: Instant) -> Probes {
+        let board = &self.state.probe_board;
+        let mut snapshots: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.newest(topic))
+            .collect();
+        for topic in stale_topics(&snapshots, since) {
+            let probe = self.probe_topic(self.topics[topic], since, self.give_up_at);
+            if let Some(snapshot) = probe.await {
+                snapshots[topic] = Some(snapshot);
+            }
+        }
+        snapshots
+            .into_iter()
+            .map(|snapshot| {
+                snapshot.map_or(Err(ERROR_NOT_LEADER_OR_FOLLOWER), |snapshot| {
+                    readable(&snapshot)
+                })
+            })
+            .collect()
+    }
+
+    /// `topic`'s probe from the board, started at `since` or later. `None` if none comes by
+    /// `deadline`.
+    async fn probe_topic(
+        &self,
+        topic: &str,
+        since: Instant,
+        deadline: Instant,
+    ) -> Option<Arc<Snapshot>> {
+        let load = || {
+            let (bridge, name) = (Arc::clone(self.bridge), topic.to_owned());
+            async move {
+                let probe = bridge.probe(&name).await;
+                probe.map(Arc::new).map_err(|error| refusal(&name, &error))
+            }
+        };
+        self.state
+            .probe_board
+            .probe(topic, since, deadline, load)
+            .await
+    }
+
+    /// The probe of partition `index` of `topic`, started at `since` or later.
+    ///
+    /// Never the last good probe of a failed refresh: [`empty_poll`] proves nothing from a probe
+    /// taken before the poll, and a stale one would answer an in-range offset 1.
+    async fn probe_partition(
+        &self,
+        topic: &str,
+        index: u32,
+        since: Instant,
+    ) -> Option<PartitionProbe> {
+        let snapshot = self.probe_topic(topic, since, self.give_up_at).await?;
+        snapshot.probe.as_ref().ok()?.get(index)
+    }
+
+    /// Probes until the bytes waiting reach `min_bytes`, a partition fails, or `wait_until`
+    /// passes. Holds no slot while it waits.
+    ///
+    /// Each [`PROBE_INTERVAL`], a round probes the next [`MAX_ROUND_TOPICS`] topics. A gateway
+    /// write to a topic probes it at once. A topic not probed keeps its last probe.
+    ///
+    /// `held` marks partitions that answered 6 or -1. They wait it out and end no wait.
+    ///
+    /// `probed_since` is the oldest start of a fresh probe in hand. A write that ended after it may
+    /// not show in the probes, and subscribing marks it seen, so those topics probe at once. An
+    /// older probe, kept when a refresh failed, is stale by the first round.
+    async fn wait(
+        &self,
+        mut probes: Probes,
+        held: &[bool],
+        min_bytes: i32,
+        probed_since: Instant,
+        wait_until: Instant,
+    ) -> Probes {
+        if held.iter().all(|&held| held) {
+            sleep_until(wait_until).await;
+            return self.probe_all(recent(Instant::now())).await;
+        }
+        let min_bytes = u64::try_from(min_bytes).unwrap_or(0);
+        let board = &self.state.probe_board;
+        let mut writes: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.writes(topic))
+            .collect();
+        let mut missed = writes_since(&writes, probed_since);
+        let mut turn = 0;
+        // Kept across write wakes, so steady writes to one topic do not stop the rounds.
+        let mut round_at = (Instant::now() + PROBE_INTERVAL).min(wait_until);
+        while Instant::now() < wait_until {
+            let written = if missed.is_empty() {
+                tokio::select! {
+                    () = sleep_until(round_at) => None,
+                    written = next_writes(&mut writes) => Some(written),
+                }
+            } else {
+                Some(std::mem::take(&mut missed))
+            };
+            let timed = written.is_none();
+            // A write needs a probe that started after it. A round needs one newer than the last.
+            let due = written.unwrap_or_else(|| {
+                turn += 1;
+                let since = recent(Instant::now());
+                round(turn - 1, self.topics.len())
+                    .map(|topic| (topic, since))
+                    .collect()
+            });
+            for (topic, since) in due {
+                // A probe late for the round still lands on the board for the next Fetch.
+                let probe = self.probe_topic(self.topics[topic], since, wait_until);
+                if let Some(snapshot) = probe.await {
+                    probes[topic] = readable(&snapshot);
+                }
+            }
+            if timed {
+                round_at = (Instant::now() + PROBE_INTERVAL).min(wait_until);
+            }
+            if ready(&self.wanted, held, &probes, self.response_bytes, min_bytes) {
+                break;
+            }
+        }
+        probes
+    }
+
+    /// One answer per requested partition, in request order, and the read slot, if taken.
+    async fn read(&self, probes: &Probes) -> (Vec<PartitionData>, Option<FetchSlot>) {
+        Reader::new(self).read_all(probes).await
+    }
+}
+
+/// One requested partition.
+struct Wanted<'a> {
+    /// Its topic entry in the request.
+    entry: usize,
+    topic: &'a str,
+    partition: i32,
+    fetch_offset: i64,
+    max_bytes: usize,
+    /// Where its probe is, or the code it answers without asking Iggy.
+    probe_at: core::result::Result<ProbeAt, i16>,
+}
+
+/// Where a partition's probe is.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct ProbeAt {
+    /// Its topic's place in `Fetch::topics`.
+    topic: usize,
+    index: u32,
+}
+
+/// Each requested partition once, in request order, and each topic to probe once. A repeat
+/// keeps the first entry.
+///
+/// The Java consumer drops a whole response that leaves out a partition it asked for.
+fn wanted(request: &FetchRequest) -> (Vec<Wanted<'_>>, Vec<&str>) {
+    let total = request
+        .topics
+        .iter()
+        .map(|topic| topic.partitions.len())
+        .sum();
+    let mut seen = HashSet::with_capacity(total);
+    let mut wanted = Vec::with_capacity(total);
+    let mut topics = IndexSet::new();
+    for (entry, topic) in request.topics.iter().enumerate() {
+        let name = topic.topic.as_str();
+        // A name Kafka refuses answers 3 here, so it never takes a place on the probe board.
+        let named = validate_kafka_topic_name("kafka_topic", name)
+            .map_err(|_| ERROR_UNKNOWN_TOPIC_OR_PARTITION);
+        for partition in &topic.partitions {
+            if !seen.insert((name, partition.partition)) {
+                continue;
+            }
+            let probe_at = named
+                .and_then(|()| {
+                    u32::try_from(partition.partition).map_err(|_| ERROR_UNKNOWN_TOPIC_OR_PARTITION)
+                })
+                .map(|index| ProbeAt {
+                    topic: topics.insert_full(name).0,
+                    index,
+                });
+            wanted.push(Wanted {
+                entry,
+                topic: name,
+                partition: partition.partition,
+                fetch_offset: partition.fetch_offset,
+                max_bytes: usize::try_from(partition.partition_max_bytes).unwrap_or(0),
+                probe_at,
+            });
+        }
+    }
+    (wanted, topics.into_iter().collect())
+}
+
+/// Record bytes the whole response may carry: `max_bytes`, at most one frame.
+fn response_bytes(max_bytes: i32, max_frame_size: usize) -> usize {
+    usize::try_from(max_bytes).unwrap_or(0).min(max_frame_size)
+}
+
+/// Per topic in `Fetch::topics`, its probe, or one code for the whole topic.
+type Probes = Vec<TopicProbed>;
+
+/// The probe to read with. A refresh that failed with a code the consumer retries at once gives
+/// way to the last good probe, so a blip in `get_topic` leaves the polls to decide rather than
+/// answering 6 or -1 for partitions that hold records.
+fn readable(snapshot: &Snapshot) -> TopicProbed {
+    match (&snapshot.probe, &snapshot.last_good) {
+        (Err(code), Some(good)) if retried_at_once(*code) => Ok(Arc::clone(good)),
+        (probe, _) => probe.clone(),
+    }
+}
+
+/// Whether a partition now fails, as an error ends Kafka's wait too, or the bytes waiting reach
+/// `min_bytes`. Skips `held` partitions.
+fn ready(

Review Comment:
   last_good  survives every failure (probe_board.rs:155-162). Offset equal to a stale high watermark returns CaughtUp (:680) and serves empty ERROR_NONE with no poll. A caught-up consumer stalls, lag reads 0, for as long as get_topic fails. **Fix**: treat CaughtUp on a fallback probe as Unsure, and cap last_good age.



##########
gateways/kafka/src/protocol/handlers/fetch.rs:
##########
@@ -97,6 +187,1222 @@ pub fn encode_response(version: i16, req: &FetchRequest) -> Result<Bytes> {
     encode_inner(version, topics, ERROR_NONE)
 }
 
+fn decode(state: &GatewayState, version: i16, body: Bytes) -> Result<FetchRequest> {
+    decode_guarded::<FetchRequest>(version, body, |v, b| {
+        validate_fetch_shape(v, b, state.max_frame_size)
+    })
+}
+
+/// Whether `request` names every partition it wants. Anything else continues a session, and
+/// this gateway opens none: it always answers `session_id` 0.
+const fn is_full(version: i16, request: &FetchRequest) -> bool {
+    version < SESSION_MIN_VERSION || matches!(request.session_epoch, INITIAL_EPOCH | FINAL_EPOCH)
+}
+
+/// Reads every requested partition once. When that finds nothing, waits for records up to
+/// `max_wait_ms` and reads again.
+///
+/// Returns the read slot too, if the read took one. Keep it until the response is encoded.
+async fn fetch(
+    bridge: &Arc<IggyBridge>,
+    state: &GatewayState,
+    stuck_offsets: &Mutex<StuckOffsets>,
+    request: &FetchRequest,
+) -> (Vec<FetchableTopicResponse>, Option<FetchSlot>) {
+    let started = Instant::now();
+    let give_up_at = started + REQUEST_DEADLINE;
+    let fetch = Fetch::new(bridge, state, stuck_offsets, request, give_up_at);
+    // A shared probe will do: an offset past it goes to a poll, not straight to a 1.
+    let since = recent(started);
+    let mut probes = fetch.probe_all(since).await;
+    let (mut answers, mut slot) = fetch.read(&probes).await;
+    if waits(request, &answers) {
+        // No slot while it waits.
+        drop(slot);
+        let held: Vec<bool> = answers
+            .iter()
+            .map(|answer| retried_at_once(answer.error_code))
+            .collect();
+        let wait_until = started + fetch.max_wait;
+        probes = fetch
+            .wait(probes, &held, request.min_bytes, since, wait_until)
+            .await;
+        // Kafka reads again when the wait ends, too.
+        (answers, slot) = fetch.read(&probes).await;
+    }
+    (group(request, &fetch.wanted, answers), slot)
+}
+
+/// Kafka answers at once when a partition fails, when the request allows no wait, or when the
+/// records read reach `min_bytes`. Otherwise it waits.
+///
+/// A 6 or a -1 waits too. See [`retried_at_once`].
+fn waits(request: &FetchRequest, answers: &[PartitionData]) -> bool {
+    let min_bytes = usize::try_from(request.min_bytes).unwrap_or(0);
+    let record_bytes: usize = answers
+        .iter()
+        .map(|answer| answer.records.as_ref().map_or(0, Bytes::len))
+        .sum();
+    request.max_wait_ms > 0
+        && !answers.is_empty()
+        && record_bytes < min_bytes
+        && answers
+            .iter()
+            .all(|answer| answer.error_code == ERROR_NONE || retried_at_once(answer.error_code))
+}
+
+/// Codes the Java consumer fetches again at once after. Sent at once, they make it spin, so they
+/// wait out the request instead.
+const fn retried_at_once(code: i16) -> bool {
+    matches!(
+        code,
+        ERROR_NOT_LEADER_OR_FOLLOWER | ERROR_UNKNOWN_SERVER_ERROR
+    )
+}
+
+fn wait_time(max_wait_ms: i32) -> Duration {
+    Duration::from_millis(u64::try_from(max_wait_ms).unwrap_or(0)).min(MAX_WAIT)
+}
+
+/// When a -1 hold that starts at `now` ends: after the request's wait, but at least
+/// [`PROBE_INTERVAL`] on. A consumer with a short wait then reads a stuck partition at most ten
+/// times a second.
+fn hold_until(now: Instant, max_wait: Duration) -> Instant {
+    now + max_wait.max(PROBE_INTERVAL)
+}
+
+/// The topics to load a new probe for: each one whose newest probe started before `since`, the
+/// oldest first, at most [`MAX_ROUND_TOPICS`].
+fn stale_topics(snapshots: &[Option<Arc<Snapshot>>], since: Instant) -> Vec<usize> {
+    let started = |topic: usize| snapshots[topic].as_ref().map(|snapshot| snapshot.started);
+    let mut stale: Vec<usize> = (0..snapshots.len())
+        .filter(|&topic| started(topic).is_none_or(|started| started < since))
+        .collect();
+    // No probe sorts first, then the oldest, so each topic gets its turn.
+    stale.sort_by_key(|&topic| started(topic));
+    stale.truncate(MAX_ROUND_TOPICS);
+    stale
+}
+
+/// The topics wait round `turn` probes: the next [`MAX_ROUND_TOPICS`] of `count`, in turn.
+fn round(turn: usize, count: usize) -> impl Iterator<Item = usize> {
+    let start = turn.saturating_mul(MAX_ROUND_TOPICS) % count.max(1);
+    (start..start + MAX_ROUND_TOPICS.min(count)).map(move |topic| topic % count)
+}
+
+/// Waits for the next gateway write to any of the topics behind `writes`, then returns the topics
+/// written, at most [`MAX_ROUND_TOPICS`], each with the time of its write, and marks them seen.
+/// Pends while no write can come.
+async fn next_writes(writes: &mut [watch::Receiver<Option<Instant>>]) -> Vec<(usize, Instant)> {
+    let first = {
+        let mut changes: Vec<_> = writes
+            .iter_mut()
+            .map(|write| Some(Box::pin(write.changed())))
+            .collect();
+        poll_fn(|context| {
+            for (topic, slot) in changes.iter_mut().enumerate() {
+                let Some(change) = slot else { continue };
+                match change.as_mut().poll(context) {
+                    // `changed` marks this write seen.
+                    Poll::Ready(Ok(())) => return Poll::Ready(topic),
+                    // Only a dropped board ends the channel. The board keeps a watched topic.
+                    Poll::Ready(Err(_)) => *slot = None,
+                    Poll::Pending => {}
+                }
+            }
+            Poll::Pending
+        })
+        .await
+    };
+    let mut written = vec![(first, written_at(&mut writes[first]))];
+    written.extend(
+        writes
+            .iter_mut()
+            .enumerate()
+            .filter(|(topic, write)| *topic != first && write.has_changed().unwrap_or(false))
+            .take(MAX_ROUND_TOPICS - 1)
+            .map(|(topic, write)| (topic, written_at(write))),
+    );
+    written
+}
+
+/// When the newest write that `write` shows ended. Marks it seen.
+fn written_at(write: &mut watch::Receiver<Option<Instant>>) -> Instant {
+    let seen = *write.borrow_and_update();
+    seen.unwrap_or_else(Instant::now)
+}
+
+/// The topics behind `writes` whose last gateway write ended at `since` or later, each with the
+/// time of that write, at most [`MAX_ROUND_TOPICS`].
+fn writes_since(
+    writes: &[watch::Receiver<Option<Instant>>],
+    since: Instant,
+) -> Vec<(usize, Instant)> {
+    writes
+        .iter()
+        .enumerate()
+        .filter_map(|(topic, write)| {
+            let written = (*write.borrow())?;
+            (written >= since).then_some((topic, written))
+        })
+        .take(MAX_ROUND_TOPICS)
+        .collect()
+}
+
+/// One request: what it asks for, and what bounds it.
+struct Fetch<'a> {
+    bridge: &'a Arc<IggyBridge>,
+    state: &'a GatewayState,
+    /// The connection's, not the gateway's. See [`ConnectionState`].
+    stuck_offsets: &'a Mutex<StuckOffsets>,
+    wanted: Vec<Wanted<'a>>,
+    /// Each topic to probe once, in request order.
+    topics: Vec<&'a str>,
+    response_bytes: usize,
+    give_up_at: Instant,
+    /// The request's wait, at most [`MAX_WAIT`].
+    max_wait: Duration,
+}
+
+impl<'a> Fetch<'a> {
+    fn new(
+        bridge: &'a Arc<IggyBridge>,
+        state: &'a GatewayState,
+        stuck_offsets: &'a Mutex<StuckOffsets>,
+        request: &'a FetchRequest,
+        give_up_at: Instant,
+    ) -> Self {
+        let (wanted, topics) = wanted(request);
+        Self {
+            bridge,
+            state,
+            stuck_offsets,
+            wanted,
+            topics,
+            response_bytes: response_bytes(request.max_bytes, state.max_frame_size),
+            give_up_at,
+            max_wait: wait_time(request.max_wait_ms),
+        }
+    }
+
+    /// Each topic's probe, started at `since` or later.
+    ///
+    /// Loads at most [`MAX_ROUND_TOPICS`] new probes, the oldest first. Other topics keep an older
+    /// probe, or answer 6 without one. So does a topic not probed before `give_up_at`.
+    async fn probe_all(&self, since: Instant) -> Probes {
+        let board = &self.state.probe_board;
+        let mut snapshots: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.newest(topic))
+            .collect();
+        for topic in stale_topics(&snapshots, since) {
+            let probe = self.probe_topic(self.topics[topic], since, self.give_up_at);
+            if let Some(snapshot) = probe.await {
+                snapshots[topic] = Some(snapshot);
+            }
+        }
+        snapshots
+            .into_iter()
+            .map(|snapshot| {
+                snapshot.map_or(Err(ERROR_NOT_LEADER_OR_FOLLOWER), |snapshot| {
+                    readable(&snapshot)
+                })
+            })
+            .collect()
+    }
+
+    /// `topic`'s probe from the board, started at `since` or later. `None` if none comes by
+    /// `deadline`.
+    async fn probe_topic(
+        &self,
+        topic: &str,
+        since: Instant,
+        deadline: Instant,
+    ) -> Option<Arc<Snapshot>> {
+        let load = || {
+            let (bridge, name) = (Arc::clone(self.bridge), topic.to_owned());
+            async move {
+                let probe = bridge.probe(&name).await;
+                probe.map(Arc::new).map_err(|error| refusal(&name, &error))
+            }
+        };
+        self.state
+            .probe_board
+            .probe(topic, since, deadline, load)
+            .await
+    }
+
+    /// The probe of partition `index` of `topic`, started at `since` or later.
+    ///
+    /// Never the last good probe of a failed refresh: [`empty_poll`] proves nothing from a probe
+    /// taken before the poll, and a stale one would answer an in-range offset 1.
+    async fn probe_partition(
+        &self,
+        topic: &str,
+        index: u32,
+        since: Instant,
+    ) -> Option<PartitionProbe> {
+        let snapshot = self.probe_topic(topic, since, self.give_up_at).await?;
+        snapshot.probe.as_ref().ok()?.get(index)
+    }
+
+    /// Probes until the bytes waiting reach `min_bytes`, a partition fails, or `wait_until`
+    /// passes. Holds no slot while it waits.
+    ///
+    /// Each [`PROBE_INTERVAL`], a round probes the next [`MAX_ROUND_TOPICS`] topics. A gateway
+    /// write to a topic probes it at once. A topic not probed keeps its last probe.
+    ///
+    /// `held` marks partitions that answered 6 or -1. They wait it out and end no wait.
+    ///
+    /// `probed_since` is the oldest start of a fresh probe in hand. A write that ended after it may
+    /// not show in the probes, and subscribing marks it seen, so those topics probe at once. An
+    /// older probe, kept when a refresh failed, is stale by the first round.
+    async fn wait(
+        &self,
+        mut probes: Probes,
+        held: &[bool],
+        min_bytes: i32,
+        probed_since: Instant,
+        wait_until: Instant,
+    ) -> Probes {
+        if held.iter().all(|&held| held) {
+            sleep_until(wait_until).await;
+            return self.probe_all(recent(Instant::now())).await;
+        }
+        let min_bytes = u64::try_from(min_bytes).unwrap_or(0);
+        let board = &self.state.probe_board;
+        let mut writes: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.writes(topic))
+            .collect();
+        let mut missed = writes_since(&writes, probed_since);
+        let mut turn = 0;
+        // Kept across write wakes, so steady writes to one topic do not stop the rounds.
+        let mut round_at = (Instant::now() + PROBE_INTERVAL).min(wait_until);
+        while Instant::now() < wait_until {
+            let written = if missed.is_empty() {
+                tokio::select! {
+                    () = sleep_until(round_at) => None,
+                    written = next_writes(&mut writes) => Some(written),
+                }
+            } else {
+                Some(std::mem::take(&mut missed))
+            };
+            let timed = written.is_none();
+            // A write needs a probe that started after it. A round needs one newer than the last.
+            let due = written.unwrap_or_else(|| {
+                turn += 1;
+                let since = recent(Instant::now());
+                round(turn - 1, self.topics.len())
+                    .map(|topic| (topic, since))
+                    .collect()
+            });
+            for (topic, since) in due {
+                // A probe late for the round still lands on the board for the next Fetch.
+                let probe = self.probe_topic(self.topics[topic], since, wait_until);
+                if let Some(snapshot) = probe.await {
+                    probes[topic] = readable(&snapshot);
+                }
+            }
+            if timed {
+                round_at = (Instant::now() + PROBE_INTERVAL).min(wait_until);
+            }
+            if ready(&self.wanted, held, &probes, self.response_bytes, min_bytes) {
+                break;
+            }
+        }
+        probes
+    }
+
+    /// One answer per requested partition, in request order, and the read slot, if taken.
+    async fn read(&self, probes: &Probes) -> (Vec<PartitionData>, Option<FetchSlot>) {
+        Reader::new(self).read_all(probes).await
+    }
+}
+
+/// One requested partition.
+struct Wanted<'a> {
+    /// Its topic entry in the request.
+    entry: usize,
+    topic: &'a str,
+    partition: i32,
+    fetch_offset: i64,
+    max_bytes: usize,
+    /// Where its probe is, or the code it answers without asking Iggy.
+    probe_at: core::result::Result<ProbeAt, i16>,
+}
+
+/// Where a partition's probe is.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct ProbeAt {
+    /// Its topic's place in `Fetch::topics`.
+    topic: usize,
+    index: u32,
+}
+
+/// Each requested partition once, in request order, and each topic to probe once. A repeat
+/// keeps the first entry.
+///
+/// The Java consumer drops a whole response that leaves out a partition it asked for.
+fn wanted(request: &FetchRequest) -> (Vec<Wanted<'_>>, Vec<&str>) {
+    let total = request
+        .topics
+        .iter()
+        .map(|topic| topic.partitions.len())
+        .sum();
+    let mut seen = HashSet::with_capacity(total);
+    let mut wanted = Vec::with_capacity(total);
+    let mut topics = IndexSet::new();
+    for (entry, topic) in request.topics.iter().enumerate() {
+        let name = topic.topic.as_str();
+        // A name Kafka refuses answers 3 here, so it never takes a place on the probe board.
+        let named = validate_kafka_topic_name("kafka_topic", name)
+            .map_err(|_| ERROR_UNKNOWN_TOPIC_OR_PARTITION);
+        for partition in &topic.partitions {
+            if !seen.insert((name, partition.partition)) {
+                continue;
+            }
+            let probe_at = named
+                .and_then(|()| {
+                    u32::try_from(partition.partition).map_err(|_| ERROR_UNKNOWN_TOPIC_OR_PARTITION)
+                })
+                .map(|index| ProbeAt {
+                    topic: topics.insert_full(name).0,
+                    index,
+                });
+            wanted.push(Wanted {
+                entry,
+                topic: name,
+                partition: partition.partition,
+                fetch_offset: partition.fetch_offset,
+                max_bytes: usize::try_from(partition.partition_max_bytes).unwrap_or(0),
+                probe_at,
+            });
+        }
+    }
+    (wanted, topics.into_iter().collect())
+}
+
+/// Record bytes the whole response may carry: `max_bytes`, at most one frame.
+fn response_bytes(max_bytes: i32, max_frame_size: usize) -> usize {
+    usize::try_from(max_bytes).unwrap_or(0).min(max_frame_size)
+}
+
+/// Per topic in `Fetch::topics`, its probe, or one code for the whole topic.
+type Probes = Vec<TopicProbed>;
+
+/// The probe to read with. A refresh that failed with a code the consumer retries at once gives
+/// way to the last good probe, so a blip in `get_topic` leaves the polls to decide rather than
+/// answering 6 or -1 for partitions that hold records.
+fn readable(snapshot: &Snapshot) -> TopicProbed {
+    match (&snapshot.probe, &snapshot.last_good) {
+        (Err(code), Some(good)) if retried_at_once(*code) => Ok(Arc::clone(good)),
+        (probe, _) => probe.clone(),
+    }
+}
+
+/// Whether a partition now fails, as an error ends Kafka's wait too, or the bytes waiting reach
+/// `min_bytes`. Skips `held` partitions.
+fn ready(
+    wanted: &[Wanted<'_>],
+    held: &[bool],
+    probes: &Probes,
+    response_bytes: usize,
+    min_bytes: u64,
+) -> bool {
+    let mut waiting = 0u64;
+    for (want, _) in wanted.iter().zip(held).filter(|&(_, &held)| !held) {
+        match position(want, probes) {
+            Position::Refused(_) => return true,
+            // Past the end of this probe, or no message kept. A newer probe, or the read after
+            // the wait, decides.
+            Position::CaughtUp(_) | Position::Unsure { .. } => {}
+            Position::Behind { offset, probe, .. } => {
+                let budget = want.max_bytes.min(response_bytes);
+                waiting = waiting.saturating_add(bytes_waiting(offset, probe, budget));
+            }
+        }
+    }
+    waiting >= min_bytes
+}
+
+/// Estimated bytes past `offset`, at most `budget`. Kafka's delayed fetch counts the same way.
+fn bytes_waiting(offset: u64, probe: PartitionProbe, budget: usize) -> u64 {
+    probe
+        .high_watermark
+        .saturating_sub(offset)
+        .saturating_mul(probe.average_size)
+        .min(u64::try_from(budget).unwrap_or(u64::MAX))
+}
+
+/// Where a requested offset stands against the probe.
+#[derive(Debug, PartialEq, Eq)]
+enum Position {
+    /// Answer this code, with no records.
+    Refused(i16),
+    /// At the high watermark. Answer 0, with no records.
+    CaughtUp(PartitionProbe),
+    /// Records wait in partition `index` from `offset` on.
+    Behind {
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    },
+    /// The probe cannot place `offset`. One poll decides.
+    Unsure {
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    },
+}
+
+fn position(want: &Wanted<'_>, probes: &Probes) -> Position {
+    let at = match want.probe_at {
+        Ok(at) => at,
+        Err(code) => return Position::Refused(code),
+    };
+    // `Fetch::probe_all` probes every topic in `Fetch::topics`, in order.
+    let probe = match &probes[at.topic] {
+        Ok(topic) => match topic.get(at.index) {
+            Some(probe) => probe,
+            None => return Position::Refused(ERROR_UNKNOWN_TOPIC_OR_PARTITION),
+        },
+        Err(code) => return Position::Refused(*code),
+    };
+    if probe.is_loading() {
+        return Position::Refused(ERROR_NOT_LEADER_OR_FOLLOWER);
+    }
+    // Below the oldest retained offset is in range: Iggy reads from the first retained message,
+    // and Kafka consumers accept the gap.
+    match u64::try_from(want.fetch_offset) {
+        Ok(offset) if offset == probe.high_watermark => Position::CaughtUp(probe),
+        // Retention can remove every message, and a server with no stats reads the same. Past
+        // the end, a shared probe can predate records the consumer already read.
+        Ok(offset) if probe.messages_count == 0 || offset > probe.high_watermark => {
+            Position::Unsure {
+                index: at.index,
+                offset,
+                probe,
+            }
+        }
+        Ok(offset) => Position::Behind {
+            index: at.index,
+            offset,
+            probe,
+        },
+        Err(_) => Position::Refused(ERROR_OFFSET_OUT_OF_RANGE),
+    }
+}
+
+/// Reads partitions in request order, as Kafka does from v3, and spends one byte budget on them.
+struct Reader<'a> {
+    fetch: &'a Fetch<'a>,
+    bytes_left: usize,
+    /// No partition has answered with records yet, so the next one returns at least one, whatever
+    /// the limits say (KIP-74). A record larger than every limit would stall the consumer
+    /// otherwise.
+    owes_first_record: bool,
+    /// Taken at the first poll, and freed before a probe that confirms an empty one. A poll given
+    /// up on keeps it until the poll ends.
+    slot: Option<FetchSlot>,
+}
+
+impl<'a> Reader<'a> {
+    const fn new(fetch: &'a Fetch<'a>) -> Self {
+        Self {
+            fetch,
+            bytes_left: fetch.response_bytes,
+            owes_first_record: true,
+            slot: None,
+        }
+    }
+
+    /// One answer per requested partition, in request order, and the slot, if taken.
+    async fn read_all(mut self, probes: &Probes) -> (Vec<PartitionData>, Option<FetchSlot>) {
+        let fetch = self.fetch;
+        let mut answers = Vec::with_capacity(fetch.wanted.len());
+        for want in &fetch.wanted {
+            let answer = match position(want, probes) {
+                Position::Refused(code) => refused(want.partition, code),
+                Position::CaughtUp(probe) => {
+                    served(want.partition, probe.high_watermark, Bytes::new())
+                }
+                Position::Behind { index, offset, .. } | Position::Unsure { index, offset, .. }
+                    if held(
+                        fetch.stuck_offsets,
+                        want.topic,
+                        index,
+                        offset,
+                        Instant::now(),
+                    ) =>
+                {
+                    refused(want.partition, ERROR_UNKNOWN_SERVER_ERROR)
+                }
+                Position::Behind {
+                    index,
+                    offset,
+                    probe,
+                } => {
+                    let polled = Polled::new(offset, probe.high_watermark);
+                    self.read(want, index, offset, probe, polled).await
+                }
+                Position::Unsure {
+                    index,
+                    offset,
+                    probe,
+                } => self.settle(want, index, offset, probe).await,
+            };
+            answers.push(answer);
+        }
+        (answers, self.slot)
+    }
+
+    /// Polls one partition that has records waiting, and answers with what its budget holds.
+    async fn read(
+        &mut self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+        mut polled: Polled,
+    ) -> PartitionData {
+        let budget = want.max_bytes.min(self.bytes_left);
+        // Unless a record is owed, skip a poll that likely brings back nothing that fits.
+        let average = usize::try_from(probe.average_size).unwrap_or(usize::MAX);
+        if self.owes_first_record || budget >= average.max(1) {
+            while let Some(count) = next_page(&polled, budget, probe.average_size) {
+                let asked = Instant::now();
+                let Some(page) = self.poll(want.topic, index, polled.next, count).await else {
+                    break;
+                };
+                match page {
+                    // The probe showed records, yet the first poll found none.
+                    Ok(page) if page.messages.is_empty() && polled.messages.is_empty() => {
+                        return self
+                            .after_empty_poll(want, index, offset, probe, asked)
+                            .await;
+                    }
+                    Ok(page) => polled.add(page, count),
+                    Err(error) if polled.messages.is_empty() => {
+                        return self.refuse(want, index, offset, &error);
+                    }
+                    // Serve what the earlier polls brought.
+                    Err(_) => break,
+                }
+            }
+        }
+
+        let keep_one = self.owes_first_record;
+        let encoded = off_worker(polled.bytes >= CODEC_OFF_WORKER_BYTES, || {
+            encode_records(&polled.messages, offset, budget, keep_one)
+        });
+        match encoded {
+            Ok(batch) => {
+                self.bytes_left = self.bytes_left.saturating_sub(batch.len());
+                self.owes_first_record &= batch.is_empty();
+                served(want.partition, polled.high_watermark, batch)
+            }
+            Err(error) => {
+                let stuck = self.fetch.stuck_offsets;
+                let now = Instant::now();
+                let first = hold(stuck, want.topic, index, offset, now, self.fetch.max_wait);
+                log_stuck(first, want.topic, index, offset, &error);
+                refused(want.partition, ERROR_UNKNOWN_SERVER_ERROR)
+            }
+        }
+    }
+
+    /// Reads a partition the probe cannot place, with a poll at `offset`.
+    ///
+    /// - Records: serve them. The probe missed them.
+    /// - Nothing, and Iggy's commit ends just before `offset`: caught up.
+    /// - Nothing else: a probe taken after the poll decides. See [`empty_poll`].
+    async fn settle(
+        &mut self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    ) -> PartitionData {
+        // Sized as a read's first page, since an empty answer costs the same round trip.
+        let budget = want.max_bytes.min(self.bytes_left);
+        let count = poll_count(budget, probe.average_size, u64::from(MAX_PAGE_COUNT));
+        let asked = Instant::now();
+        match self.poll(want.topic, index, offset, count).await {
+            // Never below the offset, or the consumer reports negative lag.
+            None => served(
+                want.partition,
+                probe.high_watermark.max(offset),
+                Bytes::new(),
+            ),
+            Some(Err(error)) => self.refuse(want, index, offset, &error),
+            Some(Ok(page)) if !page.messages.is_empty() => {
+                let mut polled = Polled::new(offset, probe.high_watermark);
+                polled.add(page, count);
+                self.read(want, index, offset, probe, polled).await
+            }
+            Some(Ok(page)) if caught_up(offset, page.current_offset) => {
+                served(want.partition, offset, Bytes::new())
+            }
+            Some(Ok(_)) => {
+                self.after_empty_poll(want, index, offset, probe, asked)
+                    .await
+            }
+        }
+    }
+
+    /// Answers an empty poll at `offset`, made at `asked`, from `before` and a probe taken after
+    /// it. See [`empty_poll`].
+    async fn after_empty_poll(
+        &mut self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        before: PartitionProbe,
+        asked: Instant,
+    ) -> PartitionData {
+        // The probe can wait behind other Iggy calls until the deadline, and every Fetch needs a
+        // slot to poll. The next poll takes one again.
+        self.slot = None;
+        let after = self.fetch.probe_partition(want.topic, index, asked).await;
+        match empty_poll(offset, before, after) {
+            EmptyPoll::OutOfRange { high_watermark } => {
+                // No offset past 0: maybe a partition that Iggy loads or fences.
+                let not_ready = &self.fetch.state.not_ready;
+                let loading = high_watermark <= 1

Review Comment:
   after RELOAD_GRACE (30s), the hwm≤1 / (0,0) shape answers 1 even when before.high_watermark > offset. (0,0) is also a stats-registry miss (core/server/src/responses.rs:951). earliest and latest both land on 0 and replay the partition. none throws. Test at :1850-1856 pins this, and its name contradicts its body. **Fix**: do not answer 1 from an ambiguous hwm≤1 shape without proof. Keep a waited 6 or serve empty, and log a warning. 



##########
gateways/kafka/src/protocol/handlers/fetch.rs:
##########
@@ -97,6 +187,1222 @@ pub fn encode_response(version: i16, req: &FetchRequest) -> Result<Bytes> {
     encode_inner(version, topics, ERROR_NONE)
 }
 
+fn decode(state: &GatewayState, version: i16, body: Bytes) -> Result<FetchRequest> {
+    decode_guarded::<FetchRequest>(version, body, |v, b| {
+        validate_fetch_shape(v, b, state.max_frame_size)
+    })
+}
+
+/// Whether `request` names every partition it wants. Anything else continues a session, and
+/// this gateway opens none: it always answers `session_id` 0.
+const fn is_full(version: i16, request: &FetchRequest) -> bool {
+    version < SESSION_MIN_VERSION || matches!(request.session_epoch, INITIAL_EPOCH | FINAL_EPOCH)
+}
+
+/// Reads every requested partition once. When that finds nothing, waits for records up to
+/// `max_wait_ms` and reads again.
+///
+/// Returns the read slot too, if the read took one. Keep it until the response is encoded.
+async fn fetch(
+    bridge: &Arc<IggyBridge>,
+    state: &GatewayState,
+    stuck_offsets: &Mutex<StuckOffsets>,
+    request: &FetchRequest,
+) -> (Vec<FetchableTopicResponse>, Option<FetchSlot>) {
+    let started = Instant::now();
+    let give_up_at = started + REQUEST_DEADLINE;
+    let fetch = Fetch::new(bridge, state, stuck_offsets, request, give_up_at);
+    // A shared probe will do: an offset past it goes to a poll, not straight to a 1.
+    let since = recent(started);
+    let mut probes = fetch.probe_all(since).await;
+    let (mut answers, mut slot) = fetch.read(&probes).await;
+    if waits(request, &answers) {
+        // No slot while it waits.
+        drop(slot);
+        let held: Vec<bool> = answers
+            .iter()
+            .map(|answer| retried_at_once(answer.error_code))
+            .collect();
+        let wait_until = started + fetch.max_wait;
+        probes = fetch
+            .wait(probes, &held, request.min_bytes, since, wait_until)
+            .await;
+        // Kafka reads again when the wait ends, too.
+        (answers, slot) = fetch.read(&probes).await;
+    }
+    (group(request, &fetch.wanted, answers), slot)
+}
+
+/// Kafka answers at once when a partition fails, when the request allows no wait, or when the
+/// records read reach `min_bytes`. Otherwise it waits.
+///
+/// A 6 or a -1 waits too. See [`retried_at_once`].
+fn waits(request: &FetchRequest, answers: &[PartitionData]) -> bool {
+    let min_bytes = usize::try_from(request.min_bytes).unwrap_or(0);
+    let record_bytes: usize = answers
+        .iter()
+        .map(|answer| answer.records.as_ref().map_or(0, Bytes::len))
+        .sum();
+    request.max_wait_ms > 0
+        && !answers.is_empty()
+        && record_bytes < min_bytes
+        && answers
+            .iter()
+            .all(|answer| answer.error_code == ERROR_NONE || retried_at_once(answer.error_code))
+}
+
+/// Codes the Java consumer fetches again at once after. Sent at once, they make it spin, so they
+/// wait out the request instead.
+const fn retried_at_once(code: i16) -> bool {
+    matches!(
+        code,
+        ERROR_NOT_LEADER_OR_FOLLOWER | ERROR_UNKNOWN_SERVER_ERROR
+    )
+}
+
+fn wait_time(max_wait_ms: i32) -> Duration {
+    Duration::from_millis(u64::try_from(max_wait_ms).unwrap_or(0)).min(MAX_WAIT)
+}
+
+/// When a -1 hold that starts at `now` ends: after the request's wait, but at least
+/// [`PROBE_INTERVAL`] on. A consumer with a short wait then reads a stuck partition at most ten
+/// times a second.
+fn hold_until(now: Instant, max_wait: Duration) -> Instant {
+    now + max_wait.max(PROBE_INTERVAL)
+}
+
+/// The topics to load a new probe for: each one whose newest probe started before `since`, the
+/// oldest first, at most [`MAX_ROUND_TOPICS`].
+fn stale_topics(snapshots: &[Option<Arc<Snapshot>>], since: Instant) -> Vec<usize> {
+    let started = |topic: usize| snapshots[topic].as_ref().map(|snapshot| snapshot.started);
+    let mut stale: Vec<usize> = (0..snapshots.len())
+        .filter(|&topic| started(topic).is_none_or(|started| started < since))
+        .collect();
+    // No probe sorts first, then the oldest, so each topic gets its turn.
+    stale.sort_by_key(|&topic| started(topic));
+    stale.truncate(MAX_ROUND_TOPICS);
+    stale
+}
+
+/// The topics wait round `turn` probes: the next [`MAX_ROUND_TOPICS`] of `count`, in turn.
+fn round(turn: usize, count: usize) -> impl Iterator<Item = usize> {
+    let start = turn.saturating_mul(MAX_ROUND_TOPICS) % count.max(1);
+    (start..start + MAX_ROUND_TOPICS.min(count)).map(move |topic| topic % count)
+}
+
+/// Waits for the next gateway write to any of the topics behind `writes`, then returns the topics
+/// written, at most [`MAX_ROUND_TOPICS`], each with the time of its write, and marks them seen.
+/// Pends while no write can come.
+async fn next_writes(writes: &mut [watch::Receiver<Option<Instant>>]) -> Vec<(usize, Instant)> {
+    let first = {
+        let mut changes: Vec<_> = writes
+            .iter_mut()
+            .map(|write| Some(Box::pin(write.changed())))
+            .collect();
+        poll_fn(|context| {
+            for (topic, slot) in changes.iter_mut().enumerate() {
+                let Some(change) = slot else { continue };
+                match change.as_mut().poll(context) {
+                    // `changed` marks this write seen.
+                    Poll::Ready(Ok(())) => return Poll::Ready(topic),
+                    // Only a dropped board ends the channel. The board keeps a watched topic.
+                    Poll::Ready(Err(_)) => *slot = None,
+                    Poll::Pending => {}
+                }
+            }
+            Poll::Pending
+        })
+        .await
+    };
+    let mut written = vec![(first, written_at(&mut writes[first]))];
+    written.extend(
+        writes
+            .iter_mut()
+            .enumerate()
+            .filter(|(topic, write)| *topic != first && write.has_changed().unwrap_or(false))
+            .take(MAX_ROUND_TOPICS - 1)
+            .map(|(topic, write)| (topic, written_at(write))),
+    );
+    written
+}
+
+/// When the newest write that `write` shows ended. Marks it seen.
+fn written_at(write: &mut watch::Receiver<Option<Instant>>) -> Instant {
+    let seen = *write.borrow_and_update();
+    seen.unwrap_or_else(Instant::now)
+}
+
+/// The topics behind `writes` whose last gateway write ended at `since` or later, each with the
+/// time of that write, at most [`MAX_ROUND_TOPICS`].
+fn writes_since(
+    writes: &[watch::Receiver<Option<Instant>>],
+    since: Instant,
+) -> Vec<(usize, Instant)> {
+    writes
+        .iter()
+        .enumerate()
+        .filter_map(|(topic, write)| {
+            let written = (*write.borrow())?;
+            (written >= since).then_some((topic, written))
+        })
+        .take(MAX_ROUND_TOPICS)
+        .collect()
+}
+
+/// One request: what it asks for, and what bounds it.
+struct Fetch<'a> {
+    bridge: &'a Arc<IggyBridge>,
+    state: &'a GatewayState,
+    /// The connection's, not the gateway's. See [`ConnectionState`].
+    stuck_offsets: &'a Mutex<StuckOffsets>,
+    wanted: Vec<Wanted<'a>>,
+    /// Each topic to probe once, in request order.
+    topics: Vec<&'a str>,
+    response_bytes: usize,
+    give_up_at: Instant,
+    /// The request's wait, at most [`MAX_WAIT`].
+    max_wait: Duration,
+}
+
+impl<'a> Fetch<'a> {
+    fn new(
+        bridge: &'a Arc<IggyBridge>,
+        state: &'a GatewayState,
+        stuck_offsets: &'a Mutex<StuckOffsets>,
+        request: &'a FetchRequest,
+        give_up_at: Instant,
+    ) -> Self {
+        let (wanted, topics) = wanted(request);
+        Self {
+            bridge,
+            state,
+            stuck_offsets,
+            wanted,
+            topics,
+            response_bytes: response_bytes(request.max_bytes, state.max_frame_size),
+            give_up_at,
+            max_wait: wait_time(request.max_wait_ms),
+        }
+    }
+
+    /// Each topic's probe, started at `since` or later.
+    ///
+    /// Loads at most [`MAX_ROUND_TOPICS`] new probes, the oldest first. Other topics keep an older
+    /// probe, or answer 6 without one. So does a topic not probed before `give_up_at`.
+    async fn probe_all(&self, since: Instant) -> Probes {
+        let board = &self.state.probe_board;
+        let mut snapshots: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.newest(topic))
+            .collect();
+        for topic in stale_topics(&snapshots, since) {
+            let probe = self.probe_topic(self.topics[topic], since, self.give_up_at);
+            if let Some(snapshot) = probe.await {
+                snapshots[topic] = Some(snapshot);
+            }
+        }
+        snapshots
+            .into_iter()
+            .map(|snapshot| {
+                snapshot.map_or(Err(ERROR_NOT_LEADER_OR_FOLLOWER), |snapshot| {
+                    readable(&snapshot)
+                })
+            })
+            .collect()
+    }
+
+    /// `topic`'s probe from the board, started at `since` or later. `None` if none comes by
+    /// `deadline`.
+    async fn probe_topic(
+        &self,
+        topic: &str,
+        since: Instant,
+        deadline: Instant,
+    ) -> Option<Arc<Snapshot>> {
+        let load = || {
+            let (bridge, name) = (Arc::clone(self.bridge), topic.to_owned());
+            async move {
+                let probe = bridge.probe(&name).await;
+                probe.map(Arc::new).map_err(|error| refusal(&name, &error))
+            }
+        };
+        self.state
+            .probe_board
+            .probe(topic, since, deadline, load)
+            .await
+    }
+
+    /// The probe of partition `index` of `topic`, started at `since` or later.
+    ///
+    /// Never the last good probe of a failed refresh: [`empty_poll`] proves nothing from a probe
+    /// taken before the poll, and a stale one would answer an in-range offset 1.
+    async fn probe_partition(
+        &self,
+        topic: &str,
+        index: u32,
+        since: Instant,
+    ) -> Option<PartitionProbe> {
+        let snapshot = self.probe_topic(topic, since, self.give_up_at).await?;
+        snapshot.probe.as_ref().ok()?.get(index)
+    }
+
+    /// Probes until the bytes waiting reach `min_bytes`, a partition fails, or `wait_until`
+    /// passes. Holds no slot while it waits.
+    ///
+    /// Each [`PROBE_INTERVAL`], a round probes the next [`MAX_ROUND_TOPICS`] topics. A gateway
+    /// write to a topic probes it at once. A topic not probed keeps its last probe.
+    ///
+    /// `held` marks partitions that answered 6 or -1. They wait it out and end no wait.
+    ///
+    /// `probed_since` is the oldest start of a fresh probe in hand. A write that ended after it may
+    /// not show in the probes, and subscribing marks it seen, so those topics probe at once. An
+    /// older probe, kept when a refresh failed, is stale by the first round.
+    async fn wait(
+        &self,
+        mut probes: Probes,
+        held: &[bool],
+        min_bytes: i32,
+        probed_since: Instant,
+        wait_until: Instant,
+    ) -> Probes {
+        if held.iter().all(|&held| held) {
+            sleep_until(wait_until).await;
+            return self.probe_all(recent(Instant::now())).await;
+        }
+        let min_bytes = u64::try_from(min_bytes).unwrap_or(0);
+        let board = &self.state.probe_board;
+        let mut writes: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.writes(topic))
+            .collect();
+        let mut missed = writes_since(&writes, probed_since);
+        let mut turn = 0;
+        // Kept across write wakes, so steady writes to one topic do not stop the rounds.
+        let mut round_at = (Instant::now() + PROBE_INTERVAL).min(wait_until);
+        while Instant::now() < wait_until {
+            let written = if missed.is_empty() {
+                tokio::select! {
+                    () = sleep_until(round_at) => None,
+                    written = next_writes(&mut writes) => Some(written),
+                }
+            } else {
+                Some(std::mem::take(&mut missed))
+            };
+            let timed = written.is_none();
+            // A write needs a probe that started after it. A round needs one newer than the last.
+            let due = written.unwrap_or_else(|| {
+                turn += 1;
+                let since = recent(Instant::now());
+                round(turn - 1, self.topics.len())
+                    .map(|topic| (topic, since))
+                    .collect()
+            });
+            for (topic, since) in due {
+                // A probe late for the round still lands on the board for the next Fetch.
+                let probe = self.probe_topic(self.topics[topic], since, wait_until);
+                if let Some(snapshot) = probe.await {
+                    probes[topic] = readable(&snapshot);
+                }
+            }
+            if timed {
+                round_at = (Instant::now() + PROBE_INTERVAL).min(wait_until);
+            }
+            if ready(&self.wanted, held, &probes, self.response_bytes, min_bytes) {
+                break;
+            }
+        }
+        probes
+    }
+
+    /// One answer per requested partition, in request order, and the read slot, if taken.
+    async fn read(&self, probes: &Probes) -> (Vec<PartitionData>, Option<FetchSlot>) {
+        Reader::new(self).read_all(probes).await
+    }
+}
+
+/// One requested partition.
+struct Wanted<'a> {
+    /// Its topic entry in the request.
+    entry: usize,
+    topic: &'a str,
+    partition: i32,
+    fetch_offset: i64,
+    max_bytes: usize,
+    /// Where its probe is, or the code it answers without asking Iggy.
+    probe_at: core::result::Result<ProbeAt, i16>,
+}
+
+/// Where a partition's probe is.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct ProbeAt {
+    /// Its topic's place in `Fetch::topics`.
+    topic: usize,
+    index: u32,
+}
+
+/// Each requested partition once, in request order, and each topic to probe once. A repeat
+/// keeps the first entry.
+///
+/// The Java consumer drops a whole response that leaves out a partition it asked for.
+fn wanted(request: &FetchRequest) -> (Vec<Wanted<'_>>, Vec<&str>) {
+    let total = request
+        .topics
+        .iter()
+        .map(|topic| topic.partitions.len())
+        .sum();
+    let mut seen = HashSet::with_capacity(total);
+    let mut wanted = Vec::with_capacity(total);
+    let mut topics = IndexSet::new();
+    for (entry, topic) in request.topics.iter().enumerate() {
+        let name = topic.topic.as_str();
+        // A name Kafka refuses answers 3 here, so it never takes a place on the probe board.
+        let named = validate_kafka_topic_name("kafka_topic", name)
+            .map_err(|_| ERROR_UNKNOWN_TOPIC_OR_PARTITION);
+        for partition in &topic.partitions {
+            if !seen.insert((name, partition.partition)) {
+                continue;
+            }
+            let probe_at = named
+                .and_then(|()| {
+                    u32::try_from(partition.partition).map_err(|_| ERROR_UNKNOWN_TOPIC_OR_PARTITION)
+                })
+                .map(|index| ProbeAt {
+                    topic: topics.insert_full(name).0,
+                    index,
+                });
+            wanted.push(Wanted {
+                entry,
+                topic: name,
+                partition: partition.partition,
+                fetch_offset: partition.fetch_offset,
+                max_bytes: usize::try_from(partition.partition_max_bytes).unwrap_or(0),
+                probe_at,
+            });
+        }
+    }
+    (wanted, topics.into_iter().collect())
+}
+
+/// Record bytes the whole response may carry: `max_bytes`, at most one frame.
+fn response_bytes(max_bytes: i32, max_frame_size: usize) -> usize {
+    usize::try_from(max_bytes).unwrap_or(0).min(max_frame_size)
+}
+
+/// Per topic in `Fetch::topics`, its probe, or one code for the whole topic.
+type Probes = Vec<TopicProbed>;
+
+/// The probe to read with. A refresh that failed with a code the consumer retries at once gives
+/// way to the last good probe, so a blip in `get_topic` leaves the polls to decide rather than
+/// answering 6 or -1 for partitions that hold records.
+fn readable(snapshot: &Snapshot) -> TopicProbed {
+    match (&snapshot.probe, &snapshot.last_good) {
+        (Err(code), Some(good)) if retried_at_once(*code) => Ok(Arc::clone(good)),
+        (probe, _) => probe.clone(),
+    }
+}
+
+/// Whether a partition now fails, as an error ends Kafka's wait too, or the bytes waiting reach
+/// `min_bytes`. Skips `held` partitions.
+fn ready(
+    wanted: &[Wanted<'_>],
+    held: &[bool],
+    probes: &Probes,
+    response_bytes: usize,
+    min_bytes: u64,
+) -> bool {
+    let mut waiting = 0u64;
+    for (want, _) in wanted.iter().zip(held).filter(|&(_, &held)| !held) {
+        match position(want, probes) {
+            Position::Refused(_) => return true,
+            // Past the end of this probe, or no message kept. A newer probe, or the read after
+            // the wait, decides.
+            Position::CaughtUp(_) | Position::Unsure { .. } => {}
+            Position::Behind { offset, probe, .. } => {
+                let budget = want.max_bytes.min(response_bytes);
+                waiting = waiting.saturating_add(bytes_waiting(offset, probe, budget));
+            }
+        }
+    }
+    waiting >= min_bytes
+}
+
+/// Estimated bytes past `offset`, at most `budget`. Kafka's delayed fetch counts the same way.
+fn bytes_waiting(offset: u64, probe: PartitionProbe, budget: usize) -> u64 {
+    probe
+        .high_watermark
+        .saturating_sub(offset)
+        .saturating_mul(probe.average_size)
+        .min(u64::try_from(budget).unwrap_or(u64::MAX))
+}
+
+/// Where a requested offset stands against the probe.
+#[derive(Debug, PartialEq, Eq)]
+enum Position {
+    /// Answer this code, with no records.
+    Refused(i16),
+    /// At the high watermark. Answer 0, with no records.
+    CaughtUp(PartitionProbe),
+    /// Records wait in partition `index` from `offset` on.
+    Behind {
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    },
+    /// The probe cannot place `offset`. One poll decides.
+    Unsure {
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    },
+}
+
+fn position(want: &Wanted<'_>, probes: &Probes) -> Position {
+    let at = match want.probe_at {
+        Ok(at) => at,
+        Err(code) => return Position::Refused(code),
+    };
+    // `Fetch::probe_all` probes every topic in `Fetch::topics`, in order.
+    let probe = match &probes[at.topic] {
+        Ok(topic) => match topic.get(at.index) {
+            Some(probe) => probe,
+            None => return Position::Refused(ERROR_UNKNOWN_TOPIC_OR_PARTITION),
+        },
+        Err(code) => return Position::Refused(*code),
+    };
+    if probe.is_loading() {
+        return Position::Refused(ERROR_NOT_LEADER_OR_FOLLOWER);
+    }
+    // Below the oldest retained offset is in range: Iggy reads from the first retained message,
+    // and Kafka consumers accept the gap.
+    match u64::try_from(want.fetch_offset) {
+        Ok(offset) if offset == probe.high_watermark => Position::CaughtUp(probe),
+        // Retention can remove every message, and a server with no stats reads the same. Past
+        // the end, a shared probe can predate records the consumer already read.
+        Ok(offset) if probe.messages_count == 0 || offset > probe.high_watermark => {
+            Position::Unsure {
+                index: at.index,
+                offset,
+                probe,
+            }
+        }
+        Ok(offset) => Position::Behind {
+            index: at.index,
+            offset,
+            probe,
+        },
+        Err(_) => Position::Refused(ERROR_OFFSET_OUT_OF_RANGE),
+    }
+}
+
+/// Reads partitions in request order, as Kafka does from v3, and spends one byte budget on them.
+struct Reader<'a> {
+    fetch: &'a Fetch<'a>,
+    bytes_left: usize,
+    /// No partition has answered with records yet, so the next one returns at least one, whatever
+    /// the limits say (KIP-74). A record larger than every limit would stall the consumer
+    /// otherwise.
+    owes_first_record: bool,
+    /// Taken at the first poll, and freed before a probe that confirms an empty one. A poll given
+    /// up on keeps it until the poll ends.
+    slot: Option<FetchSlot>,
+}
+
+impl<'a> Reader<'a> {
+    const fn new(fetch: &'a Fetch<'a>) -> Self {
+        Self {
+            fetch,
+            bytes_left: fetch.response_bytes,
+            owes_first_record: true,
+            slot: None,
+        }
+    }
+
+    /// One answer per requested partition, in request order, and the slot, if taken.
+    async fn read_all(mut self, probes: &Probes) -> (Vec<PartitionData>, Option<FetchSlot>) {
+        let fetch = self.fetch;
+        let mut answers = Vec::with_capacity(fetch.wanted.len());
+        for want in &fetch.wanted {
+            let answer = match position(want, probes) {
+                Position::Refused(code) => refused(want.partition, code),
+                Position::CaughtUp(probe) => {
+                    served(want.partition, probe.high_watermark, Bytes::new())
+                }
+                Position::Behind { index, offset, .. } | Position::Unsure { index, offset, .. }
+                    if held(
+                        fetch.stuck_offsets,
+                        want.topic,
+                        index,
+                        offset,
+                        Instant::now(),
+                    ) =>
+                {
+                    refused(want.partition, ERROR_UNKNOWN_SERVER_ERROR)
+                }
+                Position::Behind {
+                    index,
+                    offset,
+                    probe,
+                } => {
+                    let polled = Polled::new(offset, probe.high_watermark);
+                    self.read(want, index, offset, probe, polled).await
+                }
+                Position::Unsure {
+                    index,
+                    offset,
+                    probe,
+                } => self.settle(want, index, offset, probe).await,
+            };
+            answers.push(answer);
+        }
+        (answers, self.slot)
+    }
+
+    /// Polls one partition that has records waiting, and answers with what its budget holds.
+    async fn read(
+        &mut self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+        mut polled: Polled,
+    ) -> PartitionData {
+        let budget = want.max_bytes.min(self.bytes_left);
+        // Unless a record is owed, skip a poll that likely brings back nothing that fits.
+        let average = usize::try_from(probe.average_size).unwrap_or(usize::MAX);
+        if self.owes_first_record || budget >= average.max(1) {
+            while let Some(count) = next_page(&polled, budget, probe.average_size) {
+                let asked = Instant::now();
+                let Some(page) = self.poll(want.topic, index, polled.next, count).await else {
+                    break;
+                };
+                match page {
+                    // The probe showed records, yet the first poll found none.
+                    Ok(page) if page.messages.is_empty() && polled.messages.is_empty() => {
+                        return self
+                            .after_empty_poll(want, index, offset, probe, asked)
+                            .await;
+                    }
+                    Ok(page) => polled.add(page, count),
+                    Err(error) if polled.messages.is_empty() => {
+                        return self.refuse(want, index, offset, &error);
+                    }
+                    // Serve what the earlier polls brought.
+                    Err(_) => break,
+                }
+            }
+        }
+
+        let keep_one = self.owes_first_record;
+        let encoded = off_worker(polled.bytes >= CODEC_OFF_WORKER_BYTES, || {
+            encode_records(&polled.messages, offset, budget, keep_one)
+        });
+        match encoded {
+            Ok(batch) => {
+                self.bytes_left = self.bytes_left.saturating_sub(batch.len());
+                self.owes_first_record &= batch.is_empty();
+                served(want.partition, polled.high_watermark, batch)
+            }
+            Err(error) => {
+                let stuck = self.fetch.stuck_offsets;
+                let now = Instant::now();
+                let first = hold(stuck, want.topic, index, offset, now, self.fetch.max_wait);
+                log_stuck(first, want.topic, index, offset, &error);
+                refused(want.partition, ERROR_UNKNOWN_SERVER_ERROR)
+            }
+        }
+    }
+
+    /// Reads a partition the probe cannot place, with a poll at `offset`.
+    ///
+    /// - Records: serve them. The probe missed them.
+    /// - Nothing, and Iggy's commit ends just before `offset`: caught up.
+    /// - Nothing else: a probe taken after the poll decides. See [`empty_poll`].
+    async fn settle(
+        &mut self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    ) -> PartitionData {
+        // Sized as a read's first page, since an empty answer costs the same round trip.
+        let budget = want.max_bytes.min(self.bytes_left);
+        let count = poll_count(budget, probe.average_size, u64::from(MAX_PAGE_COUNT));
+        let asked = Instant::now();
+        match self.poll(want.topic, index, offset, count).await {

Review Comment:
   settle polls even when the byte budget is spent (poll_count floors at 1). Each empty poll forces a fresh get_topic per partition and bypasses MAX_ROUND_TOPICS. A request can name up to 4096 partitions (bounds_guard.rs:67). **Fix**: skip settle when the budget is 0 and no record is owed, and allow one after-probe per topic per read. Also check at lines 866-869



##########
gateways/kafka/src/protocol/handlers/fetch.rs:
##########
@@ -97,6 +187,1222 @@ pub fn encode_response(version: i16, req: &FetchRequest) -> Result<Bytes> {
     encode_inner(version, topics, ERROR_NONE)
 }
 
+fn decode(state: &GatewayState, version: i16, body: Bytes) -> Result<FetchRequest> {
+    decode_guarded::<FetchRequest>(version, body, |v, b| {
+        validate_fetch_shape(v, b, state.max_frame_size)
+    })
+}
+
+/// Whether `request` names every partition it wants. Anything else continues a session, and
+/// this gateway opens none: it always answers `session_id` 0.
+const fn is_full(version: i16, request: &FetchRequest) -> bool {
+    version < SESSION_MIN_VERSION || matches!(request.session_epoch, INITIAL_EPOCH | FINAL_EPOCH)
+}
+
+/// Reads every requested partition once. When that finds nothing, waits for records up to
+/// `max_wait_ms` and reads again.
+///
+/// Returns the read slot too, if the read took one. Keep it until the response is encoded.
+async fn fetch(
+    bridge: &Arc<IggyBridge>,
+    state: &GatewayState,
+    stuck_offsets: &Mutex<StuckOffsets>,
+    request: &FetchRequest,
+) -> (Vec<FetchableTopicResponse>, Option<FetchSlot>) {
+    let started = Instant::now();
+    let give_up_at = started + REQUEST_DEADLINE;
+    let fetch = Fetch::new(bridge, state, stuck_offsets, request, give_up_at);
+    // A shared probe will do: an offset past it goes to a poll, not straight to a 1.
+    let since = recent(started);
+    let mut probes = fetch.probe_all(since).await;
+    let (mut answers, mut slot) = fetch.read(&probes).await;
+    if waits(request, &answers) {
+        // No slot while it waits.
+        drop(slot);
+        let held: Vec<bool> = answers
+            .iter()
+            .map(|answer| retried_at_once(answer.error_code))
+            .collect();
+        let wait_until = started + fetch.max_wait;
+        probes = fetch
+            .wait(probes, &held, request.min_bytes, since, wait_until)
+            .await;
+        // Kafka reads again when the wait ends, too.
+        (answers, slot) = fetch.read(&probes).await;
+    }
+    (group(request, &fetch.wanted, answers), slot)
+}
+
+/// Kafka answers at once when a partition fails, when the request allows no wait, or when the
+/// records read reach `min_bytes`. Otherwise it waits.
+///
+/// A 6 or a -1 waits too. See [`retried_at_once`].
+fn waits(request: &FetchRequest, answers: &[PartitionData]) -> bool {
+    let min_bytes = usize::try_from(request.min_bytes).unwrap_or(0);
+    let record_bytes: usize = answers
+        .iter()
+        .map(|answer| answer.records.as_ref().map_or(0, Bytes::len))
+        .sum();
+    request.max_wait_ms > 0
+        && !answers.is_empty()
+        && record_bytes < min_bytes
+        && answers
+            .iter()
+            .all(|answer| answer.error_code == ERROR_NONE || retried_at_once(answer.error_code))
+}
+
+/// Codes the Java consumer fetches again at once after. Sent at once, they make it spin, so they
+/// wait out the request instead.
+const fn retried_at_once(code: i16) -> bool {
+    matches!(
+        code,
+        ERROR_NOT_LEADER_OR_FOLLOWER | ERROR_UNKNOWN_SERVER_ERROR
+    )
+}
+
+fn wait_time(max_wait_ms: i32) -> Duration {
+    Duration::from_millis(u64::try_from(max_wait_ms).unwrap_or(0)).min(MAX_WAIT)
+}
+
+/// When a -1 hold that starts at `now` ends: after the request's wait, but at least
+/// [`PROBE_INTERVAL`] on. A consumer with a short wait then reads a stuck partition at most ten
+/// times a second.
+fn hold_until(now: Instant, max_wait: Duration) -> Instant {
+    now + max_wait.max(PROBE_INTERVAL)
+}
+
+/// The topics to load a new probe for: each one whose newest probe started before `since`, the
+/// oldest first, at most [`MAX_ROUND_TOPICS`].
+fn stale_topics(snapshots: &[Option<Arc<Snapshot>>], since: Instant) -> Vec<usize> {
+    let started = |topic: usize| snapshots[topic].as_ref().map(|snapshot| snapshot.started);
+    let mut stale: Vec<usize> = (0..snapshots.len())
+        .filter(|&topic| started(topic).is_none_or(|started| started < since))
+        .collect();
+    // No probe sorts first, then the oldest, so each topic gets its turn.
+    stale.sort_by_key(|&topic| started(topic));
+    stale.truncate(MAX_ROUND_TOPICS);
+    stale
+}
+
+/// The topics wait round `turn` probes: the next [`MAX_ROUND_TOPICS`] of `count`, in turn.
+fn round(turn: usize, count: usize) -> impl Iterator<Item = usize> {
+    let start = turn.saturating_mul(MAX_ROUND_TOPICS) % count.max(1);
+    (start..start + MAX_ROUND_TOPICS.min(count)).map(move |topic| topic % count)
+}
+
+/// Waits for the next gateway write to any of the topics behind `writes`, then returns the topics
+/// written, at most [`MAX_ROUND_TOPICS`], each with the time of its write, and marks them seen.
+/// Pends while no write can come.
+async fn next_writes(writes: &mut [watch::Receiver<Option<Instant>>]) -> Vec<(usize, Instant)> {
+    let first = {
+        let mut changes: Vec<_> = writes
+            .iter_mut()
+            .map(|write| Some(Box::pin(write.changed())))
+            .collect();
+        poll_fn(|context| {
+            for (topic, slot) in changes.iter_mut().enumerate() {
+                let Some(change) = slot else { continue };
+                match change.as_mut().poll(context) {
+                    // `changed` marks this write seen.
+                    Poll::Ready(Ok(())) => return Poll::Ready(topic),
+                    // Only a dropped board ends the channel. The board keeps a watched topic.
+                    Poll::Ready(Err(_)) => *slot = None,
+                    Poll::Pending => {}
+                }
+            }
+            Poll::Pending
+        })
+        .await
+    };
+    let mut written = vec![(first, written_at(&mut writes[first]))];
+    written.extend(
+        writes
+            .iter_mut()
+            .enumerate()
+            .filter(|(topic, write)| *topic != first && write.has_changed().unwrap_or(false))
+            .take(MAX_ROUND_TOPICS - 1)
+            .map(|(topic, write)| (topic, written_at(write))),
+    );
+    written
+}
+
+/// When the newest write that `write` shows ended. Marks it seen.
+fn written_at(write: &mut watch::Receiver<Option<Instant>>) -> Instant {
+    let seen = *write.borrow_and_update();
+    seen.unwrap_or_else(Instant::now)
+}
+
+/// The topics behind `writes` whose last gateway write ended at `since` or later, each with the
+/// time of that write, at most [`MAX_ROUND_TOPICS`].
+fn writes_since(
+    writes: &[watch::Receiver<Option<Instant>>],
+    since: Instant,
+) -> Vec<(usize, Instant)> {
+    writes
+        .iter()
+        .enumerate()
+        .filter_map(|(topic, write)| {
+            let written = (*write.borrow())?;
+            (written >= since).then_some((topic, written))
+        })
+        .take(MAX_ROUND_TOPICS)
+        .collect()
+}
+
+/// One request: what it asks for, and what bounds it.
+struct Fetch<'a> {
+    bridge: &'a Arc<IggyBridge>,
+    state: &'a GatewayState,
+    /// The connection's, not the gateway's. See [`ConnectionState`].
+    stuck_offsets: &'a Mutex<StuckOffsets>,
+    wanted: Vec<Wanted<'a>>,
+    /// Each topic to probe once, in request order.
+    topics: Vec<&'a str>,
+    response_bytes: usize,
+    give_up_at: Instant,
+    /// The request's wait, at most [`MAX_WAIT`].
+    max_wait: Duration,
+}
+
+impl<'a> Fetch<'a> {
+    fn new(
+        bridge: &'a Arc<IggyBridge>,
+        state: &'a GatewayState,
+        stuck_offsets: &'a Mutex<StuckOffsets>,
+        request: &'a FetchRequest,
+        give_up_at: Instant,
+    ) -> Self {
+        let (wanted, topics) = wanted(request);
+        Self {
+            bridge,
+            state,
+            stuck_offsets,
+            wanted,
+            topics,
+            response_bytes: response_bytes(request.max_bytes, state.max_frame_size),
+            give_up_at,
+            max_wait: wait_time(request.max_wait_ms),
+        }
+    }
+
+    /// Each topic's probe, started at `since` or later.
+    ///
+    /// Loads at most [`MAX_ROUND_TOPICS`] new probes, the oldest first. Other topics keep an older
+    /// probe, or answer 6 without one. So does a topic not probed before `give_up_at`.
+    async fn probe_all(&self, since: Instant) -> Probes {
+        let board = &self.state.probe_board;
+        let mut snapshots: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.newest(topic))
+            .collect();
+        for topic in stale_topics(&snapshots, since) {
+            let probe = self.probe_topic(self.topics[topic], since, self.give_up_at);
+            if let Some(snapshot) = probe.await {
+                snapshots[topic] = Some(snapshot);
+            }
+        }
+        snapshots
+            .into_iter()
+            .map(|snapshot| {
+                snapshot.map_or(Err(ERROR_NOT_LEADER_OR_FOLLOWER), |snapshot| {
+                    readable(&snapshot)
+                })
+            })
+            .collect()
+    }
+
+    /// `topic`'s probe from the board, started at `since` or later. `None` if none comes by
+    /// `deadline`.
+    async fn probe_topic(
+        &self,
+        topic: &str,
+        since: Instant,
+        deadline: Instant,
+    ) -> Option<Arc<Snapshot>> {
+        let load = || {
+            let (bridge, name) = (Arc::clone(self.bridge), topic.to_owned());
+            async move {
+                let probe = bridge.probe(&name).await;
+                probe.map(Arc::new).map_err(|error| refusal(&name, &error))
+            }
+        };
+        self.state
+            .probe_board
+            .probe(topic, since, deadline, load)
+            .await
+    }
+
+    /// The probe of partition `index` of `topic`, started at `since` or later.
+    ///
+    /// Never the last good probe of a failed refresh: [`empty_poll`] proves nothing from a probe
+    /// taken before the poll, and a stale one would answer an in-range offset 1.
+    async fn probe_partition(
+        &self,
+        topic: &str,
+        index: u32,
+        since: Instant,
+    ) -> Option<PartitionProbe> {
+        let snapshot = self.probe_topic(topic, since, self.give_up_at).await?;
+        snapshot.probe.as_ref().ok()?.get(index)
+    }
+
+    /// Probes until the bytes waiting reach `min_bytes`, a partition fails, or `wait_until`
+    /// passes. Holds no slot while it waits.
+    ///
+    /// Each [`PROBE_INTERVAL`], a round probes the next [`MAX_ROUND_TOPICS`] topics. A gateway
+    /// write to a topic probes it at once. A topic not probed keeps its last probe.
+    ///
+    /// `held` marks partitions that answered 6 or -1. They wait it out and end no wait.
+    ///
+    /// `probed_since` is the oldest start of a fresh probe in hand. A write that ended after it may
+    /// not show in the probes, and subscribing marks it seen, so those topics probe at once. An
+    /// older probe, kept when a refresh failed, is stale by the first round.
+    async fn wait(
+        &self,
+        mut probes: Probes,
+        held: &[bool],
+        min_bytes: i32,
+        probed_since: Instant,
+        wait_until: Instant,
+    ) -> Probes {
+        if held.iter().all(|&held| held) {
+            sleep_until(wait_until).await;
+            return self.probe_all(recent(Instant::now())).await;
+        }
+        let min_bytes = u64::try_from(min_bytes).unwrap_or(0);
+        let board = &self.state.probe_board;
+        let mut writes: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.writes(topic))
+            .collect();
+        let mut missed = writes_since(&writes, probed_since);
+        let mut turn = 0;
+        // Kept across write wakes, so steady writes to one topic do not stop the rounds.
+        let mut round_at = (Instant::now() + PROBE_INTERVAL).min(wait_until);
+        while Instant::now() < wait_until {
+            let written = if missed.is_empty() {
+                tokio::select! {
+                    () = sleep_until(round_at) => None,
+                    written = next_writes(&mut writes) => Some(written),
+                }
+            } else {
+                Some(std::mem::take(&mut missed))
+            };
+            let timed = written.is_none();
+            // A write needs a probe that started after it. A round needs one newer than the last.
+            let due = written.unwrap_or_else(|| {
+                turn += 1;
+                let since = recent(Instant::now());
+                round(turn - 1, self.topics.len())
+                    .map(|topic| (topic, since))
+                    .collect()
+            });
+            for (topic, since) in due {
+                // A probe late for the round still lands on the board for the next Fetch.
+                let probe = self.probe_topic(self.topics[topic], since, wait_until);
+                if let Some(snapshot) = probe.await {
+                    probes[topic] = readable(&snapshot);
+                }
+            }
+            if timed {
+                round_at = (Instant::now() + PROBE_INTERVAL).min(wait_until);
+            }
+            if ready(&self.wanted, held, &probes, self.response_bytes, min_bytes) {
+                break;
+            }
+        }
+        probes
+    }
+
+    /// One answer per requested partition, in request order, and the read slot, if taken.
+    async fn read(&self, probes: &Probes) -> (Vec<PartitionData>, Option<FetchSlot>) {
+        Reader::new(self).read_all(probes).await
+    }
+}
+
+/// One requested partition.
+struct Wanted<'a> {
+    /// Its topic entry in the request.
+    entry: usize,
+    topic: &'a str,
+    partition: i32,
+    fetch_offset: i64,
+    max_bytes: usize,
+    /// Where its probe is, or the code it answers without asking Iggy.
+    probe_at: core::result::Result<ProbeAt, i16>,
+}
+
+/// Where a partition's probe is.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct ProbeAt {
+    /// Its topic's place in `Fetch::topics`.
+    topic: usize,
+    index: u32,
+}
+
+/// Each requested partition once, in request order, and each topic to probe once. A repeat
+/// keeps the first entry.
+///
+/// The Java consumer drops a whole response that leaves out a partition it asked for.
+fn wanted(request: &FetchRequest) -> (Vec<Wanted<'_>>, Vec<&str>) {
+    let total = request
+        .topics
+        .iter()
+        .map(|topic| topic.partitions.len())
+        .sum();
+    let mut seen = HashSet::with_capacity(total);
+    let mut wanted = Vec::with_capacity(total);
+    let mut topics = IndexSet::new();
+    for (entry, topic) in request.topics.iter().enumerate() {
+        let name = topic.topic.as_str();
+        // A name Kafka refuses answers 3 here, so it never takes a place on the probe board.
+        let named = validate_kafka_topic_name("kafka_topic", name)
+            .map_err(|_| ERROR_UNKNOWN_TOPIC_OR_PARTITION);
+        for partition in &topic.partitions {
+            if !seen.insert((name, partition.partition)) {
+                continue;
+            }
+            let probe_at = named
+                .and_then(|()| {
+                    u32::try_from(partition.partition).map_err(|_| ERROR_UNKNOWN_TOPIC_OR_PARTITION)
+                })
+                .map(|index| ProbeAt {
+                    topic: topics.insert_full(name).0,
+                    index,
+                });
+            wanted.push(Wanted {
+                entry,
+                topic: name,
+                partition: partition.partition,
+                fetch_offset: partition.fetch_offset,
+                max_bytes: usize::try_from(partition.partition_max_bytes).unwrap_or(0),
+                probe_at,
+            });
+        }
+    }
+    (wanted, topics.into_iter().collect())
+}
+
+/// Record bytes the whole response may carry: `max_bytes`, at most one frame.
+fn response_bytes(max_bytes: i32, max_frame_size: usize) -> usize {
+    usize::try_from(max_bytes).unwrap_or(0).min(max_frame_size)
+}
+
+/// Per topic in `Fetch::topics`, its probe, or one code for the whole topic.
+type Probes = Vec<TopicProbed>;
+
+/// The probe to read with. A refresh that failed with a code the consumer retries at once gives
+/// way to the last good probe, so a blip in `get_topic` leaves the polls to decide rather than
+/// answering 6 or -1 for partitions that hold records.
+fn readable(snapshot: &Snapshot) -> TopicProbed {
+    match (&snapshot.probe, &snapshot.last_good) {
+        (Err(code), Some(good)) if retried_at_once(*code) => Ok(Arc::clone(good)),
+        (probe, _) => probe.clone(),
+    }
+}
+
+/// Whether a partition now fails, as an error ends Kafka's wait too, or the bytes waiting reach
+/// `min_bytes`. Skips `held` partitions.
+fn ready(
+    wanted: &[Wanted<'_>],
+    held: &[bool],
+    probes: &Probes,
+    response_bytes: usize,
+    min_bytes: u64,
+) -> bool {
+    let mut waiting = 0u64;
+    for (want, _) in wanted.iter().zip(held).filter(|&(_, &held)| !held) {
+        match position(want, probes) {
+            Position::Refused(_) => return true,
+            // Past the end of this probe, or no message kept. A newer probe, or the read after
+            // the wait, decides.
+            Position::CaughtUp(_) | Position::Unsure { .. } => {}
+            Position::Behind { offset, probe, .. } => {
+                let budget = want.max_bytes.min(response_bytes);
+                waiting = waiting.saturating_add(bytes_waiting(offset, probe, budget));
+            }
+        }
+    }
+    waiting >= min_bytes
+}
+
+/// Estimated bytes past `offset`, at most `budget`. Kafka's delayed fetch counts the same way.
+fn bytes_waiting(offset: u64, probe: PartitionProbe, budget: usize) -> u64 {
+    probe
+        .high_watermark
+        .saturating_sub(offset)
+        .saturating_mul(probe.average_size)
+        .min(u64::try_from(budget).unwrap_or(u64::MAX))
+}
+
+/// Where a requested offset stands against the probe.
+#[derive(Debug, PartialEq, Eq)]
+enum Position {
+    /// Answer this code, with no records.
+    Refused(i16),
+    /// At the high watermark. Answer 0, with no records.
+    CaughtUp(PartitionProbe),
+    /// Records wait in partition `index` from `offset` on.
+    Behind {
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    },
+    /// The probe cannot place `offset`. One poll decides.
+    Unsure {
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    },
+}
+
+fn position(want: &Wanted<'_>, probes: &Probes) -> Position {
+    let at = match want.probe_at {
+        Ok(at) => at,
+        Err(code) => return Position::Refused(code),
+    };
+    // `Fetch::probe_all` probes every topic in `Fetch::topics`, in order.
+    let probe = match &probes[at.topic] {
+        Ok(topic) => match topic.get(at.index) {
+            Some(probe) => probe,
+            None => return Position::Refused(ERROR_UNKNOWN_TOPIC_OR_PARTITION),
+        },
+        Err(code) => return Position::Refused(*code),
+    };
+    if probe.is_loading() {
+        return Position::Refused(ERROR_NOT_LEADER_OR_FOLLOWER);
+    }
+    // Below the oldest retained offset is in range: Iggy reads from the first retained message,
+    // and Kafka consumers accept the gap.
+    match u64::try_from(want.fetch_offset) {
+        Ok(offset) if offset == probe.high_watermark => Position::CaughtUp(probe),
+        // Retention can remove every message, and a server with no stats reads the same. Past
+        // the end, a shared probe can predate records the consumer already read.
+        Ok(offset) if probe.messages_count == 0 || offset > probe.high_watermark => {
+            Position::Unsure {
+                index: at.index,
+                offset,
+                probe,
+            }
+        }
+        Ok(offset) => Position::Behind {
+            index: at.index,
+            offset,
+            probe,
+        },
+        Err(_) => Position::Refused(ERROR_OFFSET_OUT_OF_RANGE),
+    }
+}
+
+/// Reads partitions in request order, as Kafka does from v3, and spends one byte budget on them.
+struct Reader<'a> {
+    fetch: &'a Fetch<'a>,
+    bytes_left: usize,
+    /// No partition has answered with records yet, so the next one returns at least one, whatever
+    /// the limits say (KIP-74). A record larger than every limit would stall the consumer
+    /// otherwise.
+    owes_first_record: bool,
+    /// Taken at the first poll, and freed before a probe that confirms an empty one. A poll given
+    /// up on keeps it until the poll ends.
+    slot: Option<FetchSlot>,
+}
+
+impl<'a> Reader<'a> {
+    const fn new(fetch: &'a Fetch<'a>) -> Self {
+        Self {
+            fetch,
+            bytes_left: fetch.response_bytes,
+            owes_first_record: true,
+            slot: None,
+        }
+    }
+
+    /// One answer per requested partition, in request order, and the slot, if taken.
+    async fn read_all(mut self, probes: &Probes) -> (Vec<PartitionData>, Option<FetchSlot>) {
+        let fetch = self.fetch;
+        let mut answers = Vec::with_capacity(fetch.wanted.len());
+        for want in &fetch.wanted {
+            let answer = match position(want, probes) {
+                Position::Refused(code) => refused(want.partition, code),
+                Position::CaughtUp(probe) => {
+                    served(want.partition, probe.high_watermark, Bytes::new())
+                }
+                Position::Behind { index, offset, .. } | Position::Unsure { index, offset, .. }
+                    if held(
+                        fetch.stuck_offsets,
+                        want.topic,
+                        index,
+                        offset,
+                        Instant::now(),
+                    ) =>
+                {
+                    refused(want.partition, ERROR_UNKNOWN_SERVER_ERROR)
+                }
+                Position::Behind {
+                    index,
+                    offset,
+                    probe,
+                } => {
+                    let polled = Polled::new(offset, probe.high_watermark);
+                    self.read(want, index, offset, probe, polled).await
+                }
+                Position::Unsure {
+                    index,
+                    offset,
+                    probe,
+                } => self.settle(want, index, offset, probe).await,
+            };
+            answers.push(answer);
+        }
+        (answers, self.slot)
+    }
+
+    /// Polls one partition that has records waiting, and answers with what its budget holds.
+    async fn read(
+        &mut self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+        mut polled: Polled,
+    ) -> PartitionData {
+        let budget = want.max_bytes.min(self.bytes_left);
+        // Unless a record is owed, skip a poll that likely brings back nothing that fits.
+        let average = usize::try_from(probe.average_size).unwrap_or(usize::MAX);
+        if self.owes_first_record || budget >= average.max(1) {
+            while let Some(count) = next_page(&polled, budget, probe.average_size) {
+                let asked = Instant::now();
+                let Some(page) = self.poll(want.topic, index, polled.next, count).await else {
+                    break;
+                };
+                match page {
+                    // The probe showed records, yet the first poll found none.
+                    Ok(page) if page.messages.is_empty() && polled.messages.is_empty() => {
+                        return self
+                            .after_empty_poll(want, index, offset, probe, asked)
+                            .await;
+                    }
+                    Ok(page) => polled.add(page, count),
+                    Err(error) if polled.messages.is_empty() => {
+                        return self.refuse(want, index, offset, &error);
+                    }
+                    // Serve what the earlier polls brought.
+                    Err(_) => break,
+                }
+            }
+        }
+
+        let keep_one = self.owes_first_record;
+        let encoded = off_worker(polled.bytes >= CODEC_OFF_WORKER_BYTES, || {
+            encode_records(&polled.messages, offset, budget, keep_one)
+        });
+        match encoded {
+            Ok(batch) => {
+                self.bytes_left = self.bytes_left.saturating_sub(batch.len());
+                self.owes_first_record &= batch.is_empty();
+                served(want.partition, polled.high_watermark, batch)
+            }
+            Err(error) => {
+                let stuck = self.fetch.stuck_offsets;
+                let now = Instant::now();
+                let first = hold(stuck, want.topic, index, offset, now, self.fetch.max_wait);
+                log_stuck(first, want.topic, index, offset, &error);
+                refused(want.partition, ERROR_UNKNOWN_SERVER_ERROR)
+            }
+        }
+    }
+
+    /// Reads a partition the probe cannot place, with a poll at `offset`.
+    ///
+    /// - Records: serve them. The probe missed them.
+    /// - Nothing, and Iggy's commit ends just before `offset`: caught up.
+    /// - Nothing else: a probe taken after the poll decides. See [`empty_poll`].
+    async fn settle(
+        &mut self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    ) -> PartitionData {
+        // Sized as a read's first page, since an empty answer costs the same round trip.
+        let budget = want.max_bytes.min(self.bytes_left);
+        let count = poll_count(budget, probe.average_size, u64::from(MAX_PAGE_COUNT));
+        let asked = Instant::now();
+        match self.poll(want.topic, index, offset, count).await {
+            // Never below the offset, or the consumer reports negative lag.
+            None => served(
+                want.partition,
+                probe.high_watermark.max(offset),
+                Bytes::new(),
+            ),
+            Some(Err(error)) => self.refuse(want, index, offset, &error),
+            Some(Ok(page)) if !page.messages.is_empty() => {
+                let mut polled = Polled::new(offset, probe.high_watermark);
+                polled.add(page, count);
+                self.read(want, index, offset, probe, polled).await
+            }
+            Some(Ok(page)) if caught_up(offset, page.current_offset) => {
+                served(want.partition, offset, Bytes::new())
+            }
+            Some(Ok(_)) => {
+                self.after_empty_poll(want, index, offset, probe, asked)
+                    .await
+            }
+        }
+    }
+
+    /// Answers an empty poll at `offset`, made at `asked`, from `before` and a probe taken after
+    /// it. See [`empty_poll`].
+    async fn after_empty_poll(
+        &mut self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        before: PartitionProbe,
+        asked: Instant,
+    ) -> PartitionData {
+        // The probe can wait behind other Iggy calls until the deadline, and every Fetch needs a
+        // slot to poll. The next poll takes one again.
+        self.slot = None;
+        let after = self.fetch.probe_partition(want.topic, index, asked).await;
+        match empty_poll(offset, before, after) {
+            EmptyPoll::OutOfRange { high_watermark } => {
+                // No offset past 0: maybe a partition that Iggy loads or fences.
+                let not_ready = &self.fetch.state.not_ready;
+                let loading = high_watermark <= 1
+                    && spell(not_ready, want.topic, index, Instant::now()) < RELOAD_GRACE;
+                let code = if loading {
+                    ERROR_NOT_LEADER_OR_FOLLOWER
+                } else {
+                    ERROR_OFFSET_OUT_OF_RANGE
+                };
+                refused(want.partition, code)
+            }
+            EmptyPoll::NotReady => {
+                let spell = spell(
+                    &self.fetch.state.not_ready,
+                    want.topic,
+                    index,
+                    Instant::now(),
+                );
+                log_not_ready(spell.is_zero(), want.topic, index, offset);
+                refused(want.partition, ERROR_NOT_LEADER_OR_FOLLOWER)
+            }
+            EmptyPoll::Unproven => {
+                let high_watermark =
+                    after.map_or(before.high_watermark, |after| after.high_watermark);
+                served(want.partition, high_watermark.max(offset), Bytes::new())
+            }
+        }
+    }
+
+    /// The code for `error`. A -1 also holds the partition, so reads skip Iggy until the hold ends.
+    fn refuse(
+        &self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        error: &BridgeError,
+    ) -> PartitionData {
+        let code = refusal(want.topic, error);
+        if code == ERROR_UNKNOWN_SERVER_ERROR {
+            hold(
+                self.fetch.stuck_offsets,
+                want.topic,
+                index,
+                offset,
+                Instant::now(),
+                self.fetch.max_wait,
+            );
+        }
+        refused(want.partition, code)
+    }
+
+    /// Polls one page, in the read slot. `None` once `give_up_at` passes.
+    async fn poll(
+        &mut self,
+        topic: &str,
+        index: u32,
+        offset: u64,
+        count: u32,
+    ) -> Option<core::result::Result<PolledMessages, BridgeError>> {
+        let give_up_at = self.fetch.give_up_at;
+        if Instant::now() >= give_up_at {
+            return None;
+        }
+        let bridge = self.fetch.bridge;
+        let (page, slot) = bridge
+            .poll(
+                self.take_slot().await?,
+                topic,
+                index,
+                offset,
+                count,
+                give_up_at,
+            )
+            .await?;
+        self.slot = Some(slot);
+        Some(page)
+    }
+
+    /// The read slot, taken at the first poll. `None` once `give_up_at` passes.
+    async fn take_slot(&mut self) -> Option<FetchSlot> {
+        match self.slot.take() {
+            Some(slot) => Some(slot),
+            None => self.fetch.bridge.fetch_slot(self.fetch.give_up_at).await,
+        }
+    }
+}
+
+/// Whether an empty poll at `offset` proves the consumer is at the end: Iggy's commit counter,
+/// `current_offset`, ends just before it. A 0 proves nothing, since an empty partition and a failed
+/// read send 0 too.
+const fn caught_up(offset: u64, current_offset: u64) -> bool {
+    current_offset > 0 && current_offset.saturating_add(1) == offset
+}
+
+/// What an empty poll proves.
+#[derive(Debug, PartialEq, Eq)]
+enum EmptyPoll {
+    /// The offset is past `high_watermark`, the end after the poll.
+    OutOfRange { high_watermark: u64 },
+    /// Records remain, yet the poll found none: a read fault, or a partition Iggy loads. Retry.
+    NotReady,
+    /// Nothing. Serve no records, and the consumer asks again.
+    Unproven,
+}
+
+/// Decides an empty poll at `offset` from the probe before it and one taken after it.
+///
+/// Iggy also answers empty on a read fault, so only `after` proves anything. No message kept below
+/// the end proves no gap: a cluster replica reads so after a crash or a failed install, while its
+/// peers keep the records. So the consumer waits for the next write instead of moving past them.
+const fn empty_poll(
+    offset: u64,
+    before: PartitionProbe,
+    after: Option<PartitionProbe>,
+) -> EmptyPoll {
+    let Some(after) = after else {
+        return EmptyPoll::Unproven;
+    };
+    if after.is_loading() {
+        EmptyPoll::NotReady
+    } else if offset > after.high_watermark {
+        EmptyPoll::OutOfRange {
+            high_watermark: after.high_watermark,
+        }
+    } else if after.messages_count > 0
+        && offset < before.high_watermark
+        && offset < after.high_watermark
+    {
+        EmptyPoll::NotReady
+    } else {
+        EmptyPoll::Unproven
+    }
+}
+
+/// Per Kafka topic, then partition, so a lookup takes a `&str` and allocates nothing.
+///
+/// A new key first sweeps out the entries its caller no longer needs, once the map has doubled
+/// since the last sweep. Sweeps then cost O(1) per new key.
+#[derive(Debug)]
+pub(crate) struct PartitionMap<T> {
+    by_topic: HashMap<String, HashMap<u32, T>>,
+    /// Entries across every topic.
+    len: usize,
+    /// The size at which the next new key sweeps first.
+    sweep_at: usize,
+}
+
+/// No sweep below this many entries.
+const MIN_SWEEP: usize = 1024;
+
+impl<T> Default for PartitionMap<T> {
+    fn default() -> Self {
+        Self {
+            by_topic: HashMap::new(),
+            len: 0,
+            sweep_at: MIN_SWEEP,
+        }
+    }
+}
+
+impl<T> PartitionMap<T> {
+    fn get(&self, topic: &str, partition: u32) -> Option<&T> {
+        self.by_topic.get(topic)?.get(&partition)
+    }
+
+    fn get_mut(&mut self, topic: &str, partition: u32) -> Option<&mut T> {
+        self.by_topic.get_mut(topic)?.get_mut(&partition)
+    }
+
+    /// Stores `value` for `partition` of `topic`, and returns the value it replaces. A new key may
+    /// first sweep out every entry that `live` rejects.
+    fn insert(
+        &mut self,
+        topic: &str,
+        partition: u32,
+        value: T,
+        live: impl FnMut(&T) -> bool,
+    ) -> Option<T> {
+        if let Some(entry) = self.get_mut(topic, partition) {
+            return Some(std::mem::replace(entry, value));
+        }
+        if self.len >= self.sweep_at {
+            self.sweep(live);
+        }
+        match self.by_topic.get_mut(topic) {
+            Some(partitions) => {
+                partitions.insert(partition, value);
+            }
+            None => {
+                self.by_topic
+                    .insert(topic.to_owned(), HashMap::from([(partition, value)]));
+            }
+        }
+        self.len += 1;
+        None
+    }
+
+    fn sweep(&mut self, mut live: impl FnMut(&T) -> bool) {
+        self.by_topic.retain(|_, partitions| {
+            partitions.retain(|_, value| live(value));
+            !partitions.is_empty()
+        });
+        self.len = self.by_topic.values().map(HashMap::len).sum();
+        // Twice what is left, so sweeps cost O(1) per new key.
+        self.sweep_at = self.len.saturating_mul(2).max(MIN_SWEEP);
+    }
+}
+
+/// Per Kafka topic and partition, a spell of answers that found it not ready.
+pub(crate) type Spells = PartitionMap<Spell>;
+
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct Spell {
+    first: Instant,
+    last: Instant,
+}
+
+/// How long `partition` of `topic` reads as not ready, as of `now`. Zero for a new spell. A spell
+/// ends once the partition goes [`RELOAD_GRACE`] without reading so.
+fn spell(spells: &Mutex<Spells>, topic: &str, partition: u32, now: Instant) -> Duration {

Review Comment:
   one gateway-wide Spells map feeds both NotReady and OutOfRange grace. It resets only after 30s with no sightings, never on a healthy read. Another consumer can burn the grace so 1 comes at once. README.md:252 says the timer is per consumer. **Fix**: one map per cause, reset on a served read, fix the README.



-- 
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: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(gateways): answer Kafka Fetch with records from Iggy [iggy]

Posted by "codecov[bot] (via GitHub)" <gi...@apache.org>.
codecov[bot] commented on PR #4336:
URL: https://github.com/apache/iggy/pull/4336#issuecomment-5884311380

   ## [Codecov](https://app.codecov.io/gh/apache/iggy/pull/4336?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) Report
   :white_check_mark: All modified and coverable lines are covered by tests.
   :white_check_mark: Project coverage is 87.43%. Comparing base ([`917612d`](https://app.codecov.io/gh/apache/iggy/commit/917612d27d591ed019ec9bcc3050d564b03637dc?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)) to head ([`c5e8977`](https://app.codecov.io/gh/apache/iggy/commit/c5e897759b5964f2ca2dcbd677b8f53972407562?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)).
   :warning: Report is 1 commits behind head on master.
   
   <details><summary>Additional details and impacted files</summary>
   
   
   
   ```diff
   @@             Coverage Diff              @@
   ##             master    #4336      +/-   ##
   ============================================
   - Coverage     87.75%   87.43%   -0.33%     
     Complexity     1576     1576              
   ============================================
     Files          1289     1287       -2     
     Lines        227123   226875     -248     
     Branches     190575   190537      -38     
   ============================================
   - Hits         199323   198374     -949     
   - Misses        23096    23789     +693     
   - Partials       4704     4712       +8     
   ```
   
   | [Components](https://app.codecov.io/gh/apache/iggy/pull/4336/components?src=pr&el=components&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | Coverage Δ | |
   |---|---|---|
   | [Rust Core](https://app.codecov.io/gh/apache/iggy/pull/4336/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `88.86% <ø> (ø)` | |
   | [Java SDK](https://app.codecov.io/gh/apache/iggy/pull/4336/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `68.70% <ø> (ø)` | |
   | [C# SDK](https://app.codecov.io/gh/apache/iggy/pull/4336/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `77.40% <ø> (ø)` | |
   | [Python SDK](https://app.codecov.io/gh/apache/iggy/pull/4336/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `90.97% <ø> (ø)` | |
   | [PHP SDK](https://app.codecov.io/gh/apache/iggy/pull/4336/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `85.67% <ø> (ø)` | |
   | [Node SDK](https://app.codecov.io/gh/apache/iggy/pull/4336/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `90.85% <ø> (-5.71%)` | :arrow_down: |
   | [Go SDK](https://app.codecov.io/gh/apache/iggy/pull/4336/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `70.17% <ø> (ø)` | |
   [see 53 files with indirect coverage changes](https://app.codecov.io/gh/apache/iggy/pull/4336/indirect-changes?src=pr&el=tree-more&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)
   </details>
   <details><summary> :rocket: New features to boost your workflow: </summary>
   
   - :snowflake: [Test Analytics](https://docs.codecov.com/docs/test-analytics): Detect flaky tests, report on failures, and find test suite problems.
   - :package: [JS Bundle Analysis](https://docs.codecov.com/docs/javascript-bundle-analysis): Save yourself from yourself by tracking and limiting bundle sizes in JS merges.
   </details>


-- 
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: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(gateways): answer Kafka Fetch with records from Iggy [iggy]

Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on code in PR #4336:
URL: https://github.com/apache/iggy/pull/4336#discussion_r4130490800


##########
gateways/kafka/src/records.rs:
##########
@@ -968,28 +991,28 @@ pub fn encode_batch(records: &mut [Record]) -> Result<Bytes> {
     Ok(buf.freeze())
 }
 
+/// An upper bound on the bytes `record` adds to a batch [`encode_batch`] writes.
+///
+/// Fetch sums these against its byte budget before it encodes.
+#[must_use]
+pub fn record_size_bound(record: &Record) -> usize {

Review Comment:
   warning: `record_size_bound` gives a record's timestamp delta five bytes, but this crate's own decoder reads that v2 field as a varlong of up to `MAX_VARLONG_BYTES`. Count the delta as `MAX_VARLONG_BYTES` and raise `RECORD_FRAMING_BYTES` to 36, so Fetch's byte budget holds.



##########
gateways/kafka/src/bridge/iggy_bridge/fetch.rs:
##########
@@ -17,5 +17,369 @@
 
 //! Fetch-side bridge calls.
 //!
-//! Empty until the Fetch handler lands. Separate from `produce.rs` so the two never edit one
-//! file.
+//! Separate from `produce.rs` so the two never edit one file.
+
+use std::sync::{Arc, Mutex, PoisonError};
+
+use iggy::prelude::{
+    Client, Consumer, IggyClient, IggyError, MessageClient, Partition, PolledMessages,
+    PollingStrategy, TopicClient,
+};
+use tokio::sync::{OnceCell, OwnedSemaphorePermit, Semaphore};
+use tokio::time::{Instant, timeout_at};
+
+use super::offsets::high_watermark;
+use super::{IggyBridge, TopicTarget, connect_client, in_slot, with_request_timeout};
+use crate::bridge::config::IggyBridgeConfig;
+use crate::bridge::error::BridgeError;
+
+/// Fetch reads that poll at once. Each has its own Iggy client, so a poll that Iggy holds up
+/// stalls only its own slot.
+const FETCH_SLOTS: usize = 4;
+
+/// The Fetch read slots, with a client for each.
+pub(super) struct FetchPool {
+    permits: Arc<Semaphore>,
+    /// The clients of the free slots.
+    idle: Mutex<Vec<FetchClient>>,
+    /// Every slot's client, for `close`.
+    all: Vec<FetchClient>,
+}
+
+impl FetchPool {
+    pub(super) fn new() -> Self {
+        let all: Vec<FetchClient> = (0..FETCH_SLOTS).map(|_| FetchClient::default()).collect();
+        Self {
+            permits: Arc::new(Semaphore::new(FETCH_SLOTS)),
+            idle: Mutex::new(all.clone()),
+            all,
+        }
+    }
+
+    /// A free slot. `None` if none frees by `deadline`.
+    async fn take(self: &Arc<Self>, deadline: Instant) -> Option<FetchSlot> {
+        let permit = timeout_at(deadline, Arc::clone(&self.permits).acquire_owned())
+            .await
+            .ok()?
+            .ok()?;
+        let client = self
+            .idle
+            .lock()
+            .unwrap_or_else(PoisonError::into_inner)
+            .pop()?;
+        Some(FetchSlot {
+            client,
+            pool: Arc::clone(self),
+            _permit: permit,
+        })
+    }
+
+    /// Shuts down each client that connected.
+    pub(super) async fn close(&self) -> Result<(), BridgeError> {
+        for client in &self.all {
+            if let Some(client) = client.0.get() {
+                with_request_timeout(client.shutdown()).await?;

Review Comment:
   warning: `FetchPool::close` returns on the first `shutdown` error, so the later slot clients and the shared client in `IggyBridge::close` never shut down. Shut down every client, keep the first error, and return it after the loop.



##########
gateways/kafka/src/protocol/handlers/fetch.rs:
##########
@@ -97,6 +178,1087 @@ pub fn encode_response(version: i16, req: &FetchRequest) -> Result<Bytes> {
     encode_inner(version, topics, ERROR_NONE)
 }
 
+fn decode(state: &GatewayState, version: i16, body: Bytes) -> Result<FetchRequest> {
+    decode_guarded::<FetchRequest>(version, body, |v, b| {
+        validate_fetch_shape(v, b, state.max_frame_size)
+    })
+}
+
+/// Whether `request` names every partition it wants. Anything else continues a session, and
+/// this gateway opens none: it always answers `session_id` 0.
+const fn is_full(version: i16, request: &FetchRequest) -> bool {
+    version < SESSION_MIN_VERSION || matches!(request.session_epoch, INITIAL_EPOCH | FINAL_EPOCH)
+}
+
+/// Reads every requested partition once. When that finds nothing, waits for records up to
+/// `max_wait_ms` and reads again.
+///
+/// Returns the read slot too, if the read took one. Keep it until the response is encoded.
+async fn fetch(
+    bridge: &Arc<IggyBridge>,
+    state: &GatewayState,
+    request: &FetchRequest,
+) -> (Vec<FetchableTopicResponse>, Option<FetchSlot>) {
+    let started = Instant::now();
+    let give_up_at = started + REQUEST_DEADLINE;
+    let fetch = Fetch::new(bridge, state, request, give_up_at);
+    // A shared probe will do: an offset past it goes to a poll, not straight to a 1.
+    let mut probes = fetch.probe_all(recent(started)).await;
+    let (mut answers, mut slot) = fetch.read(&probes).await;
+    if waits(request, &answers) {
+        // No slot while it waits.
+        drop(slot);
+        let held: Vec<bool> = answers
+            .iter()
+            .map(|answer| retried_at_once(answer.error_code))
+            .collect();
+        let wait_until = started + fetch.max_wait;
+        probes = fetch
+            .wait(probes, &held, request.min_bytes, wait_until)
+            .await;
+        // Kafka reads again when the wait ends, too.
+        (answers, slot) = fetch.read(&probes).await;
+    }
+    (group(request, &fetch.wanted, answers), slot)
+}
+
+/// Kafka answers at once when a partition fails, when the request allows no wait, or when the
+/// records read reach `min_bytes`. Otherwise it waits.
+///
+/// A 6 or a -1 waits too. See [`retried_at_once`].
+fn waits(request: &FetchRequest, answers: &[PartitionData]) -> bool {
+    let min_bytes = usize::try_from(request.min_bytes).unwrap_or(0);
+    let record_bytes: usize = answers
+        .iter()
+        .map(|answer| answer.records.as_ref().map_or(0, Bytes::len))
+        .sum();
+    request.max_wait_ms > 0
+        && !answers.is_empty()
+        && record_bytes < min_bytes
+        && answers
+            .iter()
+            .all(|answer| answer.error_code == ERROR_NONE || retried_at_once(answer.error_code))
+}
+
+/// Codes the Java consumer fetches again at once after. Sent at once, they make it spin, so they
+/// wait out the request instead.
+const fn retried_at_once(code: i16) -> bool {
+    matches!(
+        code,
+        ERROR_NOT_LEADER_OR_FOLLOWER | ERROR_UNKNOWN_SERVER_ERROR
+    )
+}
+
+fn wait_time(max_wait_ms: i32) -> Duration {
+    Duration::from_millis(u64::try_from(max_wait_ms).unwrap_or(0)).min(MAX_WAIT)
+}
+
+/// When a -1 hold that starts at `now` ends: after the request's wait, but at least
+/// [`PROBE_INTERVAL`] on. A consumer with a short wait then reads a stuck partition at most ten
+/// times a second.
+fn hold_until(now: Instant, max_wait: Duration) -> Instant {
+    now + max_wait.max(PROBE_INTERVAL)
+}
+
+/// The topics to load a new probe for: each one whose newest probe started before `since`, the
+/// oldest first, at most [`MAX_ROUND_TOPICS`].
+fn stale_topics(snapshots: &[Option<Arc<Snapshot>>], since: Instant) -> Vec<usize> {
+    let started = |topic: usize| snapshots[topic].as_ref().map(|snapshot| snapshot.started);
+    let mut stale: Vec<usize> = (0..snapshots.len())
+        .filter(|&topic| started(topic).is_none_or(|started| started < since))
+        .collect();
+    // No probe sorts first, then the oldest, so each topic gets its turn.
+    stale.sort_by_key(|&topic| started(topic));
+    stale.truncate(MAX_ROUND_TOPICS);
+    stale
+}
+
+/// The topics wait round `turn` probes: the next [`MAX_ROUND_TOPICS`] of `count`, in turn.
+fn round(turn: usize, count: usize) -> impl Iterator<Item = usize> {
+    let start = turn.saturating_mul(MAX_ROUND_TOPICS) % count.max(1);
+    (start..start + MAX_ROUND_TOPICS.min(count)).map(move |topic| topic % count)
+}
+
+/// Waits for the next gateway write to any of the topics behind `writes`, then returns the topics
+/// written, at most [`MAX_ROUND_TOPICS`], each with the time of its write, and marks them seen.
+/// Pends while no write can come.
+async fn next_writes(writes: &mut [watch::Receiver<Option<Instant>>]) -> Vec<(usize, Instant)> {
+    let first = {
+        let mut changes: Vec<_> = writes
+            .iter_mut()
+            .map(|write| Some(Box::pin(write.changed())))
+            .collect();
+        poll_fn(|context| {
+            for (topic, slot) in changes.iter_mut().enumerate() {
+                let Some(change) = slot else { continue };
+                match change.as_mut().poll(context) {
+                    // `changed` marks this write seen.
+                    Poll::Ready(Ok(())) => return Poll::Ready(topic),
+                    // The topic left the board, so no write wakes this one.
+                    Poll::Ready(Err(_)) => *slot = None,
+                    Poll::Pending => {}
+                }
+            }
+            Poll::Pending
+        })
+        .await
+    };
+    let mut written = vec![(first, written_at(&mut writes[first]))];
+    written.extend(
+        writes
+            .iter_mut()
+            .enumerate()
+            .filter(|(topic, write)| *topic != first && write.has_changed().unwrap_or(false))
+            .take(MAX_ROUND_TOPICS - 1)
+            .map(|(topic, write)| (topic, written_at(write))),
+    );
+    written
+}
+
+/// When the newest write that `write` shows ended. Marks it seen.
+fn written_at(write: &mut watch::Receiver<Option<Instant>>) -> Instant {
+    let seen = *write.borrow_and_update();
+    seen.unwrap_or_else(Instant::now)
+}
+
+/// One request: what it asks for, and what bounds it.
+struct Fetch<'a> {
+    bridge: &'a Arc<IggyBridge>,
+    state: &'a GatewayState,
+    wanted: Vec<Wanted<'a>>,
+    /// Each topic to probe once, in request order.
+    topics: Vec<&'a str>,
+    response_bytes: usize,
+    give_up_at: Instant,
+    /// The request's wait, at most [`MAX_WAIT`].
+    max_wait: Duration,
+}
+
+impl<'a> Fetch<'a> {
+    fn new(
+        bridge: &'a Arc<IggyBridge>,
+        state: &'a GatewayState,
+        request: &'a FetchRequest,
+        give_up_at: Instant,
+    ) -> Self {
+        let (wanted, topics) = wanted(request);
+        Self {
+            bridge,
+            state,
+            wanted,
+            topics,
+            response_bytes: response_bytes(request.max_bytes, state.max_frame_size),
+            give_up_at,
+            max_wait: wait_time(request.max_wait_ms),
+        }
+    }
+
+    /// Each topic's probe, started at `since` or later.
+    ///
+    /// Loads at most [`MAX_ROUND_TOPICS`] new probes, the oldest first. Other topics keep an older
+    /// probe, or answer 6 without one. So does a topic not probed before `give_up_at`.
+    async fn probe_all(&self, since: Instant) -> Probes {
+        let board = &self.state.probe_board;
+        let mut snapshots: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.newest(topic))
+            .collect();
+        for topic in stale_topics(&snapshots, since) {
+            snapshots[topic] = self
+                .probe_topic(self.topics[topic], since, self.give_up_at)
+                .await;
+        }
+        snapshots
+            .into_iter()
+            .map(|snapshot| {
+                snapshot.map_or(Err(ERROR_NOT_LEADER_OR_FOLLOWER), |snapshot| {
+                    snapshot.probe.clone()
+                })
+            })
+            .collect()
+    }
+
+    /// `topic`'s probe from the board, started at `since` or later. `None` if none comes by
+    /// `deadline`.
+    async fn probe_topic(
+        &self,
+        topic: &str,
+        since: Instant,
+        deadline: Instant,
+    ) -> Option<Arc<Snapshot>> {
+        let load = || {
+            let (bridge, name) = (Arc::clone(self.bridge), topic.to_owned());
+            async move {
+                let probe = bridge.probe(&name).await;
+                probe.map(Arc::new).map_err(|error| refusal(&name, &error))
+            }
+        };
+        self.state
+            .probe_board
+            .probe(topic, since, deadline, load)
+            .await
+    }
+
+    /// The probe of partition `index` of `topic`, started at `since` or later.
+    async fn probe_partition(
+        &self,
+        topic: &str,
+        index: u32,
+        since: Instant,
+    ) -> Option<PartitionProbe> {
+        let snapshot = self.probe_topic(topic, since, self.give_up_at).await?;
+        snapshot.probe.as_ref().ok()?.get(index)
+    }
+
+    /// Probes until the bytes waiting reach `min_bytes`, a partition fails, or `wait_until`
+    /// passes. Holds no slot while it waits.
+    ///
+    /// Each [`PROBE_INTERVAL`], a round probes the next [`MAX_ROUND_TOPICS`] topics. A gateway
+    /// write to a topic probes it at once. A topic not probed keeps its last probe.
+    ///
+    /// `held` marks partitions that answered 6 or -1. They wait it out and end no wait.
+    async fn wait(
+        &self,
+        mut probes: Probes,
+        held: &[bool],
+        min_bytes: i32,
+        wait_until: Instant,
+    ) -> Probes {
+        if held.iter().all(|&held| held) {
+            sleep_until(wait_until).await;
+            return self.probe_all(recent(Instant::now())).await;
+        }
+        let min_bytes = u64::try_from(min_bytes).unwrap_or(0);
+        let board = &self.state.probe_board;
+        let mut writes: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.writes(topic))
+            .collect();
+        let mut turn = 0;
+        // Kept across write wakes, so steady writes to one topic do not stop the rounds.
+        let mut round_at = (Instant::now() + PROBE_INTERVAL).min(wait_until);
+        while Instant::now() < wait_until {
+            let written = tokio::select! {
+                () = sleep_until(round_at) => None,
+                written = next_writes(&mut writes) => Some(written),
+            };
+            let timed = written.is_none();
+            // A write needs a probe that started after it. A round needs one newer than the last.
+            let due = written.unwrap_or_else(|| {
+                turn += 1;
+                let since = recent(Instant::now());
+                round(turn - 1, self.topics.len())
+                    .map(|topic| (topic, since))
+                    .collect()
+            });
+            for (topic, since) in due {
+                // A probe late for the round still lands on the board for the next Fetch.
+                let probe = self.probe_topic(self.topics[topic], since, wait_until);
+                if let Some(snapshot) = probe.await {
+                    probes[topic].clone_from(&snapshot.probe);
+                }
+            }
+            if timed {
+                round_at = (Instant::now() + PROBE_INTERVAL).min(wait_until);
+            }
+            if ready(&self.wanted, held, &probes, self.response_bytes, min_bytes) {
+                break;
+            }
+        }
+        probes
+    }
+
+    /// One answer per requested partition, in request order, and the read slot, if taken.
+    async fn read(&self, probes: &Probes) -> (Vec<PartitionData>, Option<FetchSlot>) {
+        Reader::new(self).read_all(probes).await
+    }
+}
+
+/// One requested partition.
+struct Wanted<'a> {
+    /// Its topic entry in the request.
+    entry: usize,
+    topic: &'a str,
+    partition: i32,
+    fetch_offset: i64,
+    max_bytes: usize,
+    /// Where its probe is, or the code it answers without asking Iggy.
+    probe_at: core::result::Result<ProbeAt, i16>,
+}
+
+/// Where a partition's probe is.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct ProbeAt {
+    /// Its topic's place in `Fetch::topics`.
+    topic: usize,
+    index: u32,
+}
+
+/// Each requested partition once, in request order, and each topic to probe once. A repeat
+/// keeps the first entry.
+///
+/// The Java consumer drops a whole response that leaves out a partition it asked for.
+fn wanted(request: &FetchRequest) -> (Vec<Wanted<'_>>, Vec<&str>) {
+    let total = request
+        .topics
+        .iter()
+        .map(|topic| topic.partitions.len())
+        .sum();
+    let mut seen = HashSet::with_capacity(total);
+    let mut wanted = Vec::with_capacity(total);
+    let mut topics = IndexSet::new();
+    for (entry, topic) in request.topics.iter().enumerate() {
+        let name = topic.topic.as_str();
+        // A name Kafka refuses answers 3 here, so it never takes a place on the probe board.
+        let named = validate_kafka_topic_name("kafka_topic", name)
+            .map_err(|_| ERROR_UNKNOWN_TOPIC_OR_PARTITION);
+        for partition in &topic.partitions {
+            if !seen.insert((name, partition.partition)) {
+                continue;
+            }
+            let probe_at = named
+                .and_then(|()| {
+                    u32::try_from(partition.partition).map_err(|_| ERROR_UNKNOWN_TOPIC_OR_PARTITION)
+                })
+                .map(|index| ProbeAt {
+                    topic: topics.insert_full(name).0,
+                    index,
+                });
+            wanted.push(Wanted {
+                entry,
+                topic: name,
+                partition: partition.partition,
+                fetch_offset: partition.fetch_offset,
+                max_bytes: usize::try_from(partition.partition_max_bytes).unwrap_or(0),
+                probe_at,
+            });
+        }
+    }
+    (wanted, topics.into_iter().collect())
+}
+
+/// Record bytes the whole response may carry: `max_bytes`, at most one frame.
+fn response_bytes(max_bytes: i32, max_frame_size: usize) -> usize {
+    usize::try_from(max_bytes).unwrap_or(0).min(max_frame_size)
+}
+
+/// Per topic in `Fetch::topics`, its probe, or one code for the whole topic.
+type Probes = Vec<TopicProbed>;
+
+/// Whether a partition now fails, as an error ends Kafka's wait too, or the bytes waiting reach
+/// `min_bytes`. Skips `held` partitions.
+fn ready(
+    wanted: &[Wanted<'_>],
+    held: &[bool],
+    probes: &Probes,
+    response_bytes: usize,
+    min_bytes: u64,
+) -> bool {
+    let mut waiting = 0u64;
+    for (want, _) in wanted.iter().zip(held).filter(|&(_, &held)| !held) {
+        match position(want, probes) {
+            Position::Refused(_) => return true,
+            // Past the end of this probe, or no message kept. A newer probe, or the read after
+            // the wait, decides.
+            Position::CaughtUp(_) | Position::Unsure { .. } => {}
+            Position::Behind { offset, probe, .. } => {
+                let budget = want.max_bytes.min(response_bytes);
+                waiting = waiting.saturating_add(bytes_waiting(offset, probe, budget));
+            }
+        }
+    }
+    waiting >= min_bytes
+}
+
+/// Estimated bytes past `offset`, at most `budget`. Kafka's delayed fetch counts the same way.
+fn bytes_waiting(offset: u64, probe: PartitionProbe, budget: usize) -> u64 {
+    probe
+        .high_watermark
+        .saturating_sub(offset)
+        .saturating_mul(probe.average_size)
+        .min(u64::try_from(budget).unwrap_or(u64::MAX))
+}
+
+/// Where a requested offset stands against the probe.
+#[derive(Debug, PartialEq, Eq)]
+enum Position {
+    /// Answer this code, with no records.
+    Refused(i16),
+    /// At the high watermark. Answer 0, with no records.
+    CaughtUp(PartitionProbe),
+    /// Records wait in partition `index` from `offset` on.
+    Behind {
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    },
+    /// The probe cannot place `offset`. One poll decides.
+    Unsure {
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    },
+}
+
+fn position(want: &Wanted<'_>, probes: &Probes) -> Position {
+    let at = match want.probe_at {
+        Ok(at) => at,
+        Err(code) => return Position::Refused(code),
+    };
+    // `Fetch::probe_all` probes every topic in `Fetch::topics`, in order.
+    let probe = match &probes[at.topic] {
+        Ok(topic) => match topic.get(at.index) {
+            Some(probe) => probe,
+            None => return Position::Refused(ERROR_UNKNOWN_TOPIC_OR_PARTITION),
+        },
+        Err(code) => return Position::Refused(*code),
+    };
+    if probe.is_loading() {
+        return Position::Refused(ERROR_NOT_LEADER_OR_FOLLOWER);
+    }
+    // Below the oldest retained offset is in range: Iggy reads from the first retained message,
+    // and Kafka consumers accept the gap.
+    match u64::try_from(want.fetch_offset) {
+        Ok(offset) if offset == probe.high_watermark => Position::CaughtUp(probe),
+        // Retention can remove every message, and a server with no stats reads the same. Past
+        // the end, a shared probe can predate records the consumer already read.
+        Ok(offset) if probe.messages_count == 0 || offset > probe.high_watermark => {
+            Position::Unsure {
+                index: at.index,
+                offset,
+                probe,
+            }
+        }
+        Ok(offset) => Position::Behind {
+            index: at.index,
+            offset,
+            probe,
+        },
+        Err(_) => Position::Refused(ERROR_OFFSET_OUT_OF_RANGE),
+    }
+}
+
+/// Reads partitions in request order, as Kafka does from v3, and spends one byte budget on them.
+struct Reader<'a> {
+    fetch: &'a Fetch<'a>,
+    bytes_left: usize,
+    /// No partition has answered with records yet, so the next one returns at least one, whatever
+    /// the limits say (KIP-74). A record larger than every limit would stall the consumer
+    /// otherwise.
+    owes_first_record: bool,
+    /// Taken at the first poll. A poll given up on keeps it until the poll ends.
+    slot: Option<FetchSlot>,
+}
+
+impl<'a> Reader<'a> {
+    const fn new(fetch: &'a Fetch<'a>) -> Self {
+        Self {
+            fetch,
+            bytes_left: fetch.response_bytes,
+            owes_first_record: true,
+            slot: None,
+        }
+    }
+
+    /// One answer per requested partition, in request order, and the slot, if taken.
+    async fn read_all(mut self, probes: &Probes) -> (Vec<PartitionData>, Option<FetchSlot>) {
+        let fetch = self.fetch;
+        let mut answers = Vec::with_capacity(fetch.wanted.len());
+        for want in &fetch.wanted {
+            let answer = match position(want, probes) {
+                Position::Refused(code) => refused(want.partition, code),
+                Position::CaughtUp(probe) => {
+                    served(want.partition, probe.high_watermark, Bytes::new())
+                }
+                Position::Behind { index, offset, .. } | Position::Unsure { index, offset, .. }
+                    if held(
+                        &fetch.state.stuck_offsets,
+                        want.topic,
+                        index,
+                        offset,
+                        Instant::now(),
+                    ) =>
+                {
+                    refused(want.partition, ERROR_UNKNOWN_SERVER_ERROR)
+                }
+                Position::Behind {
+                    index,
+                    offset,
+                    probe,
+                } => {
+                    let polled = Polled::new(offset, probe.high_watermark);
+                    self.read(want, index, offset, probe, polled).await
+                }
+                Position::Unsure {
+                    index,
+                    offset,
+                    probe,
+                } => self.settle(want, index, offset, probe).await,
+            };
+            answers.push(answer);
+        }
+        (answers, self.slot)
+    }
+
+    /// Polls one partition that has records waiting, and answers with what its budget holds.
+    async fn read(
+        &mut self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+        mut polled: Polled,
+    ) -> PartitionData {
+        let budget = want.max_bytes.min(self.bytes_left);
+        // Unless a record is owed, skip a poll that likely brings back nothing that fits.
+        let average = usize::try_from(probe.average_size).unwrap_or(usize::MAX);
+        if self.owes_first_record || budget >= average.max(1) {
+            while let Some(count) = next_page(&polled, budget, probe.average_size) {
+                let asked = Instant::now();
+                let Some(page) = self.poll(want.topic, index, polled.next, count).await else {
+                    break;
+                };
+                match page {
+                    // The probe showed records, yet the first poll found none.
+                    Ok(page) if page.messages.is_empty() && polled.messages.is_empty() => {
+                        return self
+                            .after_empty_poll(want, index, offset, probe, asked)
+                            .await;
+                    }
+                    Ok(page) => polled.add(page, count),
+                    Err(error) if polled.messages.is_empty() => {
+                        return self.refuse(want, index, offset, &error);
+                    }
+                    // Serve what the earlier polls brought.
+                    Err(_) => break,
+                }
+            }
+        }
+
+        let keep_one = self.owes_first_record;
+        let encoded = off_worker(polled.bytes >= CODEC_OFF_WORKER_BYTES, || {
+            encode_records(&polled.messages, offset, budget, keep_one)
+        });
+        match encoded {
+            Ok(batch) => {
+                self.bytes_left = self.bytes_left.saturating_sub(batch.len());
+                self.owes_first_record &= batch.is_empty();
+                served(want.partition, polled.high_watermark, batch)
+            }
+            Err(error) => {
+                let until = hold_until(Instant::now(), self.fetch.max_wait);
+                let stuck = &self.fetch.state.stuck_offsets;
+                let first = hold(stuck, want.topic, index, offset, until);
+                log_stuck(first, want.topic, index, offset, &error);
+                refused(want.partition, ERROR_UNKNOWN_SERVER_ERROR)
+            }
+        }
+    }
+
+    /// Reads a partition the probe cannot place, with a poll at `offset`.
+    ///
+    /// - Records: serve them. The probe missed them.
+    /// - Nothing, and Iggy's commit ends just before `offset`: caught up.
+    /// - Nothing else: a probe taken after the poll decides. See [`empty_poll`].
+    async fn settle(
+        &mut self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    ) -> PartitionData {
+        // Sized as a read's first page, since an empty answer costs the same round trip.
+        let budget = want.max_bytes.min(self.bytes_left);
+        let count = poll_count(budget, probe.average_size, u64::from(MAX_PAGE_COUNT));
+        let asked = Instant::now();
+        match self.poll(want.topic, index, offset, count).await {
+            // Never below the offset, or the consumer reports negative lag.
+            None => served(
+                want.partition,
+                probe.high_watermark.max(offset),
+                Bytes::new(),
+            ),
+            Some(Err(error)) => self.refuse(want, index, offset, &error),
+            Some(Ok(page)) if !page.messages.is_empty() => {
+                let mut polled = Polled::new(offset, probe.high_watermark);
+                polled.add(page, count);
+                self.read(want, index, offset, probe, polled).await
+            }
+            Some(Ok(page)) if caught_up(offset, page.current_offset) => {
+                served(want.partition, offset, Bytes::new())
+            }
+            Some(Ok(_)) => {
+                self.after_empty_poll(want, index, offset, probe, asked)
+                    .await
+            }
+        }
+    }
+
+    /// Answers an empty poll at `offset`, made at `asked`, from `before` and a probe taken after
+    /// it. See [`empty_poll`].
+    async fn after_empty_poll(
+        &self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        before: PartitionProbe,
+        asked: Instant,
+    ) -> PartitionData {
+        let after = self.fetch.probe_partition(want.topic, index, asked).await;
+        match empty_poll(offset, before, after) {
+            EmptyPoll::OutOfRange { high_watermark } => {
+                // No offset past 0: maybe a partition that Iggy loads or fences.
+                let not_ready = &self.fetch.state.not_ready;
+                let loading = high_watermark <= 1
+                    && spell(not_ready, want.topic, index, Instant::now()) < RELOAD_GRACE;
+                let code = if loading {
+                    ERROR_NOT_LEADER_OR_FOLLOWER
+                } else {
+                    ERROR_OFFSET_OUT_OF_RANGE
+                };
+                refused(want.partition, code)
+            }
+            EmptyPoll::NotReady => {
+                let spell = spell(
+                    &self.fetch.state.not_ready,
+                    want.topic,
+                    index,
+                    Instant::now(),
+                );
+                log_not_ready(spell.is_zero(), want.topic, index, offset);
+                refused(want.partition, ERROR_NOT_LEADER_OR_FOLLOWER)
+            }
+            EmptyPoll::Unproven => {
+                let high_watermark =
+                    after.map_or(before.high_watermark, |after| after.high_watermark);
+                served(want.partition, high_watermark.max(offset), Bytes::new())
+            }
+        }
+    }
+
+    /// The code for `error`. A -1 also holds the partition, so reads skip Iggy until the hold ends.
+    fn refuse(
+        &self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        error: &BridgeError,
+    ) -> PartitionData {
+        let code = refusal(want.topic, error);
+        if code == ERROR_UNKNOWN_SERVER_ERROR {
+            let until = hold_until(Instant::now(), self.fetch.max_wait);
+            hold(
+                &self.fetch.state.stuck_offsets,
+                want.topic,
+                index,
+                offset,
+                until,
+            );
+        }
+        refused(want.partition, code)
+    }
+
+    /// Polls one page, in the read slot. `None` once `give_up_at` passes.
+    async fn poll(
+        &mut self,
+        topic: &str,
+        index: u32,
+        offset: u64,
+        count: u32,
+    ) -> Option<core::result::Result<PolledMessages, BridgeError>> {
+        let give_up_at = self.fetch.give_up_at;
+        if Instant::now() >= give_up_at {
+            return None;
+        }
+        let bridge = self.fetch.bridge;
+        let (page, slot) = bridge
+            .poll(
+                self.take_slot().await?,
+                topic,
+                index,
+                offset,
+                count,
+                give_up_at,
+            )
+            .await?;
+        self.slot = Some(slot);
+        Some(page)
+    }
+
+    /// The read slot, taken at the first poll. `None` once `give_up_at` passes.
+    async fn take_slot(&mut self) -> Option<FetchSlot> {
+        match self.slot.take() {
+            Some(slot) => Some(slot),
+            None => self.fetch.bridge.fetch_slot(self.fetch.give_up_at).await,
+        }
+    }
+}
+
+/// Whether an empty poll at `offset` proves the consumer is at the end: Iggy's commit counter,
+/// `current_offset`, ends just before it. A 0 proves nothing, since an empty partition and a failed
+/// read send 0 too.
+const fn caught_up(offset: u64, current_offset: u64) -> bool {
+    current_offset > 0 && current_offset.saturating_add(1) == offset
+}
+
+/// What an empty poll proves.
+#[derive(Debug, PartialEq, Eq)]
+enum EmptyPoll {
+    /// The offset is past `high_watermark`, the end after the poll.
+    OutOfRange { high_watermark: u64 },
+    /// Records remain, yet the poll found none: a read fault, or a partition Iggy loads. Retry.
+    NotReady,
+    /// Nothing. Serve no records, and the consumer asks again.
+    Unproven,
+}
+
+/// Decides an empty poll at `offset` from the probe before it and one taken after it.
+///
+/// Iggy also answers empty on a read fault, so only `after` proves anything. No message kept below
+/// the end proves no gap: a cluster replica reads so after a crash or a failed install, while its
+/// peers keep the records. So the consumer waits for the next write instead of moving past them.
+const fn empty_poll(
+    offset: u64,
+    before: PartitionProbe,
+    after: Option<PartitionProbe>,
+) -> EmptyPoll {
+    let Some(after) = after else {
+        return EmptyPoll::Unproven;
+    };
+    if after.is_loading() {
+        EmptyPoll::NotReady
+    } else if offset > after.high_watermark {
+        EmptyPoll::OutOfRange {
+            high_watermark: after.high_watermark,
+        }
+    } else if after.messages_count > 0
+        && offset < before.high_watermark
+        && offset < after.high_watermark
+    {
+        EmptyPoll::NotReady
+    } else {
+        EmptyPoll::Unproven
+    }
+}
+
+/// Per Kafka topic and partition, a spell of answers that found it not ready.
+#[derive(Debug, Default)]
+pub(crate) struct Spells {
+    by_partition: HashMap<(String, u32), Spell>,
+    /// The size at which the next new spell sweeps first.
+    sweep_at: usize,
+}
+
+/// No sweep below this many spells.
+const MIN_SPELL_SWEEP: usize = 1024;
+
+#[derive(Debug, Clone, Copy)]
+struct Spell {
+    first: Instant,
+    last: Instant,
+}
+
+/// How long `partition` of `topic` reads as not ready, as of `now`. Zero for a new spell. A spell
+/// ends once the partition goes [`RELOAD_GRACE`] without reading so.
+fn spell(spells: &Mutex<Spells>, topic: &str, partition: u32, now: Instant) -> Duration {
+    let key = (topic.to_owned(), partition);
+    let mut spells = spells.lock().unwrap_or_else(PoisonError::into_inner);
+    if !spells.by_partition.contains_key(&key) && spells.by_partition.len() >= spells.sweep_at {
+        spells
+            .by_partition
+            .retain(|_, spell| now.saturating_duration_since(spell.last) < RELOAD_GRACE);
+        // Twice what is left, so sweeps cost O(1) per new spell.
+        spells.sweep_at = spells
+            .by_partition
+            .len()
+            .saturating_mul(2)
+            .max(MIN_SPELL_SWEEP);
+    }
+    let spell = spells.by_partition.entry(key).or_insert(Spell {
+        first: now,
+        last: now,
+    });
+    if now.saturating_duration_since(spell.last) >= RELOAD_GRACE {
+        spell.first = now;
+    }
+    spell.last = now;
+    let first = spell.first;
+    drop(spells);
+    now.saturating_duration_since(first)
+}
+
+/// Logs a partition whose records Iggy did not return: `warn!` when a spell starts, `debug!` while
+/// it lasts.
+fn log_not_ready(first: bool, topic: &str, partition: u32, offset: u64) {
+    if first {
+        tracing::warn!(
+            kafka_topic = topic,
+            partition,
+            fetch_offset = offset,
+            "Fetch found no records where Iggy reports some"
+        );
+    } else {
+        tracing::debug!(
+            kafka_topic = topic,
+            partition,
+            fetch_offset = offset,
+            "Fetch still finds no records where Iggy reports some"
+        );
+    }
+}
+
+/// Per Kafka topic, then partition, where a partition last answered -1.
+pub(crate) type StuckOffsets = Mutex<HashMap<String, HashMap<u32, Stuck>>>;

Review Comment:
   warning: `hold()` keeps an entry for every topic and partition that answers -1, and nothing removes one when the hold expires. Drop an expired entry in `held()`, or sweep on insert the way `spell()` does.



##########
gateways/kafka/src/bridge/mod.rs:
##########
@@ -28,5 +28,8 @@ pub mod topic_map;
 
 pub use config::{DEFAULT_MAX_MESSAGE_SIZE, IggyBridgeConfig};
 pub use error::BridgeError;
-pub use iggy_bridge::{IggyBridge, KafkaTopicMetadata, TopicCreationOutcome, TopicTarget};
+pub use iggy_bridge::{
+    FetchSlot, IggyBridge, KafkaTopicMetadata, PartitionProbe, TopicCreationOutcome, TopicProbe,

Review Comment:
   simplification: The new `FetchSlot`, `PartitionProbe` and `TopicProbe` re-exports, the `IggyBridge::{fetch_slot, poll}` methods and `records::{BATCH_HEADER_BYTES, record_size_bound}` are public, but nothing outside the crate names them. Make them `pub(crate)` and drop the re-exports.



##########
gateways/kafka/src/protocol/handlers/fetch.rs:
##########
@@ -97,6 +178,1087 @@ pub fn encode_response(version: i16, req: &FetchRequest) -> Result<Bytes> {
     encode_inner(version, topics, ERROR_NONE)
 }
 
+fn decode(state: &GatewayState, version: i16, body: Bytes) -> Result<FetchRequest> {
+    decode_guarded::<FetchRequest>(version, body, |v, b| {
+        validate_fetch_shape(v, b, state.max_frame_size)
+    })
+}
+
+/// Whether `request` names every partition it wants. Anything else continues a session, and
+/// this gateway opens none: it always answers `session_id` 0.
+const fn is_full(version: i16, request: &FetchRequest) -> bool {
+    version < SESSION_MIN_VERSION || matches!(request.session_epoch, INITIAL_EPOCH | FINAL_EPOCH)
+}
+
+/// Reads every requested partition once. When that finds nothing, waits for records up to
+/// `max_wait_ms` and reads again.
+///
+/// Returns the read slot too, if the read took one. Keep it until the response is encoded.
+async fn fetch(
+    bridge: &Arc<IggyBridge>,
+    state: &GatewayState,
+    request: &FetchRequest,
+) -> (Vec<FetchableTopicResponse>, Option<FetchSlot>) {
+    let started = Instant::now();
+    let give_up_at = started + REQUEST_DEADLINE;
+    let fetch = Fetch::new(bridge, state, request, give_up_at);
+    // A shared probe will do: an offset past it goes to a poll, not straight to a 1.
+    let mut probes = fetch.probe_all(recent(started)).await;
+    let (mut answers, mut slot) = fetch.read(&probes).await;
+    if waits(request, &answers) {
+        // No slot while it waits.
+        drop(slot);
+        let held: Vec<bool> = answers
+            .iter()
+            .map(|answer| retried_at_once(answer.error_code))
+            .collect();
+        let wait_until = started + fetch.max_wait;
+        probes = fetch
+            .wait(probes, &held, request.min_bytes, wait_until)
+            .await;
+        // Kafka reads again when the wait ends, too.
+        (answers, slot) = fetch.read(&probes).await;
+    }
+    (group(request, &fetch.wanted, answers), slot)
+}
+
+/// Kafka answers at once when a partition fails, when the request allows no wait, or when the
+/// records read reach `min_bytes`. Otherwise it waits.
+///
+/// A 6 or a -1 waits too. See [`retried_at_once`].
+fn waits(request: &FetchRequest, answers: &[PartitionData]) -> bool {
+    let min_bytes = usize::try_from(request.min_bytes).unwrap_or(0);
+    let record_bytes: usize = answers
+        .iter()
+        .map(|answer| answer.records.as_ref().map_or(0, Bytes::len))
+        .sum();
+    request.max_wait_ms > 0
+        && !answers.is_empty()
+        && record_bytes < min_bytes
+        && answers
+            .iter()
+            .all(|answer| answer.error_code == ERROR_NONE || retried_at_once(answer.error_code))
+}
+
+/// Codes the Java consumer fetches again at once after. Sent at once, they make it spin, so they
+/// wait out the request instead.
+const fn retried_at_once(code: i16) -> bool {
+    matches!(
+        code,
+        ERROR_NOT_LEADER_OR_FOLLOWER | ERROR_UNKNOWN_SERVER_ERROR
+    )
+}
+
+fn wait_time(max_wait_ms: i32) -> Duration {
+    Duration::from_millis(u64::try_from(max_wait_ms).unwrap_or(0)).min(MAX_WAIT)
+}
+
+/// When a -1 hold that starts at `now` ends: after the request's wait, but at least
+/// [`PROBE_INTERVAL`] on. A consumer with a short wait then reads a stuck partition at most ten
+/// times a second.
+fn hold_until(now: Instant, max_wait: Duration) -> Instant {
+    now + max_wait.max(PROBE_INTERVAL)
+}
+
+/// The topics to load a new probe for: each one whose newest probe started before `since`, the
+/// oldest first, at most [`MAX_ROUND_TOPICS`].
+fn stale_topics(snapshots: &[Option<Arc<Snapshot>>], since: Instant) -> Vec<usize> {
+    let started = |topic: usize| snapshots[topic].as_ref().map(|snapshot| snapshot.started);
+    let mut stale: Vec<usize> = (0..snapshots.len())
+        .filter(|&topic| started(topic).is_none_or(|started| started < since))
+        .collect();
+    // No probe sorts first, then the oldest, so each topic gets its turn.
+    stale.sort_by_key(|&topic| started(topic));
+    stale.truncate(MAX_ROUND_TOPICS);
+    stale
+}
+
+/// The topics wait round `turn` probes: the next [`MAX_ROUND_TOPICS`] of `count`, in turn.
+fn round(turn: usize, count: usize) -> impl Iterator<Item = usize> {
+    let start = turn.saturating_mul(MAX_ROUND_TOPICS) % count.max(1);
+    (start..start + MAX_ROUND_TOPICS.min(count)).map(move |topic| topic % count)
+}
+
+/// Waits for the next gateway write to any of the topics behind `writes`, then returns the topics
+/// written, at most [`MAX_ROUND_TOPICS`], each with the time of its write, and marks them seen.
+/// Pends while no write can come.
+async fn next_writes(writes: &mut [watch::Receiver<Option<Instant>>]) -> Vec<(usize, Instant)> {
+    let first = {
+        let mut changes: Vec<_> = writes
+            .iter_mut()
+            .map(|write| Some(Box::pin(write.changed())))
+            .collect();
+        poll_fn(|context| {
+            for (topic, slot) in changes.iter_mut().enumerate() {
+                let Some(change) = slot else { continue };
+                match change.as_mut().poll(context) {
+                    // `changed` marks this write seen.
+                    Poll::Ready(Ok(())) => return Poll::Ready(topic),
+                    // The topic left the board, so no write wakes this one.
+                    Poll::Ready(Err(_)) => *slot = None,
+                    Poll::Pending => {}
+                }
+            }
+            Poll::Pending
+        })
+        .await
+    };
+    let mut written = vec![(first, written_at(&mut writes[first]))];
+    written.extend(
+        writes
+            .iter_mut()
+            .enumerate()
+            .filter(|(topic, write)| *topic != first && write.has_changed().unwrap_or(false))
+            .take(MAX_ROUND_TOPICS - 1)
+            .map(|(topic, write)| (topic, written_at(write))),
+    );
+    written
+}
+
+/// When the newest write that `write` shows ended. Marks it seen.
+fn written_at(write: &mut watch::Receiver<Option<Instant>>) -> Instant {
+    let seen = *write.borrow_and_update();
+    seen.unwrap_or_else(Instant::now)
+}
+
+/// One request: what it asks for, and what bounds it.
+struct Fetch<'a> {
+    bridge: &'a Arc<IggyBridge>,
+    state: &'a GatewayState,
+    wanted: Vec<Wanted<'a>>,
+    /// Each topic to probe once, in request order.
+    topics: Vec<&'a str>,
+    response_bytes: usize,
+    give_up_at: Instant,
+    /// The request's wait, at most [`MAX_WAIT`].
+    max_wait: Duration,
+}
+
+impl<'a> Fetch<'a> {
+    fn new(
+        bridge: &'a Arc<IggyBridge>,
+        state: &'a GatewayState,
+        request: &'a FetchRequest,
+        give_up_at: Instant,
+    ) -> Self {
+        let (wanted, topics) = wanted(request);
+        Self {
+            bridge,
+            state,
+            wanted,
+            topics,
+            response_bytes: response_bytes(request.max_bytes, state.max_frame_size),
+            give_up_at,
+            max_wait: wait_time(request.max_wait_ms),
+        }
+    }
+
+    /// Each topic's probe, started at `since` or later.
+    ///
+    /// Loads at most [`MAX_ROUND_TOPICS`] new probes, the oldest first. Other topics keep an older
+    /// probe, or answer 6 without one. So does a topic not probed before `give_up_at`.
+    async fn probe_all(&self, since: Instant) -> Probes {
+        let board = &self.state.probe_board;
+        let mut snapshots: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.newest(topic))
+            .collect();
+        for topic in stale_topics(&snapshots, since) {
+            snapshots[topic] = self
+                .probe_topic(self.topics[topic], since, self.give_up_at)
+                .await;
+        }
+        snapshots
+            .into_iter()
+            .map(|snapshot| {
+                snapshot.map_or(Err(ERROR_NOT_LEADER_OR_FOLLOWER), |snapshot| {
+                    snapshot.probe.clone()
+                })
+            })
+            .collect()
+    }
+
+    /// `topic`'s probe from the board, started at `since` or later. `None` if none comes by
+    /// `deadline`.
+    async fn probe_topic(
+        &self,
+        topic: &str,
+        since: Instant,
+        deadline: Instant,
+    ) -> Option<Arc<Snapshot>> {
+        let load = || {
+            let (bridge, name) = (Arc::clone(self.bridge), topic.to_owned());
+            async move {
+                let probe = bridge.probe(&name).await;
+                probe.map(Arc::new).map_err(|error| refusal(&name, &error))
+            }
+        };
+        self.state
+            .probe_board
+            .probe(topic, since, deadline, load)
+            .await
+    }
+
+    /// The probe of partition `index` of `topic`, started at `since` or later.
+    async fn probe_partition(
+        &self,
+        topic: &str,
+        index: u32,
+        since: Instant,
+    ) -> Option<PartitionProbe> {
+        let snapshot = self.probe_topic(topic, since, self.give_up_at).await?;
+        snapshot.probe.as_ref().ok()?.get(index)
+    }
+
+    /// Probes until the bytes waiting reach `min_bytes`, a partition fails, or `wait_until`
+    /// passes. Holds no slot while it waits.
+    ///
+    /// Each [`PROBE_INTERVAL`], a round probes the next [`MAX_ROUND_TOPICS`] topics. A gateway
+    /// write to a topic probes it at once. A topic not probed keeps its last probe.
+    ///
+    /// `held` marks partitions that answered 6 or -1. They wait it out and end no wait.
+    async fn wait(
+        &self,
+        mut probes: Probes,
+        held: &[bool],
+        min_bytes: i32,
+        wait_until: Instant,
+    ) -> Probes {
+        if held.iter().all(|&held| held) {
+            sleep_until(wait_until).await;
+            return self.probe_all(recent(Instant::now())).await;
+        }
+        let min_bytes = u64::try_from(min_bytes).unwrap_or(0);
+        let board = &self.state.probe_board;
+        let mut writes: Vec<_> = self
+            .topics
+            .iter()
+            .map(|&topic| board.writes(topic))
+            .collect();
+        let mut turn = 0;
+        // Kept across write wakes, so steady writes to one topic do not stop the rounds.
+        let mut round_at = (Instant::now() + PROBE_INTERVAL).min(wait_until);
+        while Instant::now() < wait_until {
+            let written = tokio::select! {
+                () = sleep_until(round_at) => None,
+                written = next_writes(&mut writes) => Some(written),
+            };
+            let timed = written.is_none();
+            // A write needs a probe that started after it. A round needs one newer than the last.
+            let due = written.unwrap_or_else(|| {
+                turn += 1;
+                let since = recent(Instant::now());
+                round(turn - 1, self.topics.len())
+                    .map(|topic| (topic, since))
+                    .collect()
+            });
+            for (topic, since) in due {
+                // A probe late for the round still lands on the board for the next Fetch.
+                let probe = self.probe_topic(self.topics[topic], since, wait_until);
+                if let Some(snapshot) = probe.await {
+                    probes[topic].clone_from(&snapshot.probe);
+                }
+            }
+            if timed {
+                round_at = (Instant::now() + PROBE_INTERVAL).min(wait_until);
+            }
+            if ready(&self.wanted, held, &probes, self.response_bytes, min_bytes) {
+                break;
+            }
+        }
+        probes
+    }
+
+    /// One answer per requested partition, in request order, and the read slot, if taken.
+    async fn read(&self, probes: &Probes) -> (Vec<PartitionData>, Option<FetchSlot>) {
+        Reader::new(self).read_all(probes).await
+    }
+}
+
+/// One requested partition.
+struct Wanted<'a> {
+    /// Its topic entry in the request.
+    entry: usize,
+    topic: &'a str,
+    partition: i32,
+    fetch_offset: i64,
+    max_bytes: usize,
+    /// Where its probe is, or the code it answers without asking Iggy.
+    probe_at: core::result::Result<ProbeAt, i16>,
+}
+
+/// Where a partition's probe is.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct ProbeAt {
+    /// Its topic's place in `Fetch::topics`.
+    topic: usize,
+    index: u32,
+}
+
+/// Each requested partition once, in request order, and each topic to probe once. A repeat
+/// keeps the first entry.
+///
+/// The Java consumer drops a whole response that leaves out a partition it asked for.
+fn wanted(request: &FetchRequest) -> (Vec<Wanted<'_>>, Vec<&str>) {
+    let total = request
+        .topics
+        .iter()
+        .map(|topic| topic.partitions.len())
+        .sum();
+    let mut seen = HashSet::with_capacity(total);
+    let mut wanted = Vec::with_capacity(total);
+    let mut topics = IndexSet::new();
+    for (entry, topic) in request.topics.iter().enumerate() {
+        let name = topic.topic.as_str();
+        // A name Kafka refuses answers 3 here, so it never takes a place on the probe board.
+        let named = validate_kafka_topic_name("kafka_topic", name)
+            .map_err(|_| ERROR_UNKNOWN_TOPIC_OR_PARTITION);
+        for partition in &topic.partitions {
+            if !seen.insert((name, partition.partition)) {
+                continue;
+            }
+            let probe_at = named
+                .and_then(|()| {
+                    u32::try_from(partition.partition).map_err(|_| ERROR_UNKNOWN_TOPIC_OR_PARTITION)
+                })
+                .map(|index| ProbeAt {
+                    topic: topics.insert_full(name).0,
+                    index,
+                });
+            wanted.push(Wanted {
+                entry,
+                topic: name,
+                partition: partition.partition,
+                fetch_offset: partition.fetch_offset,
+                max_bytes: usize::try_from(partition.partition_max_bytes).unwrap_or(0),
+                probe_at,
+            });
+        }
+    }
+    (wanted, topics.into_iter().collect())
+}
+
+/// Record bytes the whole response may carry: `max_bytes`, at most one frame.
+fn response_bytes(max_bytes: i32, max_frame_size: usize) -> usize {
+    usize::try_from(max_bytes).unwrap_or(0).min(max_frame_size)
+}
+
+/// Per topic in `Fetch::topics`, its probe, or one code for the whole topic.
+type Probes = Vec<TopicProbed>;
+
+/// Whether a partition now fails, as an error ends Kafka's wait too, or the bytes waiting reach
+/// `min_bytes`. Skips `held` partitions.
+fn ready(
+    wanted: &[Wanted<'_>],
+    held: &[bool],
+    probes: &Probes,
+    response_bytes: usize,
+    min_bytes: u64,
+) -> bool {
+    let mut waiting = 0u64;
+    for (want, _) in wanted.iter().zip(held).filter(|&(_, &held)| !held) {
+        match position(want, probes) {
+            Position::Refused(_) => return true,
+            // Past the end of this probe, or no message kept. A newer probe, or the read after
+            // the wait, decides.
+            Position::CaughtUp(_) | Position::Unsure { .. } => {}
+            Position::Behind { offset, probe, .. } => {
+                let budget = want.max_bytes.min(response_bytes);
+                waiting = waiting.saturating_add(bytes_waiting(offset, probe, budget));
+            }
+        }
+    }
+    waiting >= min_bytes
+}
+
+/// Estimated bytes past `offset`, at most `budget`. Kafka's delayed fetch counts the same way.
+fn bytes_waiting(offset: u64, probe: PartitionProbe, budget: usize) -> u64 {
+    probe
+        .high_watermark
+        .saturating_sub(offset)
+        .saturating_mul(probe.average_size)
+        .min(u64::try_from(budget).unwrap_or(u64::MAX))
+}
+
+/// Where a requested offset stands against the probe.
+#[derive(Debug, PartialEq, Eq)]
+enum Position {
+    /// Answer this code, with no records.
+    Refused(i16),
+    /// At the high watermark. Answer 0, with no records.
+    CaughtUp(PartitionProbe),
+    /// Records wait in partition `index` from `offset` on.
+    Behind {
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    },
+    /// The probe cannot place `offset`. One poll decides.
+    Unsure {
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    },
+}
+
+fn position(want: &Wanted<'_>, probes: &Probes) -> Position {
+    let at = match want.probe_at {
+        Ok(at) => at,
+        Err(code) => return Position::Refused(code),
+    };
+    // `Fetch::probe_all` probes every topic in `Fetch::topics`, in order.
+    let probe = match &probes[at.topic] {
+        Ok(topic) => match topic.get(at.index) {
+            Some(probe) => probe,
+            None => return Position::Refused(ERROR_UNKNOWN_TOPIC_OR_PARTITION),
+        },
+        Err(code) => return Position::Refused(*code),
+    };
+    if probe.is_loading() {
+        return Position::Refused(ERROR_NOT_LEADER_OR_FOLLOWER);
+    }
+    // Below the oldest retained offset is in range: Iggy reads from the first retained message,
+    // and Kafka consumers accept the gap.
+    match u64::try_from(want.fetch_offset) {
+        Ok(offset) if offset == probe.high_watermark => Position::CaughtUp(probe),
+        // Retention can remove every message, and a server with no stats reads the same. Past
+        // the end, a shared probe can predate records the consumer already read.
+        Ok(offset) if probe.messages_count == 0 || offset > probe.high_watermark => {
+            Position::Unsure {
+                index: at.index,
+                offset,
+                probe,
+            }
+        }
+        Ok(offset) => Position::Behind {
+            index: at.index,
+            offset,
+            probe,
+        },
+        Err(_) => Position::Refused(ERROR_OFFSET_OUT_OF_RANGE),
+    }
+}
+
+/// Reads partitions in request order, as Kafka does from v3, and spends one byte budget on them.
+struct Reader<'a> {
+    fetch: &'a Fetch<'a>,
+    bytes_left: usize,
+    /// No partition has answered with records yet, so the next one returns at least one, whatever
+    /// the limits say (KIP-74). A record larger than every limit would stall the consumer
+    /// otherwise.
+    owes_first_record: bool,
+    /// Taken at the first poll. A poll given up on keeps it until the poll ends.
+    slot: Option<FetchSlot>,
+}
+
+impl<'a> Reader<'a> {
+    const fn new(fetch: &'a Fetch<'a>) -> Self {
+        Self {
+            fetch,
+            bytes_left: fetch.response_bytes,
+            owes_first_record: true,
+            slot: None,
+        }
+    }
+
+    /// One answer per requested partition, in request order, and the slot, if taken.
+    async fn read_all(mut self, probes: &Probes) -> (Vec<PartitionData>, Option<FetchSlot>) {
+        let fetch = self.fetch;
+        let mut answers = Vec::with_capacity(fetch.wanted.len());
+        for want in &fetch.wanted {
+            let answer = match position(want, probes) {
+                Position::Refused(code) => refused(want.partition, code),
+                Position::CaughtUp(probe) => {
+                    served(want.partition, probe.high_watermark, Bytes::new())
+                }
+                Position::Behind { index, offset, .. } | Position::Unsure { index, offset, .. }
+                    if held(
+                        &fetch.state.stuck_offsets,
+                        want.topic,
+                        index,
+                        offset,
+                        Instant::now(),
+                    ) =>
+                {
+                    refused(want.partition, ERROR_UNKNOWN_SERVER_ERROR)
+                }
+                Position::Behind {
+                    index,
+                    offset,
+                    probe,
+                } => {
+                    let polled = Polled::new(offset, probe.high_watermark);
+                    self.read(want, index, offset, probe, polled).await
+                }
+                Position::Unsure {
+                    index,
+                    offset,
+                    probe,
+                } => self.settle(want, index, offset, probe).await,
+            };
+            answers.push(answer);
+        }
+        (answers, self.slot)
+    }
+
+    /// Polls one partition that has records waiting, and answers with what its budget holds.
+    async fn read(
+        &mut self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+        mut polled: Polled,
+    ) -> PartitionData {
+        let budget = want.max_bytes.min(self.bytes_left);
+        // Unless a record is owed, skip a poll that likely brings back nothing that fits.
+        let average = usize::try_from(probe.average_size).unwrap_or(usize::MAX);
+        if self.owes_first_record || budget >= average.max(1) {
+            while let Some(count) = next_page(&polled, budget, probe.average_size) {
+                let asked = Instant::now();
+                let Some(page) = self.poll(want.topic, index, polled.next, count).await else {
+                    break;
+                };
+                match page {
+                    // The probe showed records, yet the first poll found none.
+                    Ok(page) if page.messages.is_empty() && polled.messages.is_empty() => {
+                        return self
+                            .after_empty_poll(want, index, offset, probe, asked)
+                            .await;
+                    }
+                    Ok(page) => polled.add(page, count),
+                    Err(error) if polled.messages.is_empty() => {
+                        return self.refuse(want, index, offset, &error);
+                    }
+                    // Serve what the earlier polls brought.
+                    Err(_) => break,
+                }
+            }
+        }
+
+        let keep_one = self.owes_first_record;
+        let encoded = off_worker(polled.bytes >= CODEC_OFF_WORKER_BYTES, || {
+            encode_records(&polled.messages, offset, budget, keep_one)
+        });
+        match encoded {
+            Ok(batch) => {
+                self.bytes_left = self.bytes_left.saturating_sub(batch.len());
+                self.owes_first_record &= batch.is_empty();
+                served(want.partition, polled.high_watermark, batch)
+            }
+            Err(error) => {
+                let until = hold_until(Instant::now(), self.fetch.max_wait);
+                let stuck = &self.fetch.state.stuck_offsets;
+                let first = hold(stuck, want.topic, index, offset, until);
+                log_stuck(first, want.topic, index, offset, &error);
+                refused(want.partition, ERROR_UNKNOWN_SERVER_ERROR)
+            }
+        }
+    }
+
+    /// Reads a partition the probe cannot place, with a poll at `offset`.
+    ///
+    /// - Records: serve them. The probe missed them.
+    /// - Nothing, and Iggy's commit ends just before `offset`: caught up.
+    /// - Nothing else: a probe taken after the poll decides. See [`empty_poll`].
+    async fn settle(
+        &mut self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        probe: PartitionProbe,
+    ) -> PartitionData {
+        // Sized as a read's first page, since an empty answer costs the same round trip.
+        let budget = want.max_bytes.min(self.bytes_left);
+        let count = poll_count(budget, probe.average_size, u64::from(MAX_PAGE_COUNT));
+        let asked = Instant::now();
+        match self.poll(want.topic, index, offset, count).await {
+            // Never below the offset, or the consumer reports negative lag.
+            None => served(
+                want.partition,
+                probe.high_watermark.max(offset),
+                Bytes::new(),
+            ),
+            Some(Err(error)) => self.refuse(want, index, offset, &error),
+            Some(Ok(page)) if !page.messages.is_empty() => {
+                let mut polled = Polled::new(offset, probe.high_watermark);
+                polled.add(page, count);
+                self.read(want, index, offset, probe, polled).await
+            }
+            Some(Ok(page)) if caught_up(offset, page.current_offset) => {
+                served(want.partition, offset, Bytes::new())
+            }
+            Some(Ok(_)) => {
+                self.after_empty_poll(want, index, offset, probe, asked)
+                    .await
+            }
+        }
+    }
+
+    /// Answers an empty poll at `offset`, made at `asked`, from `before` and a probe taken after
+    /// it. See [`empty_poll`].
+    async fn after_empty_poll(
+        &self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        before: PartitionProbe,
+        asked: Instant,
+    ) -> PartitionData {
+        let after = self.fetch.probe_partition(want.topic, index, asked).await;
+        match empty_poll(offset, before, after) {
+            EmptyPoll::OutOfRange { high_watermark } => {
+                // No offset past 0: maybe a partition that Iggy loads or fences.
+                let not_ready = &self.fetch.state.not_ready;
+                let loading = high_watermark <= 1
+                    && spell(not_ready, want.topic, index, Instant::now()) < RELOAD_GRACE;
+                let code = if loading {
+                    ERROR_NOT_LEADER_OR_FOLLOWER
+                } else {
+                    ERROR_OFFSET_OUT_OF_RANGE
+                };
+                refused(want.partition, code)
+            }
+            EmptyPoll::NotReady => {
+                let spell = spell(
+                    &self.fetch.state.not_ready,
+                    want.topic,
+                    index,
+                    Instant::now(),
+                );
+                log_not_ready(spell.is_zero(), want.topic, index, offset);
+                refused(want.partition, ERROR_NOT_LEADER_OR_FOLLOWER)
+            }
+            EmptyPoll::Unproven => {
+                let high_watermark =
+                    after.map_or(before.high_watermark, |after| after.high_watermark);
+                served(want.partition, high_watermark.max(offset), Bytes::new())
+            }
+        }
+    }
+
+    /// The code for `error`. A -1 also holds the partition, so reads skip Iggy until the hold ends.
+    fn refuse(
+        &self,
+        want: &Wanted<'_>,
+        index: u32,
+        offset: u64,
+        error: &BridgeError,
+    ) -> PartitionData {
+        let code = refusal(want.topic, error);
+        if code == ERROR_UNKNOWN_SERVER_ERROR {
+            let until = hold_until(Instant::now(), self.fetch.max_wait);
+            hold(
+                &self.fetch.state.stuck_offsets,
+                want.topic,
+                index,
+                offset,
+                until,
+            );
+        }
+        refused(want.partition, code)
+    }
+
+    /// Polls one page, in the read slot. `None` once `give_up_at` passes.
+    async fn poll(
+        &mut self,
+        topic: &str,
+        index: u32,
+        offset: u64,
+        count: u32,
+    ) -> Option<core::result::Result<PolledMessages, BridgeError>> {
+        let give_up_at = self.fetch.give_up_at;
+        if Instant::now() >= give_up_at {
+            return None;
+        }
+        let bridge = self.fetch.bridge;
+        let (page, slot) = bridge
+            .poll(
+                self.take_slot().await?,
+                topic,
+                index,
+                offset,
+                count,
+                give_up_at,
+            )
+            .await?;
+        self.slot = Some(slot);
+        Some(page)
+    }
+
+    /// The read slot, taken at the first poll. `None` once `give_up_at` passes.
+    async fn take_slot(&mut self) -> Option<FetchSlot> {
+        match self.slot.take() {
+            Some(slot) => Some(slot),
+            None => self.fetch.bridge.fetch_slot(self.fetch.give_up_at).await,
+        }
+    }
+}
+
+/// Whether an empty poll at `offset` proves the consumer is at the end: Iggy's commit counter,
+/// `current_offset`, ends just before it. A 0 proves nothing, since an empty partition and a failed
+/// read send 0 too.
+const fn caught_up(offset: u64, current_offset: u64) -> bool {
+    current_offset > 0 && current_offset.saturating_add(1) == offset
+}
+
+/// What an empty poll proves.
+#[derive(Debug, PartialEq, Eq)]
+enum EmptyPoll {
+    /// The offset is past `high_watermark`, the end after the poll.
+    OutOfRange { high_watermark: u64 },
+    /// Records remain, yet the poll found none: a read fault, or a partition Iggy loads. Retry.
+    NotReady,
+    /// Nothing. Serve no records, and the consumer asks again.
+    Unproven,
+}
+
+/// Decides an empty poll at `offset` from the probe before it and one taken after it.
+///
+/// Iggy also answers empty on a read fault, so only `after` proves anything. No message kept below
+/// the end proves no gap: a cluster replica reads so after a crash or a failed install, while its
+/// peers keep the records. So the consumer waits for the next write instead of moving past them.
+const fn empty_poll(
+    offset: u64,
+    before: PartitionProbe,
+    after: Option<PartitionProbe>,
+) -> EmptyPoll {
+    let Some(after) = after else {
+        return EmptyPoll::Unproven;
+    };
+    if after.is_loading() {
+        EmptyPoll::NotReady
+    } else if offset > after.high_watermark {
+        EmptyPoll::OutOfRange {
+            high_watermark: after.high_watermark,
+        }
+    } else if after.messages_count > 0
+        && offset < before.high_watermark
+        && offset < after.high_watermark
+    {
+        EmptyPoll::NotReady
+    } else {
+        EmptyPoll::Unproven
+    }
+}
+
+/// Per Kafka topic and partition, a spell of answers that found it not ready.
+#[derive(Debug, Default)]
+pub(crate) struct Spells {
+    by_partition: HashMap<(String, u32), Spell>,
+    /// The size at which the next new spell sweeps first.
+    sweep_at: usize,
+}
+
+/// No sweep below this many spells.
+const MIN_SPELL_SWEEP: usize = 1024;
+
+#[derive(Debug, Clone, Copy)]
+struct Spell {
+    first: Instant,
+    last: Instant,
+}
+
+/// How long `partition` of `topic` reads as not ready, as of `now`. Zero for a new spell. A spell
+/// ends once the partition goes [`RELOAD_GRACE`] without reading so.
+fn spell(spells: &Mutex<Spells>, topic: &str, partition: u32, now: Instant) -> Duration {
+    let key = (topic.to_owned(), partition);

Review Comment:
   simplification: `spell()` builds a `String` key on every call, even on a hit. Key the outer map by topic and the inner map by partition, as `StuckOffsets` does, so only an insert allocates.



-- 
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: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(gateways): answer Kafka Fetch with records from Iggy [iggy]

Posted by "hubcio (via GitHub)" <gi...@apache.org>.
hubcio commented on PR #4336:
URL: https://github.com/apache/iggy/pull/4336#issuecomment-5885069574

   /skill team-review-slim


-- 
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: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] feat(gateways): answer Kafka Fetch with records from Iggy [iggy]

Posted by "ryerraguntla (via GitHub)" <gi...@apache.org>.
ryerraguntla commented on PR #4336:
URL: https://github.com/apache/iggy/pull/4336#issuecomment-5902221770

   /author
   


-- 
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: commits-unsubscribe@iggy.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org