nodedb_lite/storage/
array_segment_ext.rs

1// SPDX-License-Identifier: Apache-2.0
2
3//! `ArraySegmentExt` — pagedb segment operations for array tile data.
4//!
5//! The `StorageEngine` trait handles sparse, sorted, key-value state.  For
6//! array tile data (large binary payloads, sequentially read per segment,
7//! encrypted at rest) pagedb segments are the appropriate backing.  This
8//! trait exposes exactly the operations the array persistence layer needs
9//! without leaking pagedb types into caller code.
10//!
11//! Only compiled on non-WASM targets.  WASM stays on the KV blob path.
12
13use crate::error::LiteError;
14
15/// Extension trait: write, open, and delete array tile segments backed by
16/// pagedb encrypted segment files.
17///
18/// Implementors translate between the generic array segment byte stream
19/// (produced by `nodedb_array::SegmentWriter`) and the pagedb segment page
20/// layout.
21///
22/// This trait is object-safe so `StorageEngine` implementations can return
23/// `Option<&dyn ArraySegmentExt>` via `as_array_segment_ext()`.
24#[async_trait::async_trait]
25pub trait ArraySegmentExt: Send + Sync {
26    /// Write an array segment for `array_name` / `seg_id`.
27    ///
28    /// Chunks the raw segment bytes into 4 KiB pagedb pages, creates a new
29    /// encrypted segment, and links it under `arr/tile/{array_name}/{seg_id}`.
30    /// If a segment already exists under that name it is atomically replaced
31    /// (old segment is tombstoned and reaped by the next `Db::gc_now` call).
32    async fn write_array_segment(
33        &self,
34        array_name: &str,
35        seg_id: u64,
36        bytes: &[u8],
37    ) -> Result<(), LiteError>;
38
39    /// Open a previously written array segment for `array_name` / `seg_id`.
40    ///
41    /// Returns the raw segment bytes in a `Box<[u8]>`, identical to the bytes
42    /// passed to `write_array_segment`.  `SegmentReader::open` can parse them
43    /// directly.
44    ///
45    /// Returns `None` if no segment exists under that name.
46    async fn open_array_segment(
47        &self,
48        array_name: &str,
49        seg_id: u64,
50    ) -> Result<Option<Box<[u8]>>, LiteError>;
51
52    /// Delete the array segment for `array_name` / `seg_id`.
53    ///
54    /// No-op if no segment exists.  The segment file is tombstoned and reaped
55    /// by the next `Db::gc_now` cycle.
56    async fn delete_array_segment(&self, array_name: &str, seg_id: u64) -> Result<(), LiteError>;
57}
nodedb_lite/storage/array_segment_ext.rs

nodedb_lite/storage/
array_segment_ext.rs
