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 {}