kafka-client-engine 0.0.1

Execution and driver-integration layer for the native Kafka client
Documentation
//! Registry mutation for raw Fetch handoff, confirmation, restoration, and recovery.

use kafka_client_core::FetchFence;

#[cfg(test)]
use bytes::Bytes;

use super::{
    calls::TrackedFetchCalls,
    settlement::{
        FetchBeginSettlementError, FetchConfirmationError, FetchRestoreError, FetchRestoreFailure,
        PendingFetchConfirmation, StaleFetchConfirmationError,
    },
    stale::FetchRecovery,
    terminal::FetchTerminal,
};

#[cfg(test)]
use super::settlement::SettledFetchCall;

impl TrackedFetchCalls {
    pub(crate) fn begin_fetch_settlement(
        &mut self,
        supplied: FetchFence,
    ) -> Result<FetchTerminal, FetchBeginSettlementError> {
        if let Some(pending) = &self.pending_confirmation {
            return Err(FetchBeginSettlementError::ConfirmationPending {
                pending: pending.fence(),
            });
        }
        let Some(settled) = self.settled.as_ref() else {
            return Err(FetchBeginSettlementError::NoSettledCall { supplied });
        };
        if settled.fence() != supplied {
            return Err(FetchBeginSettlementError::FenceMismatch {
                settled: settled.fence(),
                supplied,
            });
        }
        if settled.is_stale() {
            return Err(FetchBeginSettlementError::StaleSettledCall { supplied });
        }
        let Some(settled) = self.settled.take() else {
            return Err(FetchBeginSettlementError::NoSettledCall { supplied });
        };
        match settled.into_live_parts() {
            Ok((terminal, route_token)) => {
                self.pending_confirmation =
                    Some(PendingFetchConfirmation::new(supplied, route_token));
                Ok(terminal)
            }
            Err(settled) => {
                self.settled = Some(settled);
                Err(FetchBeginSettlementError::StaleSettledCall { supplied })
            }
        }
    }

    pub(crate) fn confirm_fetch_settlement(
        &mut self,
        supplied: FetchFence,
    ) -> Result<(), FetchConfirmationError> {
        let Some(pending) = self.pending_confirmation.as_ref() else {
            return Err(FetchConfirmationError::NoPendingConfirmation { supplied });
        };
        if pending.fence() != supplied {
            return Err(FetchConfirmationError::FenceMismatch {
                pending: pending.fence(),
                supplied,
            });
        }
        self.pending_confirmation = None;
        Ok(())
    }

    #[allow(
        clippy::result_large_err,
        reason = "failed restoration must return the exact raw terminal without allocation"
    )]
    pub(crate) fn restore_fetch_settlement(
        &mut self,
        terminal: FetchTerminal,
    ) -> Result<(), FetchRestoreFailure> {
        let supplied = terminal.fence();
        if self.settled.is_some() {
            return Err(FetchRestoreFailure::new(
                terminal,
                FetchRestoreError::SettledCallPresent { supplied },
            ));
        }
        let Some(pending) = self.pending_confirmation.as_ref() else {
            return Err(FetchRestoreFailure::new(
                terminal,
                FetchRestoreError::NoPendingConfirmation { supplied },
            ));
        };
        if pending.fence() != supplied {
            return Err(FetchRestoreFailure::new(
                terminal,
                FetchRestoreError::FenceMismatch {
                    pending: pending.fence(),
                    supplied,
                },
            ));
        }
        let Some(pending) = self.pending_confirmation.take() else {
            return Err(FetchRestoreFailure::new(
                terminal,
                FetchRestoreError::NoPendingConfirmation { supplied },
            ));
        };
        self.settled = Some(pending.into_settled(terminal));
        Ok(())
    }

    pub(crate) fn confirm_stale_fetch(
        &mut self,
        supplied: FetchFence,
    ) -> Result<(), StaleFetchConfirmationError> {
        let Some(settled) = self.settled.as_ref() else {
            return Err(StaleFetchConfirmationError::NoSettledCall { supplied });
        };
        if settled.fence() != supplied {
            return Err(StaleFetchConfirmationError::FenceMismatch {
                settled: settled.fence(),
                supplied,
            });
        }
        if !settled.is_stale() {
            return Err(StaleFetchConfirmationError::LiveSettledCall { supplied });
        }
        self.settled = None;
        Ok(())
    }

    pub(crate) fn recover_fetches_after_driver_shutdown(&mut self) -> FetchRecovery {
        let mut requests = self
            .calls
            .iter_mut()
            .filter_map(|call| call.request.take())
            .collect::<Vec<_>>();
        self.calls.clear();
        if let Some(settled) = self.settled.take() {
            requests.extend(settled.into_request());
        }
        self.pending_confirmation = None;
        let completion_failure = self.completion_failure.take().map(|failure| {
            let (request, observation) = failure.into_parts();
            requests.extend(request);
            observation
        });
        FetchRecovery::new(requests, completion_failure)
    }

    #[cfg(test)]
    pub(crate) fn install_terminal_for_test(&mut self, terminal: FetchTerminal) {
        self.settled = Some(SettledFetchCall::live(terminal, None));
    }

    #[cfg(test)]
    #[expect(
        clippy::too_many_arguments,
        reason = "the test helper exposes every exact generated Fetch terminal field to focused scenarios"
    )]
    pub(crate) fn install_success_terminal_for_test(
        &mut self,
        request: super::admission::PartitionFetchRequest,
        observed_at: kafka_client_core::Moment,
        selected_version: i16,
        session_id: i32,
        partition_index: Option<i32>,
        records: Option<Bytes>,
        partition_error_code: i16,
    ) {
        let mut response = kafka_wire::FetchResponse::default();
        response.session_id = session_id;
        if let Some(partition_index) = partition_index {
            let mut partition = kafka_wire::fetch_response::PartitionData::default();
            partition.partition_index = partition_index;
            partition.error_code = partition_error_code;
            partition.records = records;
            let mut topic = kafka_wire::fetch_response::FetchableTopicResponse::default();
            topic.topic = request.topic().into();
            topic.partitions = vec![partition];
            response.responses = vec![topic];
        }
        self.install_terminal_result_for_test(
            request,
            observed_at,
            Some(selected_version),
            Ok(response),
        );
    }

    #[cfg(test)]
    pub(crate) fn install_broker_terminal_for_test(
        &mut self,
        request: super::admission::PartitionFetchRequest,
        observed_at: kafka_client_core::Moment,
        selected_version: i16,
        code: i16,
    ) {
        let mut response = kafka_wire::FetchResponse::default();
        response.error_code = code;
        self.install_terminal_result_for_test(
            request,
            observed_at,
            Some(selected_version),
            Ok(response),
        );
    }

    #[cfg(test)]
    pub(crate) fn install_route_unavailable_terminal_for_test(
        &mut self,
        request: super::admission::PartitionFetchRequest,
        observed_at: kafka_client_core::Moment,
    ) {
        self.install_terminal_result_for_test(
            request,
            observed_at,
            None,
            Err(kafka_driver::RequestError::RouteUnavailable),
        );
    }

    #[cfg(test)]
    fn install_terminal_result_for_test(
        &mut self,
        request: super::admission::PartitionFetchRequest,
        observed_at: kafka_client_core::Moment,
        selected_version: Option<i16>,
        result: Result<kafka_wire::FetchResponse, kafka_driver::RequestError>,
    ) {
        let terminal = super::terminal::retain_fetch_terminal(
            request,
            observed_at,
            selected_version.map(kafka_driver::ApiVersion::new),
            result,
        );
        self.settled = Some(SettledFetchCall::live(terminal, None));
    }
}