Crate wasm_dbms_memory 

wasm-dbms-memory

Runtime-agnostic memory abstraction and page management for the wasm-dbms framework.

This crate sits between the raw byte storage exposed by a WASM runtime (heap, file, IC stable memory, …) and the higher-level DBMS engine. It defines the MemoryProvider trait that abstracts over the storage backend and the on-top-of-it data structures that the engine uses to persist tables, schema, indexes, and access control state.

All structures use 64 KiB pages so the on-disk layout is byte-for-byte identical across providers — a heap-built database can be dumped and reopened as IC stable memory or a WASI file with no conversion.

What this crate provides

Storage backends:

• MemoryProvider — trait every backend implements (read, write, grow, page count).
• HeapMemoryProvider — in-memory provider for tests and embedded use cases.

Access control:

• AccessControl — pluggable access control trait.
• AccessControlList — identity-based per-table permissions persisted on a dedicated page.
• NoAccessControl — zero-overhead provider for runtimes that do not need access control.

Engine-facing data structures:

• MemoryManager — page allocator and low-level read/write helpers. See RESERVED_PAGES for the reserved layout.
• SchemaRegistry — persistent table-schema store backed by TableRegistryPage.
• TableRegistry — record-level storage, free-segment tracking, and read iterators (TableReader, RawTableReader, NextRecord, RecordAddress, RawRecordBytes).
• IndexLedger / IndexTreeWalker — secondary index storage and traversal.
• table_registry::AutoincrementLedger — per-column autoincrement counters.
• UnclaimedPages — free page pool (UNCLAIMED_PAGES_CAPACITY entries per ledger page).
• align_up / WASM_PAGE_SIZE — alignment helpers.

Memory layout

Reserved pages followed by per-table page sets:

+0:  Schema Registry            (1 page)
+1:  ACL Table                  (1 page)
+N:  Per-table Page Ledger      (1 page)
+N:  Per-table Free Segments    (1 page)
+N:  Per-table Record Pages     (grown on demand)

Quick start

use wasm_dbms_memory::prelude::*;

let mut provider = HeapMemoryProvider::default();
provider.grow(1).unwrap();
provider.write(0, b"hello").unwrap();

let mut buf = vec![0u8; 5];
provider.read(0, &mut buf).unwrap();
assert_eq!(&buf, b"hello");

Most users do not interact with this crate directly: the wasm-dbms engine consumes a MemoryProvider and exposes the higher-level CRUD/transaction API on top.

Re-exports

pub use self::table_registry::IndexLedger;

pub use self::table_registry::IndexTreeWalker;

pub use self::table_registry::NextRecord;

pub use self::table_registry::RawRecordBytes;

pub use self::table_registry::RawTableReader;

pub use self::table_registry::RecordAddress;

pub use self::table_registry::TableReader;

pub use self::table_registry::TableRegistry;

Modules

prelude

Prelude re-exports for convenient use.

table_registry

Structs

AccessControlList

Granular access-control list.

HeapMemoryProvider

An implementation of MemoryProvider that uses heap memory for testing purposes.

MemoryManager

The memory manager handles page-level memory operations on top of a MemoryProvider.

NoAccessControl

ACL provider that grants every operation unconditionally.

SchemaRegistry

The schema registry takes care of storing and retrieving table schemas from memory.

TableRegistryPage

The dictionary of tables, mapping the table schema fingerprint to the pages where the table data and metadata are stored.

UnclaimedPages

On-disk representation of the unclaimed-pages ledger.

Constants

RESERVED_PAGES

Number of reserved pages allocated at initialization.

UNCLAIMED_PAGES_CAPACITY

Maximum number of entries that fit in the reserved page (64 KiB).

WASM_PAGE_SIZE

The size of a WASM memory page in bytes (64 KiB).

Traits

AccessControl

Trait for granular access-control providers.

MemoryAccess

Abstraction over page-level memory operations.

MemoryProvider

Memory Provider trait defines the interface for interacting with the underlying memory.

Functions

align_up

Gets the padding at the given offset to the next multiple of [E::ALIGNMENT].