wasm_dbms_memory/
lib.rs

1// Rust guideline compliant 2026-04-28
2// X-WHERE-CLAUSE, M-CANONICAL-DOCS
3
4#![crate_name = "wasm_dbms_memory"]
5#![crate_type = "lib"]
6#![cfg_attr(docsrs, feature(doc_cfg))]
7#![deny(clippy::print_stdout)]
8#![deny(clippy::print_stderr)]
9
10//! # wasm-dbms-memory
11//!
12//! Runtime-agnostic memory abstraction and page management for the
13//! [`wasm-dbms`](https://crates.io/crates/wasm-dbms) framework.
14//!
15//! This crate sits between the raw byte storage exposed by a WASM
16//! runtime (heap, file, IC stable memory, ...) and the higher-level
17//! DBMS engine. It defines the [`MemoryProvider`] trait that abstracts
18//! over the storage backend and the on-top-of-it data structures that
19//! the engine uses to persist tables, schema, indexes, and access
20//! control state.
21//!
22//! All structures use 64 KiB pages so the on-disk layout is byte-for-byte
23//! identical across providers — a heap-built database can be dumped and
24//! reopened as IC stable memory or a WASI file with no conversion.
25//!
26//! ## What this crate provides
27//!
28//! Storage backends:
29//!
30//! - [`MemoryProvider`] — trait every backend implements (read, write,
31//!   grow, page count).
32//! - [`HeapMemoryProvider`] — in-memory provider for tests and embedded
33//!   use cases.
34//!
35//! Access control:
36//!
37//! - [`AccessControl`] — pluggable access control trait.
38//! - [`AccessControlList`] — identity-based per-table permissions
39//!   persisted on a dedicated page.
40//! - [`NoAccessControl`] — zero-overhead provider for runtimes that do
41//!   not need access control.
42//!
43//! Engine-facing data structures:
44//!
45//! - [`MemoryManager`] — page allocator and low-level read/write
46//!   helpers. See [`RESERVED_PAGES`] for the reserved layout.
47//! - [`SchemaRegistry`] — persistent table-schema store backed by
48//!   [`TableRegistryPage`].
49//! - [`TableRegistry`] — record-level storage, free-segment tracking,
50//!   and read iterators ([`TableReader`], [`RawTableReader`],
51//!   [`NextRecord`], [`RecordAddress`], [`RawRecordBytes`]).
52//! - [`IndexLedger`] / [`IndexTreeWalker`] — secondary index storage
53//!   and traversal.
54//! - [`table_registry::AutoincrementLedger`] — per-column
55//!   autoincrement counters.
56//! - [`UnclaimedPages`] — free page pool ([`UNCLAIMED_PAGES_CAPACITY`]
57//!   entries per ledger page).
58//! - [`align_up`] / [`WASM_PAGE_SIZE`] — alignment helpers.
59//!
60//! ## Memory layout
61//!
62//! Reserved pages followed by per-table page sets:
63//!
64//! ```text
65//! +0:  Schema Registry            (1 page)
66//! +1:  ACL Table                  (1 page)
67//! +N:  Per-table Page Ledger      (1 page)
68//! +N:  Per-table Free Segments    (1 page)
69//! +N:  Per-table Record Pages     (grown on demand)
70//! ```
71//!
72//! ## Quick start
73//!
74//! ```rust
75//! use wasm_dbms_memory::prelude::*;
76//!
77//! let mut provider = HeapMemoryProvider::default();
78//! provider.grow(1).unwrap();
79//! provider.write(0, b"hello").unwrap();
80//!
81//! let mut buf = vec![0u8; 5];
82//! provider.read(0, &mut buf).unwrap();
83//! assert_eq!(&buf, b"hello");
84//! ```
85//!
86//! Most users do not interact with this crate directly: the
87//! [`wasm-dbms`](https://crates.io/crates/wasm-dbms) engine consumes a
88//! [`MemoryProvider`] and exposes the higher-level CRUD/transaction
89//! API on top.
90
91#![doc(html_playground_url = "https://play.rust-lang.org")]
92#![doc(
93    html_favicon_url = "https://raw.githubusercontent.com/veeso/wasm-dbms/main/assets/images/cargo/logo-128.png"
94)]
95#![doc(
96    html_logo_url = "https://raw.githubusercontent.com/veeso/wasm-dbms/main/assets/images/cargo/logo-512.png"
97)]
98
99extern crate self as wasm_dbms_memory;
100
101mod acl;
102mod memory_access;
103mod memory_manager;
104mod provider;
105mod schema_registry;
106pub mod table_registry;
107mod unclaimed_pages;
108
109pub use self::acl::{AccessControl, AccessControlList, NoAccessControl};
110pub use self::memory_access::MemoryAccess;
111pub use self::memory_manager::{MemoryManager, RESERVED_PAGES, align_up};
112pub use self::provider::{HeapMemoryProvider, MemoryProvider, WASM_PAGE_SIZE};
113pub use self::schema_registry::{SchemaRegistry, TableRegistryPage};
114pub use self::table_registry::{
115    IndexLedger, IndexTreeWalker, NextRecord, RawRecordBytes, RawTableReader, RecordAddress,
116    TableReader, TableRegistry,
117};
118pub use self::unclaimed_pages::{UNCLAIMED_PAGES_CAPACITY, UnclaimedPages};
119
120/// Prelude re-exports for convenient use.
121pub mod prelude {
122    pub use super::acl::{AccessControl, AccessControlList, NoAccessControl};
123    pub use super::memory_access::MemoryAccess;
124    pub use super::memory_manager::{MemoryManager, RESERVED_PAGES, align_up};
125    pub use super::provider::{HeapMemoryProvider, MemoryProvider, WASM_PAGE_SIZE};
126    pub use super::schema_registry::{SchemaRegistry, TableRegistryPage};
127    pub use super::table_registry::{
128        AutoincrementLedger, IndexLedger, IndexTreeWalker, NextRecord, RawRecordBytes,
129        RawTableReader, RecordAddress, TableReader, TableRegistry,
130    };
131    pub use super::unclaimed_pages::{UNCLAIMED_PAGES_CAPACITY, UnclaimedPages};
132}
wasm_dbms_memory/lib.rs

wasm_dbms_memory/
lib.rs
