Skip to main content

kafka_client_engine/consumer/assigned_host/
assignment_result.rs

1//! Stable synchronous acceptance and rejection values for assignment replacement.
2
3use kafka_client_core::AssignmentEpoch;
4
5use super::{
6    assignment_error::assignment_error_kind,
7    result::{
8        AssignedConsumerAccepted, AssignedConsumerPortAcceptedFaultKind, AssignedConsumerPortError,
9    },
10};
11
12/// Opaque engine representation of one accepted assignment generation.
13#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
14pub struct AssignedConsumerAssignmentEpoch(AssignmentEpoch);
15
16impl AssignedConsumerAssignmentEpoch {
17    /// Returns the stable scalar epoch used by later engine control boundaries.
18    pub const fn get(self) -> u64 {
19        self.0.get()
20    }
21
22    pub(super) const fn from_core(epoch: AssignmentEpoch) -> Self {
23        Self(epoch)
24    }
25
26    pub(super) const fn into_core(self) -> AssignmentEpoch {
27        self.0
28    }
29}
30
31/// Accepted synchronous replacement and any advisory post-commit wake fault.
32#[must_use = "assignment acceptance and wake diagnostics must be inspected"]
33#[derive(Clone, Copy)]
34pub struct AssignedConsumerTryReplaceAssignmentAccepted {
35    epoch: AssignedConsumerAssignmentEpoch,
36    fault: Option<super::AssignedConsumerAcceptedFaultKind>,
37}
38
39impl AssignedConsumerTryReplaceAssignmentAccepted {
40    /// Returns the new assignment generation.
41    pub const fn epoch(&self) -> AssignedConsumerAssignmentEpoch {
42        self.epoch
43    }
44
45    /// Returns post-acceptance degradation without revoking assignment acceptance.
46    pub const fn fault(&self) -> Option<super::AssignedConsumerAcceptedFaultKind> {
47        self.fault
48    }
49
50    pub(super) fn from_port(accepted: AssignedConsumerAccepted<AssignmentEpoch>) -> Self {
51        let fault = accepted.fault().map(|fault| match fault {
52            AssignedConsumerPortAcceptedFaultKind::Wake => {
53                super::AssignedConsumerAcceptedFaultKind::Wake
54            }
55        });
56        Self {
57            epoch: AssignedConsumerAssignmentEpoch::from_core(accepted.into_value()),
58            fault,
59        }
60    }
61}
62
63impl std::fmt::Debug for AssignedConsumerTryReplaceAssignmentAccepted {
64    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
65        formatter
66            .debug_struct("AssignedConsumerTryReplaceAssignmentAccepted")
67            .field("epoch", &self.epoch)
68            .field("fault", &self.fault)
69            .finish()
70    }
71}
72
73/// Stable reason an assignment replacement did not cross admission.
74#[derive(Clone, Copy, Debug, Eq, PartialEq)]
75pub enum AssignedConsumerTryReplaceAssignmentErrorKind {
76    /// Another caller or the host currently owns the assigned-consumer shard.
77    Contended,
78    /// Assigned-consumer admission is permanently closed.
79    Closed,
80    /// Earlier accepted effects must be interpreted before replacement.
81    Pending,
82    /// The replacement exceeds the configured partition bound.
83    AssignmentCapacity,
84    /// The retained topic catalog has no capacity for another topic.
85    TopicCapacity,
86    /// Retained topic-name bytes have reached their configured bound.
87    RetainedNameCapacity,
88    /// Terminal consumer-event claims currently occupy their bounded store.
89    EventCapacity,
90    /// A direct assignment must contain at least one partition.
91    EmptyAssignment,
92    /// One topic-partition appeared more than once.
93    DuplicatePartition,
94    /// The requested timeout cannot become one absolute deadline.
95    DeadlineOverflow,
96    /// A bounded local allocation or identity domain is exhausted.
97    ResourceExhausted,
98    /// The synchronized host can no longer execute new assigned-consumer work.
99    HostUnavailable,
100    /// A non-semantic engine mechanism violated its ownership contract.
101    InternalInvariant,
102}
103
104/// Immediate assignment-replacement rejection before ownership crossed.
105#[derive(Clone, Copy, Debug, Eq, PartialEq)]
106pub struct AssignedConsumerTryReplaceAssignmentError {
107    kind: AssignedConsumerTryReplaceAssignmentErrorKind,
108}
109
110impl AssignedConsumerTryReplaceAssignmentError {
111    /// Returns the stable rejection category.
112    pub const fn kind(&self) -> AssignedConsumerTryReplaceAssignmentErrorKind {
113        self.kind
114    }
115
116    pub(super) const fn from_port(error: &AssignedConsumerPortError) -> Self {
117        Self {
118            kind: assignment_error_kind(error),
119        }
120    }
121}
122
123impl std::fmt::Display for AssignedConsumerTryReplaceAssignmentError {
124    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
125        write!(
126            formatter,
127            "assigned-consumer assignment replacement failed: {:?}",
128            self.kind
129        )
130    }
131}
132
133impl std::error::Error for AssignedConsumerTryReplaceAssignmentError {}