@loro-dev/sqlite-riverrun

Single-node SQLite-backed Durable Streams dev server for local CRDT development.

This package powers loro dev. It provides a scoped local runtime that is protocol-compatible with the agreed Durable Streams subset for:

• stream create / append / read / head / delete
• snapshot locate / read / write
• bootstrap
• long-poll live reads
• SSE live reads, including the binary Riverrun extension

It is intentionally not a production simulator.

Scope

This package is designed for:

• local application development
• protocol integration testing
• CRDT debugging
• lightweight embedded usage from other TypeScript tools

It does not implement:

• auth
• quota or metering
• explicit bucket lifecycle APIs
• multi-node replication
• producer idempotency headers

Semantics

• Buckets are implicit namespaces. PUT /ds/:bucket/:stream creates the bucket namespace as needed.
• Streams have a fixed Content-Type chosen at create time.
• POST may omit Content-Type; when present it must match the stream type.
• Snapshot creation advances the earliest readable offset and forces older reads to return 410 Gone.
• /bootstrap returns multipart/mixed with the snapshot part first, then update parts.

Minimal usage

import { startDevServer } from "@loro-dev/sqlite-riverrun";

const server = await startDevServer({
  host: "127.0.0.1",
  port: 8787,
  dbPath: "./data/dev.sqlite",
});

console.log(server.baseUrl);

await server.close();

Limits and defaults

• SQLite journal mode is forced to WAL.
• Live watch fanout is process-local only.
• Long-poll cursors are opaque and not guaranteed to survive process restarts.
• Stream IDs are validated against the current ds-crdt constraints.