Skip to main content

bornera_core/write/
error.rs

1//! Ownership-preserving admission rejection and exact-progress faults.
2
3use core::fmt;
4
5use calandria::RetainedBytes;
6
7use crate::{ConnectionEpoch, EffectId};
8
9/// Pending identity category that a new frame attempted to reuse.
10#[derive(Clone, Copy, Debug, Eq, PartialEq)]
11#[non_exhaustive]
12pub enum WriteIdentityKind {
13    /// Accepted operation identity.
14    Operation,
15    /// Write effect identity.
16    Effect,
17}
18
19/// Why a complete frame could not enter the bounded writer.
20#[derive(Clone, Copy, Debug, Eq, PartialEq)]
21#[non_exhaustive]
22pub enum WriteAdmissionFailure {
23    /// The frame names an epoch other than the writer's fixed epoch.
24    StaleEpoch {
25        /// Epoch owned by the writer.
26        expected: ConnectionEpoch,
27        /// Epoch supplied with the frame.
28        received: ConnectionEpoch,
29    },
30    /// An operation or effect identity is already retained.
31    IdentityInUse(WriteIdentityKind),
32    /// The configured frame-count capacity was reached.
33    FrameCapacityReached {
34        /// Configured maximum frames.
35        limit: usize,
36    },
37    /// Retaining the frame would exceed the configured byte bound.
38    RetainedByteCapacity {
39        /// Bytes already retained by the writer.
40        retained: RetainedBytes,
41        /// Bytes retained by the rejected frame.
42        incoming: RetainedBytes,
43        /// Configured retained-byte maximum.
44        limit: RetainedBytes,
45    },
46}
47
48/// Rejected admission that preserves the exact unsent frame.
49#[derive(Clone, Debug, Eq, PartialEq)]
50pub(crate) struct WriteAdmissionError<F> {
51    failure: WriteAdmissionFailure,
52    frame: F,
53}
54
55impl<F> WriteAdmissionError<F> {
56    pub(crate) const fn new(failure: WriteAdmissionFailure, frame: F) -> Self {
57        Self { failure, frame }
58    }
59
60    /// Returns the mechanical admission failure.
61    pub(crate) const fn failure(&self) -> WriteAdmissionFailure {
62        self.failure
63    }
64
65    /// Recovers the exact unadmitted frame.
66    pub(crate) fn into_frame(self) -> F {
67        self.frame
68    }
69}
70
71impl<F> fmt::Display for WriteAdmissionError<F> {
72    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
73        self.failure.fmt(formatter)
74    }
75}
76
77impl<F: fmt::Debug> core::error::Error for WriteAdmissionError<F> {}
78
79impl fmt::Display for WriteAdmissionFailure {
80    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
81        formatter.write_str(match self {
82            Self::StaleEpoch { .. } => "frame belongs to another connection epoch",
83            Self::IdentityInUse(_) => "operation or effect identity is already queued",
84            Self::FrameCapacityReached { .. } => "write-frame capacity is exhausted",
85            Self::RetainedByteCapacity { .. } => "write retained-byte capacity is exhausted",
86        })
87    }
88}
89
90/// Why reported transport progress could not mutate the FIFO front.
91#[derive(Clone, Copy, Debug, Eq, PartialEq)]
92#[non_exhaustive]
93pub enum WriteProgressError {
94    /// The progress event belongs to another epoch.
95    StaleEpoch {
96        /// Epoch owned by the writer.
97        expected: ConnectionEpoch,
98        /// Epoch supplied with progress.
99        received: ConnectionEpoch,
100    },
101    /// No frame currently awaits progress.
102    NoPendingWrite,
103    /// Progress named an effect other than the FIFO front.
104    OutOfOrderEffect {
105        /// Effect at the FIFO front.
106        expected: EffectId,
107        /// Effect supplied with progress.
108        received: EffectId,
109    },
110    /// Reported bytes exceed the frame's remaining bytes.
111    ExceedsRemaining {
112        /// Bytes reported written.
113        written: usize,
114        /// Bytes remaining before the report.
115        remaining: usize,
116    },
117    /// Cached progress exceeded the frame's commit-time wire measurement.
118    ProgressAccountingOverflow {
119        /// Complete wire length sampled at commit.
120        measured: usize,
121        /// Bytes already reported as written.
122        written: usize,
123    },
124    /// Internal retained-byte release exceeded the writer's accounted total.
125    RetainedAccountingUnderflow {
126        /// Bytes accounted before release.
127        retained: RetainedBytes,
128        /// Bytes the completed or discarded frame required releasing.
129        released: RetainedBytes,
130    },
131}
132
133impl fmt::Display for WriteProgressError {
134    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
135        formatter.write_str(match self {
136            Self::StaleEpoch { .. } => "write progress belongs to another epoch",
137            Self::NoPendingWrite => "no ordered write is pending",
138            Self::OutOfOrderEffect { .. } => "write progress does not name the FIFO front",
139            Self::ExceedsRemaining { .. } => "write progress exceeds remaining frame bytes",
140            Self::ProgressAccountingOverflow { .. } => {
141                "write progress exceeded the committed frame measurement"
142            }
143            Self::RetainedAccountingUnderflow { .. } => {
144                "write retained-byte accounting underflowed"
145            }
146        })
147    }
148}
149
150impl core::error::Error for WriteProgressError {}