@syncular/server 0.1.2 → 0.2.0

package/dist/sqlite-image.js

@@ -0,0 +1,83 @@
+/**
+ * SQLite-image segment generation (SPEC.md §5.3): a complete SQLite
+ * database file carrying one table's whole effective-scope snapshot at
+ * the bootstrap pin, plus the single-row `_syncular_segment` metadata
+ * table. Built in memory on bun:sqlite — dependency-free.
+ *
+ * Images are NOT byte-deterministic (§5.3): the content address pins the
+ * served bytes, and cross-client dedup comes from the segment store's
+ * metadata lookup (`SegmentStore.find`), not from hash convergence.
+ */
+import { Database } from 'bun:sqlite';
+import { decodeRow } from '@syncular/core';
+/** The §5.6 version column as it appears inside a sqlite image (§5.3). */
+export const IMAGE_VERSION_COLUMN = '_syncular_version';
+/** The §5.3 metadata table name. */
+export const IMAGE_METADATA_TABLE = '_syncular_segment';
+function quoteIdent(name) {
+    return `"${name.replaceAll('"', '""')}"`;
+}
+/** §5.3 column type affinities (string/json/blob_ref TEXT, boolean INTEGER, …). */
+function sqlType(column) {
+    switch (column.type) {
+        case 'string':
+        case 'json':
+        case 'blob_ref':
+            return 'TEXT';
+        case 'integer':
+            return 'INTEGER';
+        case 'float':
+            return 'REAL';
+        case 'boolean':
+            return 'INTEGER';
+        case 'bytes':
+        case 'crdt':
+            // §5.10: a crdt column's opaque bytes ride the BLOB affinity, like
+            // bytes.
+            return 'BLOB';
+        default:
+            throw new Error(`unsupported column type: ${String(column.type)}`);
+    }
+}
+/** §5.3 cell encodings: boolean as 0/1, everything else its natural type. */
+function toSql(value) {
+    if (typeof value === 'boolean')
+        return value ? 1 : 0;
+    return value;
+}
+/** Build the §5.3 image bytes for a whole-table snapshot. */
+export const buildSqliteImage = (input) => {
+    const { table, rows } = input;
+    const primaryKey = table.columns[table.primaryKeyIndex]?.name;
+    const db = new Database(':memory:');
+    try {
+        const columnDefs = table.columns.map((column) => {
+            const notNull = column.nullable ? '' : ' NOT NULL';
+            const pk = column.name === primaryKey ? ' PRIMARY KEY' : '';
+            return `${quoteIdent(column.name)} ${sqlType(column)}${notNull}${pk}`;
+        });
+        columnDefs.push(`${quoteIdent(IMAGE_VERSION_COLUMN)} INTEGER NOT NULL`);
+        db.exec(`CREATE TABLE ${quoteIdent(table.name)} (${columnDefs.join(', ')})`);
+        db.exec(`CREATE TABLE ${IMAGE_METADATA_TABLE} (
+        format INTEGER NOT NULL, "table" TEXT NOT NULL,
+        "schemaVersion" INTEGER NOT NULL, "asOfCommitSeq" INTEGER NOT NULL,
+        "scopeDigest" TEXT NOT NULL, "rowCount" INTEGER NOT NULL)`);
+        db.query(`INSERT INTO ${IMAGE_METADATA_TABLE} VALUES (1, ?, ?, ?, ?, ?)`).run(table.name, input.schemaVersion, input.asOfCommitSeq, input.scopeDigest, rows.length);
+        const names = [
+            ...table.columns.map((column) => quoteIdent(column.name)),
+            quoteIdent(IMAGE_VERSION_COLUMN),
+        ];
+        const insert = db.query(`INSERT INTO ${quoteIdent(table.name)} (${names.join(', ')})
+       VALUES (${names.map(() => '?').join(', ')})`);
+        db.exec('BEGIN');
+        for (const row of rows) {
+            const values = decodeRow(table.columns, row.payload);
+            insert.run(...values.map(toSql), row.serverVersion);
+        }
+        db.exec('COMMIT');
+        return new Uint8Array(db.serialize());
+    }
+    finally {
+        db.close();
+    }
+};

