Skip to main content

camus/
model.rs

1use crate::config::FullPolicy;
2use crate::error::{DurabilityOutcome, ErrorKind};
3use bytes::Bytes;
4use std::fmt;
5use std::ops::Deref;
6use std::time::Duration;
7
8/// A caller-selected logical stream namespace inside one storage root.
9#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
10#[repr(transparent)]
11pub struct StreamId(u64);
12
13impl StreamId {
14    /// Creates a logical stream identifier.
15    #[must_use]
16    pub const fn new(value: u64) -> Self {
17        Self(value)
18    }
19
20    /// Returns the caller-selected numeric value.
21    #[must_use]
22    pub const fn get(self) -> u64 {
23        self.0
24    }
25}
26
27impl From<u64> for StreamId {
28    fn from(value: u64) -> Self {
29        Self::new(value)
30    }
31}
32
33impl fmt::Display for StreamId {
34    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
35        self.0.fmt(formatter)
36    }
37}
38
39/// The immutable identity stored in one Camus root superblock.
40#[derive(Clone, Copy, Eq, Hash, Ord, PartialEq, PartialOrd)]
41pub(crate) struct RootId([u8; 16]);
42
43impl RootId {
44    pub(crate) const LEN: usize = 16;
45
46    pub(crate) fn random() -> std::io::Result<Self> {
47        let mut bytes = [0_u8; Self::LEN];
48        getrandom::fill(&mut bytes).map_err(|error| std::io::Error::other(error.to_string()))?;
49        Ok(Self(bytes))
50    }
51
52    pub(crate) const fn from_bytes(bytes: [u8; Self::LEN]) -> Self {
53        Self(bytes)
54    }
55
56    pub(crate) const fn to_bytes(self) -> [u8; Self::LEN] {
57        self.0
58    }
59}
60
61impl fmt::Debug for RootId {
62    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
63        formatter.write_str("RootId(")?;
64        write_hex(formatter, &self.0)?;
65        formatter.write_str(")")
66    }
67}
68
69/// A stable opaque record identity allocated by Camus.
70#[derive(Clone, Copy, Eq, Hash, Ord, PartialEq, PartialOrd)]
71pub struct RecordId([u8; Self::BYTE_LEN]);
72
73impl RecordId {
74    /// The fixed serialized size of every record ID.
75    pub const BYTE_LEN: usize = 32;
76
77    /// Reconstructs an opaque ID from its fixed serialization.
78    #[must_use]
79    pub const fn from_bytes(bytes: [u8; Self::BYTE_LEN]) -> Self {
80        Self(bytes)
81    }
82
83    /// Returns the fixed serialization of this ID.
84    #[must_use]
85    pub const fn to_bytes(self) -> [u8; Self::BYTE_LEN] {
86        self.0
87    }
88
89    /// Borrows the fixed serialization of this ID.
90    #[must_use]
91    pub const fn as_bytes(&self) -> &[u8; Self::BYTE_LEN] {
92        &self.0
93    }
94
95    pub(crate) fn from_parts(root_id: RootId, stream_id: StreamId, sequence: u64) -> Self {
96        let mut bytes = [0_u8; Self::BYTE_LEN];
97        bytes[..16].copy_from_slice(&root_id.to_bytes());
98        bytes[16..24].copy_from_slice(&stream_id.get().to_le_bytes());
99        bytes[24..32].copy_from_slice(&sequence.to_le_bytes());
100        Self(bytes)
101    }
102
103    pub(crate) fn root_id(self) -> RootId {
104        let mut bytes = [0_u8; RootId::LEN];
105        bytes.copy_from_slice(&self.0[..16]);
106        RootId::from_bytes(bytes)
107    }
108
109    pub(crate) fn stream_id(self) -> StreamId {
110        let mut bytes = [0_u8; 8];
111        bytes.copy_from_slice(&self.0[16..24]);
112        StreamId::new(u64::from_le_bytes(bytes))
113    }
114
115    pub(crate) fn sequence(self) -> u64 {
116        let mut bytes = [0_u8; 8];
117        bytes.copy_from_slice(&self.0[24..32]);
118        u64::from_le_bytes(bytes)
119    }
120}
121
122impl fmt::Debug for RecordId {
123    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
124        formatter.write_str("RecordId(")?;
125        write_hex(formatter, &self.0)?;
126        formatter.write_str(")")
127    }
128}
129
130impl fmt::Display for RecordId {
131    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
132        write_hex(formatter, &self.0)
133    }
134}
135
136fn write_hex(formatter: &mut fmt::Formatter<'_>, bytes: &[u8]) -> fmt::Result {
137    for byte in bytes {
138        write!(formatter, "{byte:02x}")?;
139    }
140    Ok(())
141}
142
143/// Opaque metadata and payload transferred into one append operation.
144#[derive(Clone, Debug, Default, Eq, PartialEq)]
145pub struct Record {
146    /// Application-owned opaque metadata bytes.
147    pub metadata: Bytes,
148    /// Application-owned opaque payload bytes.
149    pub payload: Bytes,
150}
151
152impl Record {
153    /// Creates a record with empty metadata.
154    #[must_use]
155    pub fn new(payload: impl Into<Bytes>) -> Self {
156        Self {
157            metadata: Bytes::new(),
158            payload: payload.into(),
159        }
160    }
161
162    /// Replaces the opaque metadata bytes.
163    #[must_use]
164    pub fn with_metadata(mut self, metadata: impl Into<Bytes>) -> Self {
165        self.metadata = metadata.into();
166        self
167    }
168}
169
170/// One owned pending record returned by a stream read.
171#[derive(Clone, Debug, Eq, PartialEq)]
172#[non_exhaustive]
173pub struct PendingRecord {
174    /// Stable storage identity used for release.
175    pub id: RecordId,
176    /// Verified opaque metadata bytes.
177    pub metadata: Bytes,
178    /// Verified opaque payload bytes.
179    pub payload: Bytes,
180}
181
182/// Hard bounds for one waiting stream read.
183#[derive(Clone, Copy, Debug, Eq, PartialEq)]
184pub struct ReadLimits {
185    /// Maximum number of records returned.
186    pub max_records: usize,
187    /// Maximum sum of returned payload bytes.
188    pub max_bytes: u64,
189}
190
191impl ReadLimits {
192    /// Creates explicit record-count and payload-byte limits.
193    #[must_use]
194    pub const fn new(max_records: usize, max_bytes: u64) -> Self {
195        Self {
196            max_records,
197            max_bytes,
198        }
199    }
200}
201
202/// A non-empty owned observation of pending records.
203#[derive(Clone, Debug, Eq, PartialEq)]
204pub struct PendingSnapshot(Vec<PendingRecord>);
205
206impl PendingSnapshot {
207    pub(crate) fn new(records: Vec<PendingRecord>) -> Self {
208        debug_assert!(!records.is_empty());
209        Self(records)
210    }
211
212    /// Returns the number of records in this snapshot.
213    #[must_use]
214    pub fn len(&self) -> usize {
215        self.0.len()
216    }
217
218    /// Returns whether the snapshot is empty.
219    ///
220    /// Successful `Stream::read` calls always return `false`; this method is
221    /// provided for normal collection ergonomics.
222    #[must_use]
223    pub fn is_empty(&self) -> bool {
224        self.0.is_empty()
225    }
226
227    /// Borrows the returned records.
228    #[must_use]
229    pub fn records(&self) -> &[PendingRecord] {
230        &self.0
231    }
232}
233
234impl Deref for PendingSnapshot {
235    type Target = [PendingRecord];
236
237    fn deref(&self) -> &Self::Target {
238        &self.0
239    }
240}
241
242impl IntoIterator for PendingSnapshot {
243    type Item = PendingRecord;
244    type IntoIter = std::vec::IntoIter<PendingRecord>;
245
246    fn into_iter(self) -> Self::IntoIter {
247        self.0.into_iter()
248    }
249}
250
251impl<'a> IntoIterator for &'a PendingSnapshot {
252    type Item = &'a PendingRecord;
253    type IntoIter = std::slice::Iter<'a, PendingRecord>;
254
255    fn into_iter(self) -> Self::IntoIter {
256        self.0.iter()
257    }
258}
259
260/// A count, total, and maximum for monotonic elapsed-time observations.
261#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
262#[non_exhaustive]
263pub struct DurationStats {
264    /// Number of elapsed-time observations included in this summary.
265    pub observations: u64,
266    /// Saturating sum of all observed durations.
267    pub total: Duration,
268    /// Longest observed duration.
269    pub max: Duration,
270}
271
272/// Current durable and physical aggregate state for one root.
273#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
274#[non_exhaustive]
275pub struct StorageStats {
276    /// Configured root capacity in bytes, or `None` for an unbounded root.
277    pub configured_capacity_bytes: Option<u64>,
278    /// Configured bounded-root full policy, or `None` when unbounded.
279    pub full_policy: Option<FullPolicy>,
280    /// Number of logical streams that have durable identity.
281    pub durable_streams: u64,
282    /// Number of records currently pending across all streams.
283    pub pending_records: u64,
284    /// Sum of payload bytes currently pending across all streams.
285    pub pending_payload_bytes: u64,
286    /// Exact encoded bytes currently charged to the root.
287    pub actual_file_bytes: u64,
288    /// Dynamic capacity reserved for maintenance progress.
289    pub maintenance_headroom_bytes: u64,
290    /// Bytes currently admissible for data, or `None` for an unbounded root.
291    pub data_admissible_bytes: Option<u64>,
292    /// Number of extant physical data segments.
293    pub live_segments: u64,
294    /// Number of live segments with a durable footer.
295    pub sealed_segments: u64,
296    /// Number of sealed segments currently eligible for reclamation.
297    pub reclaimable_segments: u64,
298    /// Exact segment bytes currently eligible for reclamation.
299    pub reclaimable_bytes: u64,
300}
301
302/// Current waiters plus saturating session totals for one wait category.
303#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
304#[non_exhaustive]
305pub struct WaitStats {
306    /// Number of operations currently waiting in this category.
307    pub current: usize,
308    /// Number of waits begun since this root was opened.
309    pub waits: u64,
310    /// Aggregate and maximum wait duration.
311    pub elapsed: DurationStats,
312}
313
314/// Detailed elapsed time for finite filesystem jobs by reactor work kind.
315#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
316#[non_exhaustive]
317pub struct StorageJobStats {
318    /// Append commit jobs, including size rollover performed by an append.
319    pub append: DurationStats,
320    /// Physical record-read jobs.
321    pub read: DurationStats,
322    /// Durable release commit jobs.
323    pub release: DurationStats,
324    /// Automatic and explicitly requested physical reclamation jobs.
325    pub reclaim: DurationStats,
326    /// Timer-driven segment rollover jobs.
327    pub segment_rollover: DurationStats,
328}
329
330/// Reactor admission and backpressure state for one open root.
331#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
332#[non_exhaustive]
333pub struct PressureStats {
334    /// Configured maximum number of admitted commands buffered for this root.
335    pub command_queue_capacity: usize,
336    /// Number of commands admitted but not complete.
337    pub queue_depth: usize,
338    /// Number of filesystem jobs currently executing for this root.
339    pub active_storage_jobs: usize,
340    /// Number of commands admitted since this root was opened.
341    pub admitted_commands: u64,
342    /// Time from queue insertion or internal requeue until reactor selection.
343    pub reactor_dispatch_wait: DurationStats,
344    /// Scheduling plus filesystem duration of completed storage jobs when enabled.
345    pub storage_job_elapsed: DurationStats,
346    /// Completed storage-job durations split by reactor work kind.
347    pub storage_jobs: StorageJobStats,
348    /// Time spent waiting for a command-queue permit.
349    pub queue_wait: WaitStats,
350    /// Time waiting for a stream to become readable.
351    pub readiness_wait: WaitStats,
352    /// Time blocked appends spent waiting for capacity to change.
353    pub capacity_wait: WaitStats,
354}
355
356/// Saturating session counters for one logical public operation.
357#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
358#[non_exhaustive]
359pub struct OperationCounters {
360    /// Calls begun since this root was opened.
361    pub started: u64,
362    /// Calls that returned success to their caller.
363    pub succeeded: u64,
364    /// Calls that returned an error to their caller.
365    pub failed: u64,
366    /// Calls whose Future was dropped before returning an outcome.
367    pub cancelled: u64,
368    /// Records supplied to or returned by successful calls.
369    ///
370    /// For release this includes duplicate and already-released IDs. Use
371    /// `CommitStats::release_records` for the number that changed durable
372    /// pending state.
373    pub records: u64,
374    /// Payload bytes supplied to successful appends or returned by reads.
375    ///
376    /// Release and reclaim calls contribute zero.
377    pub payload_bytes: u64,
378    /// End-to-end call durations when detailed timing is enabled.
379    pub elapsed: DurationStats,
380}
381
382/// Logical-operation activity for one open root.
383#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
384#[non_exhaustive]
385pub struct OperationStats {
386    /// Append and append-batch calls.
387    pub append: OperationCounters,
388    /// Waiting bounded-read calls.
389    pub read: OperationCounters,
390    /// Exact durable-release calls.
391    pub release: OperationCounters,
392    /// Explicit reclamation calls.
393    pub reclaim: OperationCounters,
394}
395
396/// Aggregate durability-group activity for one open root.
397#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
398#[non_exhaustive]
399pub struct CommitStats {
400    /// Successful append durability groups.
401    pub append_groups: u64,
402    /// Append API units included in successful groups.
403    pub append_units: u64,
404    /// Records included in successful append groups.
405    pub append_records: u64,
406    /// Encoded bytes included in successful append groups.
407    pub append_encoded_bytes: u64,
408    /// Largest successful append group in API units.
409    pub max_append_units: u64,
410    /// Largest successful append group in encoded bytes.
411    pub max_append_encoded_bytes: u64,
412    /// Successful release durability groups.
413    pub release_groups: u64,
414    /// Release API units that contributed a durable frame.
415    pub release_units: u64,
416    /// Unique records included in successful release groups.
417    pub release_records: u64,
418    /// Encoded manifest bytes included in successful release groups.
419    pub release_encoded_bytes: u64,
420    /// Largest successful release group in API units.
421    pub max_release_units: u64,
422    /// Largest successful release group in encoded bytes.
423    pub max_release_encoded_bytes: u64,
424}
425
426/// Successful physical maintenance activity for one open root.
427#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
428#[non_exhaustive]
429pub struct MaintenanceStats {
430    /// Low-priority or capacity-promoted reclamation passes.
431    pub automatic_reclaim_passes: u64,
432    /// Reclamation passes requested through `Log::reclaim`.
433    pub explicit_reclaim_passes: u64,
434    /// Segment seals caused by the configured hard size boundary.
435    pub size_rollovers: u64,
436    /// Segment seals caused by the configured soft age boundary.
437    pub age_rollovers: u64,
438    /// Fully released active segments sealed to make reclamation possible.
439    pub reclaim_rollovers: u64,
440    /// Physical segments successfully deleted and directory-synced.
441    pub reclaimed_segments: u64,
442    /// Exact segment bytes successfully deleted and directory-synced.
443    pub reclaimed_bytes: u64,
444    /// Successful complete manifest checkpoint rewrites.
445    pub manifest_compactions: u64,
446}
447
448/// Work performed while successfully opening and recovering the current root.
449#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
450#[non_exhaustive]
451pub struct RecoveryStats {
452    /// Complete physical manifest frames structurally scanned.
453    pub manifest_frames_scanned: u64,
454    /// Physical data segments structurally scanned.
455    pub segments_scanned: u64,
456    /// Complete append epochs structurally scanned.
457    pub epochs_scanned: u64,
458    /// Record descriptors indexed during recovery.
459    pub records_scanned: u64,
460    /// Incomplete active segment tails repaired under the format rules.
461    pub repaired_active_tails: u64,
462    /// Incomplete manifest-log tails repaired under the format rules.
463    pub repaired_manifest_tails: u64,
464    /// Complete segment footers published into the manifest during recovery.
465    pub completed_segment_seals: u64,
466    /// Durable segment deletions completed during recovery.
467    pub completed_segment_deletions: u64,
468    /// Stale root or segment temporary files removed during recovery.
469    pub removed_temporary_files: u64,
470    /// End-to-end duration of the successful storage open.
471    pub elapsed: Duration,
472}
473
474/// A synchronous in-memory snapshot of root-wide operational state.
475///
476/// Durable storage fields describe one coherent completed storage transition.
477/// Concurrent pressure and operation counters are sampled independently and
478/// may advance while the snapshot is being assembled.
479#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
480#[non_exhaustive]
481pub struct RootStats {
482    /// Whether end-to-end logical-call and storage-job timing is enabled.
483    pub detailed_timings: bool,
484    /// Durable and physical aggregate state.
485    pub storage: StorageStats,
486    /// Reactor queue and wait state.
487    pub pressure: PressureStats,
488    /// Logical public-operation activity for this open session.
489    pub operations: OperationStats,
490    /// Durability-group activity for this open session.
491    pub commits: CommitStats,
492    /// Successful maintenance activity for this open session.
493    pub maintenance: MaintenanceStats,
494    /// Work performed by the successful current open.
495    pub recovery: RecoveryStats,
496}
497
498/// Lifecycle state of one open root.
499#[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)]
500#[non_exhaustive]
501pub enum RootState {
502    /// The root accepts new operations.
503    #[default]
504    Running,
505    /// New admission is closed while admitted work drains.
506    ShuttingDown,
507    /// Storage or runtime execution failed closed and requires reopen.
508    Poisoned,
509    /// The reactor and every storage job have finished.
510    Closed,
511}
512
513impl RootState {
514    /// Returns the stable snake-case label for this lifecycle state.
515    #[must_use]
516    pub const fn as_str(self) -> &'static str {
517        match self {
518            Self::Running => "running",
519            Self::ShuttingDown => "shutting_down",
520            Self::Poisoned => "poisoned",
521            Self::Closed => "closed",
522        }
523    }
524}
525
526impl fmt::Display for RootState {
527    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
528        formatter.write_str(self.as_str())
529    }
530}
531
532/// Low-cardinality operation context for a failed-closed transition.
533#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
534#[non_exhaustive]
535pub enum OperationKind {
536    /// Append durability work.
537    Append,
538    /// Pending-record verification and read work.
539    Read,
540    /// Durable release work.
541    Release,
542    /// Automatic or explicit reclamation work.
543    Reclaim,
544    /// Reactor-driven age rollover work outside a foreground append.
545    SegmentRollover,
546    /// Publication of a completed storage state into the in-memory view.
547    StatePublication,
548    /// Root reactor or runtime progress.
549    Reactor,
550}
551
552impl OperationKind {
553    /// Returns the stable snake-case label for this operation context.
554    #[must_use]
555    pub const fn as_str(self) -> &'static str {
556        match self {
557            Self::Append => "append",
558            Self::Read => "read",
559            Self::Release => "release",
560            Self::Reclaim => "reclaim",
561            Self::SegmentRollover => "segment_rollover",
562            Self::StatePublication => "state_publication",
563            Self::Reactor => "reactor",
564        }
565    }
566}
567
568impl fmt::Display for OperationKind {
569    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
570        formatter.write_str(self.as_str())
571    }
572}
573
574/// Structured detail retained for the first failed-closed transition.
575#[derive(Clone, Debug, Eq, PartialEq)]
576#[non_exhaustive]
577pub struct FailureInfo {
578    /// Operation that encountered the root-poisoning failure.
579    pub operation: OperationKind,
580    /// Stable low-cardinality error classification.
581    pub error_kind: ErrorKind,
582    /// Whether an admitted mutation may nevertheless be durable.
583    ///
584    /// Camus reports `Unknown` conservatively when runtime failure prevents a
585    /// more precise result.
586    pub durability_outcome: DurabilityOutcome,
587    /// Human-readable detail intended for logs, never metric labels.
588    pub message: String,
589}
590
591/// Current lifecycle and first failed-closed cause for one open root.
592#[derive(Clone, Debug, Default, Eq, PartialEq)]
593#[non_exhaustive]
594pub struct RootHealth {
595    /// Monotonic in-memory lifecycle generation for this open session.
596    pub generation: u64,
597    /// Current root lifecycle state.
598    pub state: RootState,
599    /// First root-poisoning failure, retained through shutdown.
600    pub failure: Option<FailureInfo>,
601}
602
603/// A synchronous in-memory snapshot of one logical stream.
604#[derive(Clone, Debug, Default, Eq, PartialEq)]
605#[non_exhaustive]
606pub struct StreamStats {
607    /// Whether the stream has ever completed a recoverable append.
608    pub durable_known: bool,
609    /// Number of records currently pending in the stream.
610    pub pending_records: u64,
611    /// Sum of payload bytes currently pending in the stream.
612    pub pending_payload_bytes: u64,
613}
614
615/// Work completed by one explicit reclamation request.
616#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
617#[non_exhaustive]
618pub struct ReclaimReport {
619    /// Number of physical segment files removed.
620    pub segments: u64,
621    /// Exact encoded segment bytes removed.
622    pub bytes: u64,
623}
624
625impl ReclaimReport {
626    /// Returns whether the request removed no segment bytes.
627    #[must_use]
628    pub const fn is_empty(self) -> bool {
629        self.segments == 0 && self.bytes == 0
630    }
631}
632
633#[cfg(test)]
634mod tests {
635    use super::*;
636
637    #[test]
638    fn record_id_has_fixed_root_stream_sequence_encoding() {
639        let root = RootId::from_bytes([0x11; 16]);
640        let stream = StreamId::new(0x0203_0405_0607_0809);
641        let id = RecordId::from_parts(root, stream, 0x0a0b_0c0d_0e0f_1011);
642
643        assert_eq!(&id.as_bytes()[..16], &[0x11; 16]);
644        assert_eq!(id.root_id(), root);
645        assert_eq!(id.stream_id(), stream);
646        assert_eq!(id.sequence(), 0x0a0b_0c0d_0e0f_1011);
647        assert_eq!(RecordId::from_bytes(id.to_bytes()), id);
648    }
649}