Skip to main content

kafka_client_engine/admin/update_features/
handle.rs

1//! Capture-first runtime-neutral admission of one finalized-feature mutation.
2
3use std::{fmt, time::Duration};
4
5use crate::{admin::AdminHandle, clock::DeadlineCapture};
6
7use super::{
8    UpdateFeaturesAdmissionError, UpdateFeaturesAdmissionErrorKind, UpdateFeaturesObserver,
9    UpdateFeaturesRequest, model::UpdateFeaturesPlanFailure,
10};
11
12impl AdminHandle {
13    /// Captures the original public deadline before request conversion.
14    pub fn capture_update_features(
15        &self,
16        timeout: Duration,
17    ) -> Result<UpdateFeaturesCapture<'_>, UpdateFeaturesAdmissionError> {
18        let deadline = self
19            .clock
20            .capture_deadline_after(timeout)
21            .map_err(|_error| admission(UpdateFeaturesAdmissionErrorKind::InvalidDeadline))?;
22        Ok(UpdateFeaturesCapture {
23            handle: self,
24            deadline,
25            timeout,
26        })
27    }
28
29    /// Captures and submits an already engine-owned request.
30    pub fn try_update_features(
31        &self,
32        request: UpdateFeaturesRequest,
33        timeout: Duration,
34    ) -> Result<UpdateFeaturesAccepted, UpdateFeaturesAdmissionError> {
35        self.capture_update_features(timeout)?.try_submit(request)
36    }
37}
38
39/// Linear original-deadline token bound to one Admin handle.
40#[must_use = "dropping abandons the deadline without admitting UpdateFeatures work"]
41pub struct UpdateFeaturesCapture<'handle> {
42    handle: &'handle AdminHandle,
43    deadline: DeadlineCapture,
44    timeout: Duration,
45}
46
47impl UpdateFeaturesCapture<'_> {
48    /// Validates bounded intent and atomically reserves terminal ownership.
49    pub fn try_submit(
50        self,
51        request: UpdateFeaturesRequest,
52    ) -> Result<UpdateFeaturesAccepted, UpdateFeaturesAdmissionError> {
53        if self.timeout.is_zero() {
54            return Err(admission(UpdateFeaturesAdmissionErrorKind::InvalidDeadline));
55        }
56        let plan = request.plan().map_err(|error| {
57            admission(match error {
58                UpdateFeaturesPlanFailure::Invalid => {
59                    UpdateFeaturesAdmissionErrorKind::InvalidRequest
60                }
61                UpdateFeaturesPlanFailure::RetainedBytes => {
62                    UpdateFeaturesAdmissionErrorKind::RetainedBytes
63                }
64            })
65        })?;
66        drop(request);
67
68        let now = self
69            .handle
70            .clock
71            .now()
72            .map_err(|_error| admission(UpdateFeaturesAdmissionErrorKind::HostUnavailable))?;
73        if self.deadline.deadline().is_elapsed_at(now) {
74            return Err(admission(UpdateFeaturesAdmissionErrorKind::InvalidDeadline));
75        }
76        let admitted = self
77            .handle
78            .update_features
79            .try_admit(now, self.deadline.operation_deadline(), plan)
80            .map_err(admission)?;
81        Ok(UpdateFeaturesAccepted {
82            observer: admitted.observer,
83            fault: admitted.fault.map(accepted_fault_kind),
84        })
85    }
86}
87
88impl fmt::Debug for UpdateFeaturesCapture<'_> {
89    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
90        formatter
91            .debug_struct("UpdateFeaturesCapture")
92            .finish_non_exhaustive()
93    }
94}
95
96const fn admission(kind: UpdateFeaturesAdmissionErrorKind) -> UpdateFeaturesAdmissionError {
97    UpdateFeaturesAdmissionError::new(kind)
98}
99
100const fn accepted_fault_kind(
101    fault: super::UpdateFeaturesHostError,
102) -> UpdateFeaturesAcceptedFaultKind {
103    match fault {
104        super::UpdateFeaturesHostError::Wake => UpdateFeaturesAcceptedFaultKind::Wake,
105        _ => UpdateFeaturesAcceptedFaultKind::HostInvariant,
106    }
107}
108
109/// Accepted post-commit degradation that cannot revoke ownership.
110#[derive(Clone, Copy, Debug, Eq, PartialEq)]
111pub enum UpdateFeaturesAcceptedFaultKind {
112    /// The coalescing host wake failed after admission committed.
113    Wake,
114    /// A concrete host invariant failed after terminal reservation.
115    HostInvariant,
116}
117
118/// Accepted operation plus advisory post-commit degradation.
119#[must_use = "accepted UpdateFeatures work must retain its observer"]
120pub struct UpdateFeaturesAccepted {
121    observer: UpdateFeaturesObserver,
122    fault: Option<UpdateFeaturesAcceptedFaultKind>,
123}
124
125impl UpdateFeaturesAccepted {
126    /// Returns advisory post-commit degradation.
127    pub const fn fault(&self) -> Option<UpdateFeaturesAcceptedFaultKind> {
128        self.fault
129    }
130
131    /// Consumes acceptance into its named observer.
132    pub fn into_observer(self) -> UpdateFeaturesObserver {
133        self.observer
134    }
135}
136
137impl fmt::Debug for UpdateFeaturesAccepted {
138    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
139        formatter
140            .debug_struct("UpdateFeaturesAccepted")
141            .field("observer", &self.observer)
142            .field("fault", &self.fault)
143            .finish()
144    }
145}