spacedb_sdk/
lib.rs

1#![forbid(unsafe_code)]
2//! # spacedb-sdk — the developer's whole world
3//!
4//! One surface over the entire SpaceDB stack. You [`open`](Database::open) an
5//! offline-first local replica, [`define`](Database::define) a [`Schema`] where
6//! each field declares its [`CrdtType`] and consistency [`Tier`], and run ops that
7//! are **mID-authorized**, **budget-bounded**, and **honest** — every write and
8//! read returns the [`Outcome`] it actually achieved (`Local`, `Committed{tier}`,
9//! `Stale{lag}`, `Unavailable{reason}`). Strong-tier fields go through a quorum
10//! that fails safe under partition; reactive [`Watcher`]s and CRDT
11//! [`export`](Database::export)/[`import`](Database::import) sync round it out.
12//!
13//! ```no_run
14//! use spacedb_sdk::{Database, Schema, CrdtType, Tier, Identity};
15//!
16//! let owner = Identity::generate("did:mata:owner").unwrap();
17//! let mut db = Database::open(Identity::generate("did:mata:home-1").unwrap());
18//! db.register_identity(&owner).unwrap();
19//! db.define(
20//!     Schema::new("profile")
21//!         .field("bio", CrdtType::Text, Tier::Convergent)
22//!         .field("username", CrdtType::Register, Tier::Strong),
23//! );
24//! ```
25//!
26//! Open-core (MIT). Composes `spacedb-crdt`, `-access`, `-consistency`, `-meter`.
27
28
29/// The pure-Rust global allocator, installed process-wide.
30///
31/// Present with the **default** `rusty-alloc` feature. SpaceDB is a distributed
32/// database whose replicas routinely run on machines their operator does not
33/// control, so the allocator is part of the failure surface, not an
34/// implementation detail: a double free **aborts** instead of corrupting the
35/// heap, and the tree carries no C allocator. An unconfigured node should be the
36/// hardened one, so this is opt-**out**:
37///
38/// ```toml
39/// spacedb-sdk = { version = "0.5", default-features = false }  # bring your own
40/// spacedb-sdk = { version = "0.5", features = ["secure"] }     # + guard pages
41/// ```
42///
43/// Disabling it removes `rusty_alloc` from the dependency graph entirely, not
44/// merely from a `cfg`, leaving you free to declare your own.
45///
46/// ## If you are writing a LIBRARY that depends on this crate
47///
48/// Set `default-features = false`. A program may contain exactly **one**
49/// `#[global_allocator]`, and Cargo features are **additive across the whole
50/// dependency graph** — a library that pulled this crate with defaults on would
51/// impose this allocator on every application downstream, and any application
52/// that had already chosen its own would fail to build with
53/// `the #[global_allocator] in this crate conflicts with global allocator in:
54/// spacedb_sdk`, which it could not fix from its own manifest.
55#[cfg(feature = "rusty-alloc")]
56#[global_allocator]
57static GLOBAL: rusty_alloc_api::RustyAlloc = rusty_alloc_api::RustyAlloc;
58
59/// Whether this build installed `rusty_alloc` as the global allocator.
60///
61/// Worth logging at node startup: the allocator is a deployment property, and a
62/// property you cannot observe is one you cannot verify.
63pub const fn rusty_alloc_enabled() -> bool {
64    cfg!(feature = "rusty-alloc")
65}
66
67/// Whether the hardened `secure` profile (guard pages, encrypted free lists) is
68/// compiled in.
69pub const fn secure_allocator_enabled() -> bool {
70    cfg!(feature = "secure")
71}
72
73mod schema;
74pub use schema::{CrdtType, FieldSpec, Schema};
75
76mod error;
77pub use error::{SdkError, SdkResult};
78
79mod session;
80pub use session::Session;
81
82mod db;
83pub use db::Database;
84
85// Re-export the stack types a developer composes with, so one `use` line suffices.
86pub use spacedb_access::{
87    Capability, Did, Identity, MemKeyDirectory, Ops, RevocationSet, Scope, SignedCapability,
88};
89pub use spacedb_consistency::{Outcome, RejectReason, StrongResult, Tier, UnavailableReason};
90pub use spacedb_crdt::Watcher;
91pub use spacedb_meter::Budget;
92
93/// Compiles the README's examples as doctests, so the documented API can never
94/// drift from the real one. Not part of the public API, and not rendered into
95/// the crate docs — it exists only under `cargo test --doc`.
96#[cfg(doctest)]
97#[doc = include_str!("../README.md")]
98pub struct ReadmeDoctests;
spacedb_sdk/lib.rs

spacedb_sdk/
lib.rs