package/dist/sqlite-lease-store.d.ts

@@ -0,0 +1,21 @@
+/**
+ * SQLite-backed auth-lease store via `bun:sqlite` (§7.3.1 reference store,
+ * dependency-free). Bun-specific by design (top-level `bun:sqlite` import),
+ * so it lives in its own module — the runtime-neutral `LeaseStore` interface,
+ * `LeaseRecord`, and `MemoryLeaseStore` stay in `lease-store.ts` for the
+ * Workers/edge core (TODO §4.2 neutrality discipline; enforced by
+ * `test/runtime-neutrality.test.ts`).
+ */
+import { Database } from 'bun:sqlite';
+import type { ScopeMap } from '@syncular/core';
+import type { LeaseIdFactory, LeaseRecord, LeaseStore } from './lease-store.js';
+export declare class SqliteLeaseStore implements LeaseStore {
+    #private;
+    readonly db: Database;
+    constructor(db?: Database | string, options?: {
+        readonly leaseId?: LeaseIdFactory;
+    });
+    get(partition: string, clientId: string): Promise<LeaseRecord | undefined>;
+    issue(partition: string, clientId: string, actorId: string, allowedScopes: ScopeMap, nowMs: number, ttlMs: number): Promise<LeaseRecord>;
+    revoke(partition: string, leaseId: string): Promise<void>;
+}

package/dist/sqlite-lease-store.js

