Struct Runtime 

pub struct Runtime { /* private fields */ }

A minimal runtime that executes CRUD operations against a SQLite database based on a manifest contract.

In WAL mode SQLite allows one writer and multiple concurrent readers. This struct exploits that by keeping a single write connection behind a mutex and a pool of read-only connections that can be acquired in parallel, so read operations never block on (or are blocked by) writes.

Implementations

impl Runtime

pub fn open(db_path: &str, manifest: AppManifest) -> Result<Self, RuntimeError>

Open a runtime against an existing SQLite database.

pub fn is_in_memory(&self) -> bool

Returns true if this runtime is backed by an in-memory SQLite DB.

Stored at open time rather than queried via conn.path() because the path-based check conflates “no filename” with “in-memory”: Connection::open("") yields a file-backed DB with empty path, and would falsely pass as in-memory. Since we always know at construction time which constructor was used, track the bit.

Gates the test-reset endpoint — a false positive here would let /api/__test__/reset truncate real tables.

pub fn db_path(&self) -> Option<String>

Filesystem path to the SQLite database, if this runtime is file-backed. Returns None for in-memory runtimes. Used by the server bootstrap to derive companion paths (session store, change log persistence) without requiring the caller to pass them in.

pub fn reset_for_tests(&self) -> Result<(), RuntimeError>

Drop every row from every entity table. Intended for test harnesses that call /api/__test__/reset between cases; refuses to run on anything but an in-memory database.

Does NOT drop the tables themselves — schema stays, indexes stay, triggers stay. Just truncates user data + the change log.

pub fn in_memory(manifest: AppManifest) -> Result<Self, RuntimeError>

Create an in-memory runtime (useful for tests and benchmarks).

pub fn ensure_search_indexes(&self) -> Result<(), RuntimeError>

Create the search index tables (_facet_bitmap, per-entity _fts_<Entity>, and a covering index for each declared sortable field) for every searchable entity in the manifest.

Production deployments do this via the storage adapter’s apply_schema / migration plan; that path also handles adding/removing the tables when a search: block is added or removed across deploys. This method is a quick path for tests and benchmarks that build a Runtime::in_memory(...) directly without going through the schema-plan pipeline.

pub fn manifest(&self) -> &AppManifest

Return a reference to the app manifest.

pub fn lock_conn_pub(&self) -> Result<MutexGuard<'_, Connection>, RuntimeError>

Expose the write connection mutex for transactional operations.

pub fn read_pool_size(&self) -> usize

Return the number of read connections in the pool (0 for in-memory DBs).

pub fn crdt_store(&self) -> &LoroStore

Borrow the CRDT store. Tests use this to inspect cache state and the WS handler will use it to fetch snapshots on subscribe.

pub fn insert(&self, entity: &str, data: &Value) -> Result<String, RuntimeError>

Insert a new row. Returns the generated ID.

For entities with crdt: true (the default) the LoroDoc snapshot

• the SQLite materialized row are committed together in a single SQLite transaction so a crash between the two leaves neither. crdt: false entities skip the LoroDoc and use a direct write (legacy LWW path). Both produce the same on-disk row shape, so reads, indexes, FTS, and policies don’t change between modes.

pub fn get_by_id( &self, entity: &str, id: &str, ) -> Result<Option<Value>, RuntimeError>

Get a single row by ID.

pub fn list(&self, entity: &str) -> Result<Vec<Value>, RuntimeError>

List all rows for an entity.

pub fn list_after( &self, entity: &str, after: Option<&str>, limit: usize, ) -> Result<Vec<Value>, RuntimeError>

List rows after a cursor ID (for cursor-based pagination).

pub fn update( &self, entity: &str, id: &str, data: &Value, ) -> Result<bool, RuntimeError>

Update a row by ID. Returns true if a row was found and updated.

For entities with crdt: true (the default) the LoroDoc receives the patch first; the SQLite UPDATE writes the same fields so the materialized view stays in lockstep with the doc state.

pub fn delete(&self, entity: &str, id: &str) -> Result<bool, RuntimeError>

Delete a row by ID. Returns true if a row was actually deleted.

pub fn lookup( &self, entity: &str, field: &str, value: &str, ) -> Result<Option<Value>, RuntimeError>

Lookup a single row by a field value (e.g., email).

pub fn link( &self, entity: &str, id: &str, relation: &str, target_id: &str, ) -> Result<bool, RuntimeError>

Link two entities by setting a foreign-key field.

pub fn unlink( &self, entity: &str, id: &str, relation: &str, ) -> Result<bool, RuntimeError>

Unlink a relation by setting the foreign-key field to null.

pub fn query_filtered( &self, entity: &str, filter: &Value, ) -> Result<Vec<Value>, RuntimeError>

Execute a filtered query with operators ($not, $gt, $in, $like, $order, $limit).

pub fn query_graph(&self, query: &Value) -> Result<Value, RuntimeError>

Execute a graph-style query.

Input: { "User": { "where": { "email": "..." }, "include": { "posts": {} } } } Returns nested results following relations.

