obj_core/lib.rs
1//! `obj-core` — internal storage engine for the `obj` embedded document
2//! database.
3//!
4//! # ⚠️ UNSTABLE — not a stable public API
5//!
6//! `obj-core` is an **implementation detail of `obj-db`**. It is published
7//! to `crates.io` only because `obj-db` depends on it; its public API carries
8//! **no `SemVer` guarantee** and may change in any release, including patch
9//! releases. Do not depend on `obj-core` directly — depend on `obj-db` and
10//! use the `obj` crate's API. Only `obj-db`'s public surface is frozen at
11//! 1.0 (see `docs/public-api.md`); `obj-core` is deliberately excluded from
12//! the public-api freeze gate so the engine can evolve freely.
13//!
14//! This crate hosts the layered storage engine: the platform syscall
15//! wrappers (L0), the pager (L1), the WAL (L2), the B-tree (L3), the
16//! document codec (L4), the catalog (L5), and the transaction manager
17//! (L7). Layers are built bottom-up across milestones; see the project
18//! plan and `power-of-ten.md` for the design discipline this crate
19//! must uphold.
20//!
21//! # On-disk format
22//!
23//! The `.obj` file format that this crate reads and writes is specified
24//! in `docs/format.md` at the repository root. That document is the
25//! authoritative description of the page-0 file header, the per-page
26//! CRC32C trailer scheme, and the page-type tag enumeration; this
27//! crate is its reference implementation.
28//!
29//! # `unsafe` policy
30//!
31//! This crate does **not** carry a crate-level `#![forbid(unsafe_code)]`
32//! because the `platform` submodule holds the project's syscall
33//! wrappers. Every other submodule should be safe; new submodules
34//! SHOULD include `#![forbid(unsafe_code)]` of their own where
35//! appropriate.
36
37#![deny(missing_docs)]
38#![deny(rustdoc::broken_intra_doc_links)]
39
40pub mod backup;
41pub mod btree;
42pub mod catalog;
43pub mod codec;
44#[cfg(feature = "encryption")]
45pub mod crypto;
46pub mod error;
47pub mod id;
48pub mod index;
49pub mod integrity;
50pub mod pager;
51pub mod platform;
52pub mod txn;
53pub mod wal;
54
55pub use crate::catalog::{Catalog, CollectionDescriptor, IndexDescriptor, IndexStatus};
56pub use crate::codec::Document;
57pub use crate::error::{Error, LockKind, Result};
58pub use crate::id::Id;
59pub use crate::index::{IndexKind, IndexSpec};
60pub use crate::integrity::{IntegrityFailure, IntegrityReport};
61pub use crate::pager::{CompressionMode, PageHandle, ReaderSnapshot, SnapshotId};
62pub use crate::platform::{FileBackend, SyncMode};
63pub use crate::txn::{ReadTxn, TxnEnv, WriteTxn, DEFAULT_BUSY_TIMEOUT};
64pub use crate::wal::Lsn;