kafka-client-engine 0.0.1

Execution and driver-integration layer for the native Kafka client
Documentation
//! Sole bounded state owner for group Fetch activation and later execution.

use std::{collections::VecDeque, time::Duration};

use kafka_client_core::{
    AssignedConsumerEffect, AssignedConsumerMachine, GroupPositionFence,
    GroupPositionMissingOffsetPolicy, ReadIsolation,
};

use crate::{
    consumer::{
        assigned_event::AssignedConsumerEventStore,
        assigned_owner_model::{PendingPosition, RawPositionDeadline},
        assigned_timers::AssignedTimers,
        fetch_execution::{DirectFetchExecutor, PreparedFetchExecution},
        position_execution::PositionResolutionExecutor,
    },
    protocol::{
        consumer::CLASSIC_SYNC_MAX_MEMBER_PARTITIONS,
        fetch::{FetchDecodeLimits, FetchRequestSettings},
    },
};

use super::{
    super::classic_group_position::{
        ClassicGroupPositionCompleted, prepare_classic_group_fetch_activation,
    },
    activation::{
        ClassicGroupFetchActivation, ClassicGroupFetchActivationError,
        ClassicGroupFetchActivationFailure, ClassicGroupFetchActivationFault,
        ClassicGroupFetchBinding, ClassicGroupFetchPostCoreFaultKind,
    },
    delivery::ClassicGroupFetchReclaimFault,
    model::{ClassicGroupFetchOwnerFault, ClassicGroupFetchPreflightError},
    seek::ClassicGroupFetchSeek,
};

/// First private slice mirrors the direct consumer's current partition bound.
pub(super) const FIRST_GROUP_FETCH_PARTITIONS: usize = CLASSIC_SYNC_MAX_MEMBER_PARTITIONS;
/// First private slice reserves replacement revokes, starts, and one close effect.
pub(super) const FIRST_GROUP_FETCH_EFFECTS: usize = FIRST_GROUP_FETCH_PARTITIONS * 2 + 1;
/// Default group Fetch-call capacity mirrors the assigned consumer.
pub(super) const FIRST_GROUP_FETCH_CALLS: usize = 8;
/// Default group delivery capacity mirrors the assigned consumer.
pub(super) const FIRST_GROUP_FETCH_DELIVERIES: usize = 8;
/// Default group delivery-byte capacity mirrors the assigned consumer.
pub(super) const FIRST_GROUP_FETCH_DELIVERY_BYTES: usize = 8 * 1024 * 1024;
/// First private slice mirrors the direct consumer's one-MiB per-Fetch output bound.
pub(super) const FIRST_GROUP_FETCH_OUTPUT_BYTES: usize = 1024 * 1024;

/// One group-specific deterministic Fetch policy owner.
pub(in crate::consumer::group) struct ClassicGroupFetchOwner {
    pub(super) machine: AssignedConsumerMachine,
    pub(super) activation: Option<ClassicGroupFetchActivation>,
    pub(super) timers: AssignedTimers,
    pub(super) positions: PositionResolutionExecutor,
    pub(super) fetches: DirectFetchExecutor,
    pub(super) events: AssignedConsumerEventStore,
    pub(super) effects: VecDeque<AssignedConsumerEffect>,
    pub(super) raw_position_deadlines: VecDeque<RawPositionDeadline>,
    pub(super) pending_positions: VecDeque<PendingPosition>,
    pub(super) pending_fetches: VecDeque<PreparedFetchExecution>,
    pub(super) fetch_settings: FetchRequestSettings,
    pub(super) fetch_decode_limits: FetchDecodeLimits,
    pub(super) fetch_attempt_timeout: Duration,
    pub(super) missing_offset_policy: GroupPositionMissingOffsetPolicy,
    pub(super) read_isolation: ReadIsolation,
    pub(super) partition_capacity: usize,
    pub(super) effect_capacity: usize,
    pub(super) delivery_capacity: usize,
    pub(super) hard_fetch_output_bytes: usize,
    pub(super) fault: Option<ClassicGroupFetchOwnerFault>,
    pub(super) seek: Option<ClassicGroupFetchSeek>,
    pub(super) reclaim_faults: Vec<ClassicGroupFetchReclaimFault>,
    pub(super) reclaim_overflow: Option<ClassicGroupFetchReclaimFault>,
}

