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 {
            body: Bytes::from_static(b"hi"),
            content_type: "text/plain".into(),
            headers: 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 HTTP, no CoAP, no SSE, no server runtime. Those live in the elastik-core binary and consume this library through the unstable public Engine API. The library does not read environment variables, does not bind sockets, and does not depend on axum, hyper, tower, tokio-stream, futures-util, or base64 in a default-feature build.

§Feature flags

bundled-sqlite (default) — link a bundled SQLite via rusqlite/bundled.
coap (default) — enable the CoAP adapter inside the binary.
multi-thread (default) — enable Tokio’s multi-thread runtime for the binary.
unstable-engine — expose the public Engine facade. The API shape is allowed to change between minor versions while this gate stays.
unstable-engine-bin (default) — superset that adds axum, base64, futures-util, Tokio net/signal, and tracing-subscriber; the elastik-core binary requires this feature.

Minimal library-only build: cargo build --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
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.

Traits§

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