Skip to main content

kafka_client_engine/consumer/
group_start.rs

1//! Capture-first public result vocabulary for group-consumer membership start.
2
3use std::time::Duration;
4
5use super::{GroupConsumerCycleAdmission, GroupConsumerCyclePortErrorCategory, GroupConsumerPort};
6use crate::clock::DeadlineCapture;
7
8/// Linear membership-start deadline captured before higher-layer input work.
9#[must_use = "a captured group start should be admitted or deliberately discarded"]
10pub struct GroupConsumerStartCapture {
11    port: GroupConsumerPort,
12    capture: DeadlineCapture,
13}
14
15impl GroupConsumerStartCapture {
16    pub(in crate::consumer) fn capture(
17        port: GroupConsumerPort,
18        timeout: Duration,
19    ) -> Result<Self, GroupConsumerStartError> {
20        let capture = port.capture_cycle_deadline(timeout).map_err(|_error| {
21            GroupConsumerStartError::from_port(GroupConsumerCyclePortErrorCategory::InvalidTimeout)
22        })?;
23        if timeout.is_zero() {
24            return Err(GroupConsumerStartError::from_port(
25                GroupConsumerCyclePortErrorCategory::InvalidTimeout,
26            ));
27        }
28        Ok(Self { port, capture })
29    }
30
31    pub(in crate::consumer) fn admit(
32        self,
33        port: &GroupConsumerPort,
34        group_id: kafka_client_core::GroupId,
35    ) -> Result<GroupConsumerCycleAdmission, GroupConsumerStartError> {
36        if !self.port.shares_registry_with(port) {
37            return Err(GroupConsumerStartError::from_port(
38                GroupConsumerCyclePortErrorCategory::InternalInvariant,
39            ));
40        }
41        port.admit_captured_cycle(group_id, self.capture)
42            .map_err(|error| GroupConsumerStartError::from_port(error.public_category()))
43    }
44}
45
46impl core::fmt::Debug for GroupConsumerStartCapture {
47    fn fmt(&self, formatter: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
48        formatter
49            .debug_struct("GroupConsumerStartCapture")
50            .finish_non_exhaustive()
51    }
52}
53
54/// Stable reason a membership cycle was rejected before deterministic core mutation.
55#[derive(Clone, Copy, Debug, Eq, PartialEq)]
56pub enum GroupConsumerStartErrorKind {
57    /// Engine or group admission has closed.
58    Closed,
59    /// Another owner currently holds the bounded group registry.
60    Contended,
61    /// This registered group already owns membership work.
62    AlreadyStarted,
63    /// The exact registered group is closing or no longer available.
64    GroupUnavailable,
65    /// The requested timeout cannot be represented as an absolute deadline.
66    InvalidTimeout,
67    /// An engine ownership invariant prevented admission.
68    Internal,
69}
70
71/// Pre-core membership-start rejection that leaves the handle retryable.
72#[derive(Clone, Copy, Debug, Eq, PartialEq)]
73pub struct GroupConsumerStartError {
74    kind: GroupConsumerStartErrorKind,
75}
76
77impl GroupConsumerStartError {
78    pub(in crate::consumer) const fn from_port(
79        category: GroupConsumerCyclePortErrorCategory,
80    ) -> Self {
81        let kind = match category {
82            GroupConsumerCyclePortErrorCategory::InvalidTimeout => {
83                GroupConsumerStartErrorKind::InvalidTimeout
84            }
85            GroupConsumerCyclePortErrorCategory::Closed => GroupConsumerStartErrorKind::Closed,
86            GroupConsumerCyclePortErrorCategory::Contended => {
87                GroupConsumerStartErrorKind::Contended
88            }
89            GroupConsumerCyclePortErrorCategory::AlreadyStarted => {
90                GroupConsumerStartErrorKind::AlreadyStarted
91            }
92            GroupConsumerCyclePortErrorCategory::GroupUnavailable => {
93                GroupConsumerStartErrorKind::GroupUnavailable
94            }
95            GroupConsumerCyclePortErrorCategory::InternalInvariant => {
96                GroupConsumerStartErrorKind::Internal
97            }
98        };
99        Self { kind }
100    }
101
102    /// Returns the stable rejection category.
103    pub const fn kind(self) -> GroupConsumerStartErrorKind {
104        self.kind
105    }
106}
107
108impl core::fmt::Display for GroupConsumerStartError {
109    fn fmt(&self, formatter: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
110        write!(
111            formatter,
112            "group-consumer membership start rejected: {:?}",
113            self.kind
114        )
115    }
116}
117
118impl std::error::Error for GroupConsumerStartError {}
119
120/// Accepted membership ownership plus advisory engine degradation.
121#[derive(Clone, Copy, Debug, Eq, PartialEq)]
122#[must_use = "accepted membership remains owned even when advisory progress degraded"]
123pub struct GroupConsumerStartAccepted {
124    entry_faulted: bool,
125    wake_failed: bool,
126}
127
128impl GroupConsumerStartAccepted {
129    pub(in crate::consumer) const fn new(entry_faulted: bool, wake_failed: bool) -> Self {
130        Self {
131            entry_faulted,
132            wake_failed,
133        }
134    }
135
136    /// Reports that accepted post-core ownership was frozen by an invariant fault.
137    pub const fn entry_faulted(self) -> bool {
138        self.entry_faulted
139    }
140
141    /// Reports that the advisory reactor wake failed after admission.
142    pub const fn wake_failed(self) -> bool {
143        self.wake_failed
144    }
145}