impl ClassicGroupFetchOwner {
    #[expect(
        clippy::result_large_err,
        reason = "the internal lossless boundary returns the exact completed position without hidden boxing"
    )]
    pub(in crate::consumer::group) fn try_activate(
        &mut self,
        completed: ClassicGroupPositionCompleted,
        current_fence: GroupPositionFence,
    ) -> Result<(), ClassicGroupFetchActivationError> {
        if self.activation.is_some() || self.is_faulted() {
            return Err(ClassicGroupFetchActivationError::Returned(
                ClassicGroupFetchActivationFailure::already_active(completed),
            ));
        }
        let input = match prepare_classic_group_fetch_activation(&completed, current_fence) {
            Ok(input) => input,
            Err(error) => {
                return Err(ClassicGroupFetchActivationError::Returned(
                    ClassicGroupFetchActivationFailure::position(completed, error),
                ));
            }
        };
        let partition_count = input.partitions().len();
        if let Err(error) = self.preflight_activation_capacity(partition_count) {
            return Err(ClassicGroupFetchActivationError::Returned(
                ClassicGroupFetchActivationFailure::preflight(completed, input, error),
            ));
        }
        let event_claims = match self.events.prepare_replacement(partition_count) {
            Ok(claims) => claims,
            Err(error) => {
                return Err(ClassicGroupFetchActivationError::Returned(
                    ClassicGroupFetchActivationFailure::preflight(
                        completed,
                        input,
                        ClassicGroupFetchPreflightError::Event(error),
                    ),
                ));
            }
        };
        let transition = match self.machine.install_resolved_assignment(input) {
            Ok(transition) => transition,
            Err(error) => {
                event_claims.rollback_event_claims();
                return Err(ClassicGroupFetchActivationError::Returned(
                    ClassicGroupFetchActivationFailure::core(completed, error),
                ));
            }
        };
        let Some(assignment_epoch) = transition.assignment_epoch() else {
            let kind = ClassicGroupFetchPostCoreFaultKind::MissingAssignmentEpoch;
            event_claims.rollback_event_claims();
            self.fault = Some(ClassicGroupFetchOwnerFault::Activation(
                ClassicGroupFetchActivationFault::new(completed, transition, kind),
            ));
            return Err(ClassicGroupFetchActivationError::Retained(kind));
        };
        let effect_count = transition.effects().len();
        let effect_limit = self.effect_capacity.saturating_sub(self.effects.len());
        if effect_count > effect_limit {
            let kind = ClassicGroupFetchPostCoreFaultKind::EffectCapacity {
                actual: effect_count,
                limit: effect_limit,
            };
            event_claims.rollback_event_claims();
            self.fault = Some(ClassicGroupFetchOwnerFault::Activation(
                ClassicGroupFetchActivationFault::new(completed, transition, kind),
            ));
            return Err(ClassicGroupFetchActivationError::Retained(kind));
        }
        if let Err(error) = event_claims.commit_event_claims(transition.effects()) {
            let kind = ClassicGroupFetchPostCoreFaultKind::Event(error);
            self.fault = Some(ClassicGroupFetchOwnerFault::Activation(
                ClassicGroupFetchActivationFault::new(completed, transition, kind),
            ));
            return Err(ClassicGroupFetchActivationError::Retained(kind));
        }
        let binding = ClassicGroupFetchBinding::new(completed.fence(), assignment_epoch);
        for effect in transition.into_effects() {
            self.effects.push_back(effect);
        }
        self.activation = Some(ClassicGroupFetchActivation::new(binding));
        self.fetches.resume_broker_session_maintenance();
        Ok(())
    }

    fn preflight_activation_capacity(
        &self,
        partition_count: usize,
    ) -> Result<(), ClassicGroupFetchPreflightError> {
        let effects = self.effects.len().saturating_add(partition_count);
        if effects > self.effect_capacity {
            return Err(ClassicGroupFetchPreflightError::EffectCapacity {
                actual: effects,
                limit: self.effect_capacity,
            });
        }
        let prepared = self.pending_fetches.len().saturating_add(partition_count);
        if prepared > self.partition_capacity {
            return Err(ClassicGroupFetchPreflightError::PreparedCapacity {
                actual: prepared,
                limit: self.partition_capacity,
            });
        }
        Ok(())
    }
    /// Reports authorized bytes that must remain observable before cooperative fencing.
    pub(in crate::consumer::group) fn has_ready_delivery(&self) -> bool {
        self.fetches.has_ready_delivery()
    }
}