Skip to main content

bornera_core/write/
frame.rs

1//! Opaque complete-frame capability and one-time admission measurement.
2
3use calandria::RetainedBytes;
4
5/// Wire length and retained memory sampled once when a frame is committed.
6///
7/// Bornera owns this measurement for the remainder of the frame's lifetime. It
8/// never re-samples retained memory or uses a later byte-view length for bounds
9/// accounting or write completion.
10#[derive(Clone, Copy, Debug, Eq, PartialEq)]
11pub struct FrameMeasure {
12    wire_bytes: usize,
13    retained_bytes: RetainedBytes,
14}
15
16impl FrameMeasure {
17    /// Samples one frame's wire length and retained memory exactly once.
18    pub fn capture<F>(frame: &F) -> Self
19    where
20        F: WriteFrame + ?Sized,
21    {
22        Self {
23            wire_bytes: frame.bytes().len(),
24            retained_bytes: frame.retained_bytes(),
25        }
26    }
27
28    /// Returns the complete wire length observed at commit.
29    pub const fn wire_bytes(self) -> usize {
30        self.wire_bytes
31    }
32
33    /// Returns the retained-memory footprint observed at commit.
34    pub const fn retained_bytes(self) -> RetainedBytes {
35        self.retained_bytes
36    }
37}
38
39/// A frame changed the byte-view shape promised at commit.
40#[derive(Clone, Copy, Debug, Eq, PartialEq)]
41#[non_exhaustive]
42pub enum FrameContractViolation {
43    /// The current byte-view length differs from the committed measurement.
44    WireLengthChanged {
45        /// Wire length sampled at commit.
46        measured: usize,
47        /// Wire length observed while borrowing the next write slice.
48        observed: usize,
49    },
50    /// The cached progress range was unavailable in the current byte view.
51    WriteRangeUnavailable {
52        /// Wire length sampled at commit.
53        measured: usize,
54        /// Bytes already reported as written.
55        written: usize,
56        /// Current byte-view length.
57        observed: usize,
58    },
59}
60
61/// A complete outbound frame with explicit retained-memory accounting.
62///
63/// The byte contents and length must remain stable for the entire period that
64/// Bornera owns the value. Retained memory is sampled once at commit. A later
65/// byte-length change is rejected explicitly rather than indexed unchecked;
66/// same-length content mutation remains a caller contract violation that
67/// Bornera cannot mechanically detect without copying the frame.
68pub trait WriteFrame {
69    /// Returns the contiguous bytes still interpreted only by the transport.
70    fn bytes(&self) -> &[u8];
71
72    /// Returns all variable memory retained while this frame remains owned.
73    fn retained_bytes(&self) -> RetainedBytes;
74}
75
76impl core::fmt::Display for FrameContractViolation {
77    fn fmt(&self, formatter: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
78        formatter.write_str(match self {
79            Self::WireLengthChanged { .. } => "frame wire length changed after commit",
80            Self::WriteRangeUnavailable { .. } => {
81                "frame byte view no longer contains the committed write range"
82            }
83        })
84    }
85}
86
87impl core::error::Error for FrameContractViolation {}