kafka-client-engine 0.0.1

Execution and driver-integration layer for the native Kafka client
Documentation
//! Atomic assignment revocation and recovery installation after Heartbeat rejection.

use kafka_client_core::{
    ClassicCoordinatorRecovery, ClassicGeneration, ClassicGroupEffect, ClassicGroupFatal,
    ClassicGroupPhase, ClassicRejoinSchedule, LiveGroupAssignment, Moment,
};

use super::{
    classic_group_assignment::ClassicGroupRevocationFailureKind,
    classic_group_heartbeat_prepare::commit_revoke,
    classic_group_rejection_fault::{ClassicRejectionInstallFailure, ClassicRejectionPostCore},
    registry_entry::GroupConsumerEntry,
    registry_graceful_revocation::stage_classic_group_revocation,
};

#[expect(
    clippy::result_large_err,
    reason = "the error retains exact post-core effects without allocating or erasing recovery state"
)]
pub(super) fn install_rejoin(
    entry: &mut GroupConsumerEntry,
    assignment: LiveGroupAssignment,
    generation: ClassicGeneration,
    schedule: ClassicRejoinSchedule,
    now: Moment,
) -> Result<(), ClassicRejectionPostCore> {
    if !waiting_state_matches(entry, schedule) {
        return Err(post_rejoin(assignment, generation, schedule, MachineState));
    }
    let prepared_rejoin = match entry.rejoin.prepare_rejoin_install(schedule) {
        Ok(prepared) => prepared,
        Err(_error) => {
            return Err(post_rejoin(assignment, generation, schedule, RejoinState));
        }
    };
    if let Err((error, assignment)) = stage_classic_group_revocation(
        &mut entry.catalog,
        &entry.fetch,
        &mut entry.revocation,
        assignment,
        generation,
        schedule.due(),
        now,
    ) {
        drop(prepared_rejoin);
        return Err(post_rejoin(
            assignment,
            generation,
            schedule,
            GracefulRevocation(error),
        ));
    }
    prepared_rejoin.commit();
    Ok(())
}

#[expect(
    clippy::result_large_err,
    reason = "the error retains exact post-core effects without allocating or erasing recovery state"
)]
pub(super) fn install_rediscovery(
    entry: &mut GroupConsumerEntry,
    assignment: LiveGroupAssignment,
    generation: ClassicGeneration,
    schedule: ClassicRejoinSchedule,
    now: Moment,
) -> Result<(), ClassicRejectionPostCore> {
    if !waiting_state_matches(entry, schedule) {
        return Err(post_rediscovery(
            assignment,
            generation,
            schedule,
            MachineState,
        ));
    }
    let prepared_rediscovery = match entry.rediscovery.prepare_rediscovery_install() {
        Ok(prepared) => prepared,
        Err(_error) => {
            return Err(post_rediscovery(
                assignment,
                generation,
                schedule,
                RediscoveryState,
            ));
        }
    };
    let prepared_rejoin = match entry.rejoin.prepare_rejoin_install(schedule) {
        Ok(prepared) => prepared,
        Err(_error) => {
            return Err(post_rediscovery(
                assignment,
                generation,
                schedule,
                RejoinState,
            ));
        }
    };
    if let Err((error, assignment)) = stage_classic_group_revocation(
        &mut entry.catalog,
        &entry.fetch,
        &mut entry.revocation,
        assignment,
        generation,
        schedule.due(),
        now,
    ) {
        drop(prepared_rejoin);
        drop(prepared_rediscovery);
        return Err(post_rediscovery(
            assignment,
            generation,
            schedule,
            GracefulRevocation(error),
        ));
    }
    prepared_rejoin.commit();
    prepared_rediscovery.commit();
    Ok(())
}

#[expect(
    clippy::result_large_err,
    reason = "the error retains exact post-core effects without allocating or erasing recovery state"
)]
pub(super) fn install_fatal(
    entry: &mut GroupConsumerEntry,
    assignment: LiveGroupAssignment,
    generation: ClassicGeneration,
    fatal: ClassicGroupFatal,
) -> Result<(), ClassicRejectionPostCore> {
    if !fatal_state_matches(entry, fatal) {
        return Err(post_fatal(assignment, generation, fatal, MachineState));
    }
    match commit_revoke(entry, assignment, generation) {
        Ok(()) => Ok(()),
        Err(failure) => {
            let kind = rejection_revocation_kind(failure.kind);
            Err(post_fatal(
                failure.assignment,
                failure.classic_generation,
                fatal,
                kind,
            ))
        }
    }
}

const fn rejection_revocation_kind(
    kind: ClassicGroupRevocationFailureKind,
) -> ClassicRejectionInstallFailure {
    match kind {
        ClassicGroupRevocationFailureKind::Catalog(kind) => Assignment(kind),
        ClassicGroupRevocationFailureKind::ProcessingLeaseCycleUnavailable => {
            ProcessingLeaseCycleUnavailable
        }
        ClassicGroupRevocationFailureKind::ProcessingLease(error) => ProcessingLease(error),
        ClassicGroupRevocationFailureKind::Fetch(error) => FetchRetirement(error),
    }
}

fn waiting_state_matches(entry: &GroupConsumerEntry, schedule: ClassicRejoinSchedule) -> bool {
    entry.classic.machine().phase() == ClassicGroupPhase::WaitingToRejoin
        && entry.classic.machine().pending_rejoin() == Some(schedule)
        && entry.classic.machine().fatal().is_none()
        && entry.rejoin.is_dormant()
        && !entry.rediscovery.blocks_join()
}

fn fatal_state_matches(entry: &GroupConsumerEntry, fatal: ClassicGroupFatal) -> bool {
    entry.classic.machine().phase() == ClassicGroupPhase::Fatal
        && entry.classic.machine().fatal() == Some(fatal)
        && entry.classic.machine().pending_rejoin().is_none()
        && entry.rejoin.is_dormant()
}

fn post_rejoin(
    assignment: LiveGroupAssignment,
    generation: ClassicGeneration,
    schedule: ClassicRejoinSchedule,
    failure: ClassicRejectionInstallFailure,
) -> ClassicRejectionPostCore {
    ClassicRejectionPostCore::heartbeat(
        assignment,
        generation,
        ClassicGroupEffect::ArmRejoin {
            schedule,
            coordinator: ClassicCoordinatorRecovery::Retain,
        },
        failure,
    )
}

fn post_fatal(
    assignment: LiveGroupAssignment,
    generation: ClassicGeneration,
    fatal: ClassicGroupFatal,
    failure: ClassicRejectionInstallFailure,
) -> ClassicRejectionPostCore {
    ClassicRejectionPostCore::heartbeat(
        assignment,
        generation,
        ClassicGroupEffect::Fatal { fatal },
        failure,
    )
}

fn post_rediscovery(
    assignment: LiveGroupAssignment,
    generation: ClassicGeneration,
    schedule: ClassicRejoinSchedule,
    failure: ClassicRejectionInstallFailure,
) -> ClassicRejectionPostCore {
    ClassicRejectionPostCore::heartbeat(
        assignment,
        generation,
        ClassicGroupEffect::ArmRejoin {
            schedule,
            coordinator: ClassicCoordinatorRecovery::Rediscover,
        },
        failure,
    )
}

use ClassicRejectionInstallFailure::{
    Assignment, FetchRetirement, GracefulRevocation, MachineState, ProcessingLease,
    ProcessingLeaseCycleUnavailable, RediscoveryState, RejoinState,
};