Crate elastik_core

Expand description

§Elastik — Audi-ted L5 Storage Engine

elastik-core is a protocol-neutral storage engine: canonical paths, opaque bytes, content-addressed versioning, an HMAC-chained audit log, and a four-tier access model. SQLite for files.

§Quick start

use elastik_core::{
    AccessTier, Engine, Preconditions, Representation, SecretBytes, ValidatedWorldPath,
};
use bytes::Bytes;

let engine = Engine::builder()
    .data_root("./data")
    .key(SecretBytes::new(b"shared-hmac-secret".to_vec()).expect("hmac key"))
    .build()
    .expect("engine builds");

let world = ValidatedWorldPath::new("home/hello").expect("canonical path");

// Store bytes at a path.
engine
    .replace(
        &world,
        Representation::new(Bytes::from_static(b"hi"), "text/plain", Vec::new()),
        Preconditions::none(),
        AccessTier::Write,
    )
    .await
    .expect("write succeeds");

// Retrieve bytes by path.
let read = engine.read(&world, AccessTier::Read).expect("read succeeds");
assert!(read.is_some());

§What the library does

Bytes at paths. Canonical home/, tmp/, dev/, sys/, etc/, lib/, boot/, usr/, var/ namespaces decide durable-vs-transient without per-call configuration.
Versions everything. Every successful write returns an ETag; reads, replaces, and appends honour Preconditions::if_match / if_none_match.
Audits everything. HMAC-chained ledger; Engine::verify_audit returns a typed AuditVerify result and refuses to start when an existing chain is corrupted.
Authenticates everything. AccessTier (Anon / Read / Write / Approve) plus token-bytes verification via Engine::verify_token.
Subscribes to changes. Engine::subscribe returns an EngineSubscription with replay-then-live ordering.

§What the library does not do

No protocol adapters and no server runtime. Those live in the elastik-bin package’s elastik-core binary and consume this library through the unstable public Engine API. In a minimal library-only build, the library does not read environment variables, does not bind sockets, and does not depend on protocol-adapter transport crates.

§Feature flags

bundled-sqlite (default) — link a bundled SQLite via rusqlite/bundled.
unstable-engine — expose the public Engine facade. The API shape is allowed to change between minor versions while this gate stays.

Binary adapter features such as coap, mqtt, and multi-thread live in bin/Cargo.toml, not in this library package.

Minimal library-only build from the repository root: cargo build --manifest-path core/Cargo.toml --lib --no-default-features --features bundled-sqlite,unstable-engine.

Structs§

AuditBroken: Audit-chain break details.
AuditValid: Successful audit-chain verification details.
ChangeEvent: Protocol-neutral change event delivered to subscribers.
DeleteMetadata: Metadata recorded with a delete audit intent.
DfSnapshot: Aggregate storage/memory snapshot.
EmptyKeyError: Returned when a secret key constructor receives an empty or all-whitespace byte string.
Engine: Public handle for the protocol-neutral Elastik engine.
EngineBuilder: Builder for an Engine.
EngineSubscription: Subscription to protocol-neutral engine change events.
InvalidProcPath: Returned when a string is not one of Engine’s known proc endpoints.
InvalidWorldPath: Returned when a world key cannot be represented as an Engine world.
PoolSnapshot: Read-cache + ledger-writer snapshot.
Preconditions: Protocol-neutral write preconditions.
ReadResult: Result of a successful full-representation read.
Representation: Stored representation passed to write operations.
SecretBytes: HMAC key material for the audit chain.
SubscribePattern: Normalized subscription pattern matching the existing /listen/* grammar.
ValidatedProcPath: Validated /proc/* introspection endpoint.
ValidatedWorldPath: Canonical world key that passed Engine path validation.
WorldUsage: One world-size row for engine introspection.
WriteResult: Result of a successful write.

Enums§

AccessTier: Access tier granted to a caller after token verification.
AuditVerify: Result of crate::Engine::verify_audit.
AuthGate
ChangeVerb: Kind of storage mutation that produced a change event.
EngineBuildError: Errors that can occur while constructing an Engine.
EngineError: Runtime operation errors reported by the Engine facade.
EtagMatcher: ETag matcher parsed by adapters before calling the engine.
ProcEndpoint: Stable proc endpoint identity carried by ValidatedProcPath.
SubscriptionRecvError: Error returned by EngineSubscription::recv.
WriteKind: Whether a write created a new world or updated an existing one.

Constants§

DEFAULT_LISTEN_REPLAY_MAX
DEFAULT_MAX_LISTEN_CONNECTIONS
DEFAULT_MAX_MEMORY_BYTES
DEFAULT_MAX_WORLD_BYTES
DEFAULT_READ_CACHE_MAX_ENTRIES
NAMESPACE_PREFIXES: Canonical Engine world namespaces.

Traits§

EngineDeleteTraceHooks: Trace hooks for Engine::delete_traced’s intent/delete/commit protocol.
EngineWriteTraceHooks: Trace hooks for Engine::replace_traced / Engine::append_traced.

Functions§

is_valid_token: Returns true when raw token bytes can represent a configured or candidate Engine token.
validate_world_name: Returns the specific rejection reason so adapters can surface precise diagnostics instead of a blanket invalid-path error.