Skip to main content

kafka_client_engine/consumer/assigned_host/
result.rs

1//! Stable close admission and exact private assigned-consumer port results.
2
3use std::fmt;
4
5use kafka_client_core::AssignedConsumerMachineError;
6
7use crate::clock::ClockError;
8use crate::completion::CompletionRegistryError;
9
10use super::{
11    super::assigned_owner_model::AssignedConsumerOwnerError, AssignedConsumerCloseObserver,
12    shard::AssignedConsumerShardLockError, wake::AssignedConsumerShardWakeError,
13};
14
15#[derive(Clone, Copy, Debug, Eq, PartialEq)]
16pub(crate) enum AssignedConsumerPortAcceptedFaultKind {
17    Wake,
18}
19
20#[must_use = "accepted assigned-consumer work retains any post-commit host fault"]
21pub(crate) struct AssignedConsumerAccepted<T> {
22    value: T,
23    wake: Option<AssignedConsumerShardWakeError>,
24}
25
26impl<T> AssignedConsumerAccepted<T> {
27    pub(super) fn new(value: T, wake: Result<(), AssignedConsumerShardWakeError>) -> Self {
28        Self {
29            value,
30            wake: wake.err(),
31        }
32    }
33
34    pub(crate) const fn fault(&self) -> Option<AssignedConsumerPortAcceptedFaultKind> {
35        if self.wake.is_some() {
36            Some(AssignedConsumerPortAcceptedFaultKind::Wake)
37        } else {
38            None
39        }
40    }
41
42    pub(crate) fn into_value(self) -> T {
43        self.value
44    }
45}
46
47/// Stable post-acceptance degradation that cannot revoke close ownership.
48#[derive(Clone, Copy, Debug, Eq, PartialEq)]
49pub enum AssignedConsumerAcceptedFaultKind {
50    /// Close was accepted, but requesting an immediate host turn failed.
51    Wake,
52}
53
54/// Accepted assigned-consumer close and its single terminal observer.
55#[must_use = "accepted close work must retain or deliberately abandon its observer"]
56pub struct AssignedConsumerTryCloseAccepted {
57    observer: AssignedConsumerCloseObserver,
58    fault: Option<AssignedConsumerAcceptedFaultKind>,
59}
60
61impl AssignedConsumerTryCloseAccepted {
62    /// Returns post-acceptance degradation without reclassifying close as rejected.
63    pub const fn fault(&self) -> Option<AssignedConsumerAcceptedFaultKind> {
64        self.fault
65    }
66
67    /// Transfers the sole terminal observer to the caller.
68    pub fn into_observer(self) -> AssignedConsumerCloseObserver {
69        self.observer
70    }
71
72    pub(super) fn from_port(
73        accepted: AssignedConsumerAccepted<AssignedConsumerCloseObserver>,
74    ) -> Self {
75        let fault = accepted.fault().map(|fault| match fault {
76            AssignedConsumerPortAcceptedFaultKind::Wake => AssignedConsumerAcceptedFaultKind::Wake,
77        });
78        Self {
79            observer: accepted.into_value(),
80            fault,
81        }
82    }
83}
84
85impl fmt::Debug for AssignedConsumerTryCloseAccepted {
86    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
87        formatter
88            .debug_struct("AssignedConsumerTryCloseAccepted")
89            .field("observer", &self.observer)
90            .field("fault", &self.fault)
91            .finish()
92    }
93}
94
95/// Stable reason an assigned-consumer close did not cross admission.
96#[derive(Clone, Copy, Debug, Eq, PartialEq)]
97pub enum AssignedConsumerTryCloseErrorKind {
98    /// Another caller or the host currently owns the assigned-consumer shard.
99    Contended,
100    /// Assigned-consumer admission is permanently closed.
101    Closed,
102    /// The sole terminal-completion reservation is still occupied.
103    CompletionCapacity,
104    /// Earlier accepted effects must be interpreted before close can be admitted.
105    Pending,
106    /// The synchronized host can no longer execute new assigned-consumer work.
107    HostUnavailable,
108    /// A non-semantic engine mechanism violated its ownership contract.
109    InternalInvariant,
110}
111
112/// Immediate assigned-consumer close rejection before ownership crossed.
113#[derive(Clone, Copy, Debug, Eq, PartialEq)]
114pub struct AssignedConsumerTryCloseError {
115    kind: AssignedConsumerTryCloseErrorKind,
116}
117
118impl AssignedConsumerTryCloseError {
119    /// Returns the stable rejection category.
120    pub const fn kind(&self) -> AssignedConsumerTryCloseErrorKind {
121        self.kind
122    }
123
124    pub(super) const fn from_port(error: &AssignedConsumerPortError) -> Self {
125        Self {
126            kind: close_admission_error_kind(error),
127        }
128    }
129}
130
131impl fmt::Display for AssignedConsumerTryCloseError {
132    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
133        write!(
134            formatter,
135            "assigned-consumer close admission failed: {:?}",
136            self.kind
137        )
138    }
139}
140
141impl std::error::Error for AssignedConsumerTryCloseError {}
142
143#[derive(Debug)]
144pub(crate) enum AssignedConsumerPortError {
145    Clock(ClockError),
146    Closed,
147    Lock(AssignedConsumerShardLockError),
148    Owner {
149        error: AssignedConsumerOwnerError,
150        wake: Option<AssignedConsumerShardWakeError>,
151    },
152}
153
154impl AssignedConsumerPortError {
155    #[cfg_attr(
156        not(test),
157        expect(
158            dead_code,
159            reason = "the next engine boundary will translate the exact clock failure"
160        )
161    )]
162    pub(crate) const fn clock_error(&self) -> Option<ClockError> {
163        match self {
164            Self::Clock(error) => Some(*error),
165            Self::Closed | Self::Lock(_) | Self::Owner { .. } => None,
166        }
167    }
168}
169
170const fn close_admission_error_kind(
171    error: &AssignedConsumerPortError,
172) -> AssignedConsumerTryCloseErrorKind {
173    match error {
174        AssignedConsumerPortError::Closed
175        | AssignedConsumerPortError::Owner {
176            error: AssignedConsumerOwnerError::Core(AssignedConsumerMachineError::ConsumerClosed),
177            ..
178        } => AssignedConsumerTryCloseErrorKind::Closed,
179        AssignedConsumerPortError::Lock(AssignedConsumerShardLockError::Contended) => {
180            AssignedConsumerTryCloseErrorKind::Contended
181        }
182        AssignedConsumerPortError::Owner {
183            error: AssignedConsumerOwnerError::EffectsPending,
184            ..
185        } => AssignedConsumerTryCloseErrorKind::Pending,
186        AssignedConsumerPortError::Owner {
187            error: AssignedConsumerOwnerError::Completion(CompletionRegistryError::Full),
188            ..
189        } => AssignedConsumerTryCloseErrorKind::CompletionCapacity,
190        AssignedConsumerPortError::Lock(
191            AssignedConsumerShardLockError::Poisoned | AssignedConsumerShardLockError::OwnerMissing,
192        )
193        | AssignedConsumerPortError::Owner {
194            error:
195                AssignedConsumerOwnerError::Faulted
196                | AssignedConsumerOwnerError::Completion(
197                    CompletionRegistryError::NotifierStopped
198                    | CompletionRegistryError::GenerationExhausted
199                    | CompletionRegistryError::ReclaimDisconnected,
200                ),
201            ..
202        } => AssignedConsumerTryCloseErrorKind::HostUnavailable,
203        AssignedConsumerPortError::Clock(_) | AssignedConsumerPortError::Owner { .. } => {
204            AssignedConsumerTryCloseErrorKind::InternalInvariant
205        }
206    }
207}