@@ -0,0 +1,94 @@
+/**
+ * SQLite-backed auth-lease store via `bun:sqlite` (§7.3.1 reference store,
+ * dependency-free). Bun-specific by design (top-level `bun:sqlite` import),
+ * so it lives in its own module — the runtime-neutral `LeaseStore` interface,
+ * `LeaseRecord`, and `MemoryLeaseStore` stay in `lease-store.ts` for the
+ * Workers/edge core (TODO §4.2 neutrality discipline; enforced by
+ * `test/runtime-neutrality.test.ts`).
+ */
+import { Database } from 'bun:sqlite';
+function defaultLeaseId() {
+    return `lease_${crypto.randomUUID()}`;
+}
+export class SqliteLeaseStore {
+    db;
+    #newId;
+    constructor(db = ':memory:', options) {
+        this.db = typeof db === 'string' ? new Database(db) : db;
+        this.#newId = options?.leaseId ?? defaultLeaseId;
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS sync_leases(
+        partition TEXT NOT NULL, client_id TEXT NOT NULL,
+        lease_id TEXT NOT NULL, actor_id TEXT NOT NULL,
+        allowed_scopes TEXT NOT NULL,
+        issued_at_ms INTEGER NOT NULL, expires_at_ms INTEGER NOT NULL,
+        revoked INTEGER NOT NULL DEFAULT 0,
+        PRIMARY KEY (partition, client_id)
+      );
+      CREATE TABLE IF NOT EXISTS sync_lease_revocations(
+        partition TEXT NOT NULL, lease_id TEXT NOT NULL,
+        PRIMARY KEY (partition, lease_id)
+      );
+    `);
+    }
+    async get(partition, clientId) {
+        const row = this.db
+            .query(`SELECT lease_id, actor_id, allowed_scopes, issued_at_ms,
+                expires_at_ms, revoked
+         FROM sync_leases WHERE partition=? AND client_id=?`)
+            .get(partition, clientId);
+        if (row === null)
+            return undefined;
+        return {
+            leaseId: row.lease_id,
+            actorId: row.actor_id,
+            allowedScopes: JSON.parse(row.allowed_scopes),
+            issuedAtMs: row.issued_at_ms,
+            expiresAtMs: row.expires_at_ms,
+            revoked: row.revoked !== 0,
+        };
+    }
+    #isRevoked(partition, leaseId) {
+        const row = this.db
+            .query('SELECT 1 AS n FROM sync_lease_revocations WHERE partition=? AND lease_id=?')
+            .get(partition, leaseId);
+        return row !== null;
+    }
+    async issue(partition, clientId, actorId, allowedScopes, nowMs, ttlMs) {
+        const existing = await this.get(partition, clientId);
+        const reuse = existing !== undefined &&
+            existing.actorId === actorId &&
+            !existing.revoked &&
+            !this.#isRevoked(partition, existing.leaseId);
+        const leaseId = reuse ? existing.leaseId : this.#newId();
+        const record = {
+            leaseId,
+            actorId,
+            allowedScopes,
+            issuedAtMs: nowMs,
+            expiresAtMs: nowMs + ttlMs,
+            revoked: false,
+        };
+        this.db
+            .query(`INSERT INTO sync_leases(
+          partition, client_id, lease_id, actor_id, allowed_scopes,
+          issued_at_ms, expires_at_ms, revoked
+        ) VALUES (?,?,?,?,?,?,?,0)
+        ON CONFLICT(partition, client_id) DO UPDATE SET
+          lease_id=excluded.lease_id, actor_id=excluded.actor_id,
+          allowed_scopes=excluded.allowed_scopes,
+          issued_at_ms=excluded.issued_at_ms,
+          expires_at_ms=excluded.expires_at_ms, revoked=0`)
+            .run(partition, clientId, leaseId, actorId, JSON.stringify(allowedScopes), nowMs, record.expiresAtMs);
+        return record;
+    }
+    async revoke(partition, leaseId) {
+        this.db
+            .query(`INSERT OR IGNORE INTO sync_lease_revocations(partition, lease_id)
+         VALUES (?,?)`)
+            .run(partition, leaseId);
+        this.db
+            .query('UPDATE sync_leases SET revoked=1 WHERE partition=? AND lease_id=?')
+            .run(partition, leaseId);
+    }
+}

package/dist/sqlite-segment-store.d.ts

@@ -0,0 +1,25 @@
+/**
+ * SQLite-backed segment store via `bun:sqlite` (dev/bench convenience,
+ * dependency-free). Bun-specific by design: it imports `bun:sqlite` at the
+ * top level, so it lives in its own module — importing it opts into the Bun
+ * runtime. The runtime-neutral `SegmentStore` interface, `MemorySegmentStore`,
+ * and `segmentIdFor` stay in `segment-store.ts` so the Workers/edge core can
+ * import them without pulling in `bun:sqlite` (TODO §4.2 neutrality
+ * discipline; enforced by `test/runtime-neutrality.test.ts`).
+ */
+import { Database } from 'bun:sqlite';
+import { type SegmentFindKey, type SegmentMetadata, type SegmentRecord, type SegmentStore, type SegmentStoreStats } from './segment-store.js';
+export declare class SqliteSegmentStore implements SegmentStore {
+    #private;
+    readonly db: Database;
+    constructor(db?: Database | string, options?: {
+        ttlMs?: number;
+    });
+    put(metadata: SegmentMetadata, bytes: Uint8Array, nowMs: number): Promise<SegmentRecord>;
+    get(segmentId: string): Promise<{
+        record: SegmentRecord;
+        bytes: Uint8Array;
+    } | undefined>;
+    find(key: SegmentFindKey, nowMs: number): Promise<SegmentRecord | undefined>;
+    stats(): Promise<SegmentStoreStats>;
+}

package/dist/sqlite-segment-store.js

@@ -0,0 +1,115 @@
+/**
+ * SQLite-backed segment store via `bun:sqlite` (dev/bench convenience,
+ * dependency-free). Bun-specific by design: it imports `bun:sqlite` at the
+ * top level, so it lives in its own module — importing it opts into the Bun
+ * runtime. The runtime-neutral `SegmentStore` interface, `MemorySegmentStore`,
+ * and `segmentIdFor` stay in `segment-store.ts` so the Workers/edge core can
+ * import them without pulling in `bun:sqlite` (TODO §4.2 neutrality
+ * discipline; enforced by `test/runtime-neutrality.test.ts`).
+ */
+import { Database } from 'bun:sqlite';
+import { DEFAULT_SEGMENT_TTL_MS, segmentIdFor, } from './segment-store.js';
+export class SqliteSegmentStore {
+    db;
+    #ttlMs;
+    constructor(db = ':memory:', options) {
+        this.db = typeof db === 'string' ? new Database(db) : db;
+        this.#ttlMs = options?.ttlMs ?? DEFAULT_SEGMENT_TTL_MS;
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS sync_segments(
+        segment_id TEXT PRIMARY KEY, partition TEXT NOT NULL,
+        tbl TEXT NOT NULL, schema_version INTEGER NOT NULL,
+        media_type TEXT NOT NULL, scope_digest TEXT NOT NULL,
+        as_of_commit_seq INTEGER NOT NULL, row_count INTEGER NOT NULL,
+        row_cursor TEXT, next_row_cursor TEXT,
+        byte_length INTEGER NOT NULL, created_at_ms INTEGER NOT NULL,
+        expires_at_ms INTEGER NOT NULL, bytes BLOB NOT NULL
+      );
+    `);
+    }
+    async put(metadata, bytes, nowMs) {
+        const segmentId = await segmentIdFor(bytes);
+        const record = {
+            ...metadata,
+            segmentId,
+            byteLength: bytes.length,
+            createdAtMs: nowMs,
+            expiresAtMs: nowMs + this.#ttlMs,
+        };
+        this.db
+            .query(`INSERT OR REPLACE INTO sync_segments(
+          segment_id, partition, tbl, schema_version, media_type,
+          scope_digest, as_of_commit_seq, row_count, row_cursor,
+          next_row_cursor, byte_length, created_at_ms, expires_at_ms, bytes
+        ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)`)
+            .run(record.segmentId, record.partition, record.table, record.schemaVersion, record.mediaType, record.scopeDigest, record.asOfCommitSeq, record.rowCount, record.rowCursor, record.nextRowCursor, record.byteLength, record.createdAtMs, record.expiresAtMs, bytes);
+        return record;
+    }
+    async get(segmentId) {
+        const row = this.db
+            .query('SELECT * FROM sync_segments WHERE segment_id=?')
+            .get(segmentId);
+        if (row === null)
+            return undefined;
+        return {
+            record: {
+                segmentId: row.segment_id,
+                partition: row.partition,
+                table: row.tbl,
+                schemaVersion: row.schema_version,
+                mediaType: row.media_type === 'sqlite' ? 'sqlite' : 'rows',
+                scopeDigest: row.scope_digest,
+                asOfCommitSeq: row.as_of_commit_seq,
+                rowCount: row.row_count,
+                rowCursor: row.row_cursor,
+                nextRowCursor: row.next_row_cursor,
+                byteLength: row.byte_length,
+                createdAtMs: row.created_at_ms,
+                expiresAtMs: row.expires_at_ms,
+            },
+            bytes: new Uint8Array(row.bytes),
+        };
+    }
+    async find(key, nowMs) {
+        const row = this.db
+            .query(`SELECT segment_id, row_count, next_row_cursor, byte_length,
+                created_at_ms, expires_at_ms
+         FROM sync_segments
+         WHERE partition=? AND tbl=? AND schema_version=? AND media_type=?
+           AND scope_digest=? AND as_of_commit_seq=? AND row_cursor IS NULL
+           AND expires_at_ms > ?
+         LIMIT 1`)
+            .get(key.partition, key.table, key.schemaVersion, key.mediaType, key.scopeDigest, key.asOfCommitSeq, nowMs);
+        if (row === null)
+            return undefined;
+        return {
+            segmentId: row.segment_id,
+            partition: key.partition,
+            table: key.table,
+            schemaVersion: key.schemaVersion,
+            mediaType: key.mediaType,
+            scopeDigest: key.scopeDigest,
+            asOfCommitSeq: key.asOfCommitSeq,
+            rowCount: row.row_count,
+            rowCursor: null,
+            nextRowCursor: row.next_row_cursor,
+            byteLength: row.byte_length,
+            createdAtMs: row.created_at_ms,
+            expiresAtMs: row.expires_at_ms,
+        };
+    }
+    async stats() {
+        const row = this.db
+            .query(`SELECT count(*) AS count, sum(byte_length) AS bytes,
+                sum(CASE WHEN media_type='sqlite' THEN 0 ELSE 1 END) AS rows_segments,
+                sum(CASE WHEN media_type='sqlite' THEN 1 ELSE 0 END) AS sqlite_segments
+         FROM sync_segments`)
+            .get();
+        return {
+            count: row?.count ?? 0,
+            bytes: row?.bytes ?? 0,
+            rowsSegments: row?.rows_segments ?? 0,
+            sqliteSegments: row?.sqlite_segments ?? 0,
+        };
+    }
+}