pub fn insert_with_conn( &self, conn: &Connection, entity: &str, data: &Value, ) -> Result<String, RuntimeError>

Insert using an already-locked connection (for transactions).

pub fn update_with_conn( &self, conn: &Connection, entity: &str, id: &str, data: &Value, ) -> Result<bool, RuntimeError>

Update using an already-locked connection (for transactions).

pub fn delete_with_conn( &self, conn: &Connection, entity: &str, id: &str, ) -> Result<bool, RuntimeError>

Delete using an already-locked connection (for transactions).

pub fn get_by_id_with_conn( &self, conn: &Connection, entity: &str, id: &str, ) -> Result<Option<Value>, RuntimeError>

Read a row by id using a pre-held connection (for transactions).

pub fn list_with_conn( &self, conn: &Connection, entity: &str, ) -> Result<Vec<Value>, RuntimeError>

List rows using a pre-held connection (for transactions).

pub fn list_after_with_conn( &self, conn: &Connection, entity: &str, after: Option<&str>, limit: usize, ) -> Result<Vec<Value>, RuntimeError>

List after cursor using a pre-held connection (for transactions).

pub fn lookup_with_conn( &self, conn: &Connection, entity: &str, field: &str, value: &str, ) -> Result<Option<Value>, RuntimeError>

Lookup by field using a pre-held connection (for transactions).

pub fn link_with_conn( &self, conn: &Connection, entity: &str, id: &str, relation: &str, target_id: &str, ) -> Result<bool, RuntimeError>

Link relation using a pre-held connection (for transactions).

pub fn unlink_with_conn( &self, conn: &Connection, entity: &str, id: &str, relation: &str, ) -> Result<bool, RuntimeError>

Unlink relation using a pre-held connection (for transactions).

pub fn query_filtered_with_conn( &self, conn: &Connection, entity: &str, filter: &Value, ) -> Result<Vec<Value>, RuntimeError>

Query with filters using a pre-held connection (for transactions).

Shares the filter-building logic with [query_filtered] by executing against the provided connection rather than acquiring one.

pub fn query_graph_with_conn( &self, conn: &Connection, query: &Value, ) -> Result<Value, RuntimeError>

Graph query using a pre-held connection (for transactions).

pub fn aggregate( &self, entity: &str, spec: &Value, ) -> Result<Value, RuntimeError>

Run an aggregation query. See pylon_http::DataStore::aggregate for the spec shape.

Trait Implementations

impl DataStore for Runtime

fn search(&self, entity: &str, query: &Value) -> Result<Value, DataError>

Bridge the typed SearchQuery / SearchResult shapes to the trait’s JSON-in / JSON-out contract. The router passes a JSON body; we deserialize, look up the entity’s SearchConfig, run the planner, and re-serialize. Serialization round-tripping lets this method live on the DataStore trait without forcing pylon-http to depend on pylon-storage.

fn crdt_snapshot( &self, entity: &str, row_id: &str, ) -> Result<Option<Vec<u8>>, DataError>

Return the binary CRDT snapshot for a row. Ok(None) for any entity with crdt: false (the LWW opt-out) — the router uses that to decide whether to ship a binary update over WebSocket after the write.

fn crdt_apply_update( &self, entity: &str, row_id: &str, update: &[u8], ) -> Result<Vec<u8>, DataError>

Client-pushed Loro update. Imports into the row’s LoroDoc, re-projects the doc state into the materialized SQLite columns (so subsequent reads see the merged content), and returns the fresh full-row snapshot for the router to broadcast to other clients.

Wrapped in a single SQLite transaction — same crash-safety shape as Runtime::insert/update. Either the LoroStore + SQLite columns both update or neither does.

fn manifest(&self) -> &AppManifest

fn insert(&self, entity: &str, data: &Value) -> Result<String, DataError>

fn get_by_id(&self, entity: &str, id: &str) -> Result<Option<Value>, DataError>

fn list(&self, entity: &str) -> Result<Vec<Value>, DataError>

fn list_after( &self, entity: &str, after: Option<&str>, limit: usize, ) -> Result<Vec<Value>, DataError>

fn update( &self, entity: &str, id: &str, data: &Value, ) -> Result<bool, DataError>

fn delete(&self, entity: &str, id: &str) -> Result<bool, DataError>

fn lookup( &self, entity: &str, field: &str, value: &str, ) -> Result<Option<Value>, DataError>

fn link( &self, entity: &str, id: &str, relation: &str, target_id: &str, ) -> Result<bool, DataError>

fn unlink( &self, entity: &str, id: &str, relation: &str, ) -> Result<bool, DataError>

fn query_filtered( &self, entity: &str, filter: &Value, ) -> Result<Vec<Value>, DataError>

fn query_graph(&self, query: &Value) -> Result<Value, DataError>

fn aggregate(&self, entity: &str, spec: &Value) -> Result<Value, DataError>

Run an aggregation query.

fn transact(&self, ops: &[Value]) -> Result<(bool, Vec<Value>), DataError>

Execute transactional operations. Each element is a JSON object with op (“insert”/“update”/“delete”), entity, and optionally id/data.