package/dist/sqlite-storage.d.ts

@@ -0,0 +1,47 @@
+/**
+ * SQLite storage via `bun:sqlite` (dev-speed, dependency-free).
+ *
+ * Scope fanout is index-first (REVISE B2): both the commit log and the
+ * current-row table carry a (table, variable, value) inverted index; reads
+ * select candidates from the index and verify the full multi-variable
+ * match against the stored scope map — never a log scan.
+ */
+import { Database } from 'bun:sqlite';
+import type { CompiledSchema, CompiledTable } from './schema.js';
+import type { ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, StorageTransaction, StoredCommit, StoredPushResult, StoredRow } from './storage.js';
+export declare class SqliteServerStorage implements ServerStorage {
+    #private;
+    readonly db: Database;
+    constructor(db?: Database | string);
+    /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
+    table(name: string): CompiledTable;
+    ensureSchema(schema: CompiledSchema): Promise<void>;
+    begin(partition: string): Promise<StorageTransaction>;
+    /** Internal: write a row + refresh its scope-index entries. */
+    writeRow(partition: string, table: string, row: StoredRow): void;
+    getMaxCommitSeq(partition: string): Promise<number>;
+    getHorizonSeq(partition: string): Promise<number>;
+    setHorizonSeq(partition: string, seq: number): Promise<void>;
+    pruneCommitsThrough(partition: string, seq: number): Promise<number>;
+    getCommitSeqBefore(partition: string, createdBeforeMs: number): Promise<number>;
+    getRow(partition: string, table: string, rowId: string): Promise<StoredRow | undefined>;
+    getPushResult(partition: string, clientId: string, clientCommitId: string): Promise<StoredPushResult | undefined>;
+    readCommitWindow(partition: string, query: CommitWindowQuery): Promise<StoredCommit[]>;
+    scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]>;
+    getClientRecord(partition: string, clientId: string): Promise<ClientRecord | undefined>;
+    putClientRecord(partition: string, record: ClientRecord): Promise<void>;
+    listClientCursors(partition: string): Promise<ClientCursorInfo[]>;
+    listRowsReferencingBlob(partition: string, blobId: string): Promise<{
+        readonly table: string;
+        readonly rowId: string;
+        readonly scopes: Record<string, string>;
+    }[]>;
+    listReferencedBlobIds(partition: string): Promise<string[]>;
+    listClientRecords(partition: string): Promise<ClientRecord[]>;
+    listCommitMetadata(partition: string, query: CommitMetadataQuery): Promise<CommitMetadata[]>;
+    scopeActivity(partition: string, query: ScopeActivityQuery): Promise<ScopeCommitActivity[]>;
+    getRowScopes(partition: string, table: string, rowId: string): Promise<{
+        serverVersion: number;
+        scopes: Record<string, string>;
+    } | undefined>;
+}