@syncular/client 0.1.2 → 0.2.0

package/dist/blob.js

@@ -0,0 +1,201 @@
+/**
+ * Client-side blob cache + transport (SPEC.md §5.9.7).
+ *
+ * Blob bytes are cached content-addressed by `blobId` and refcounted by the
+ * local rows whose `blob_ref` columns reference them (B1). The cache is
+ * derived from live-row references: after any apply/purge, refcounts are
+ * reconciled from the current `blob_ref` column contents, and a body whose
+ * only referencing rows were revocation-purged is deleted (B2, evicted ≠
+ * revoked). BlobRefs stay resolvable at any time (B3): the `blobId` in the
+ * row value is the whole download key. Pending uploads are tracked in the
+ * outbox-adjacent uploads table (B4) and flushed before push.
+ */
+import { parseBlobRef, serializeBlobRef } from '@syncular/core';
+import { quoteIdent } from './schema.js';
+/** `"sha256:" + hex` of the bytes — the content address (§5.9.1). */
+export async function computeBlobId(bytes) {
+    const digest = await crypto.subtle.digest('SHA-256', bytes.slice().buffer);
+    const hex = [...new Uint8Array(digest)]
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+    return `sha256:${hex}`;
+}
+export function ensureBlobSchema(db) {
+    db.exec(`CREATE TABLE IF NOT EXISTS _syncular_blobs(
+    blob_id TEXT PRIMARY KEY,
+    bytes BLOB NOT NULL,
+    byte_length INTEGER NOT NULL,
+    media_type TEXT,
+    refcount INTEGER NOT NULL DEFAULT 0,
+    created_at_ms INTEGER NOT NULL,
+    last_used_ms INTEGER NOT NULL DEFAULT 0)`);
+    // Migrate a cache created before the §5.9.7 B1 LRU column: additive,
+    // idempotent (a duplicate-column error on an already-migrated DB is
+    // swallowed). last_used_ms drives cap eviction (LRU of zero-ref bodies).
+    try {
+        db.exec('ALTER TABLE _syncular_blobs ADD COLUMN last_used_ms INTEGER NOT NULL DEFAULT 0');
+    }
+    catch {
+        // column already exists — the CREATE above included it
+    }
+    db.exec(`CREATE TABLE IF NOT EXISTS _syncular_blob_uploads(
+    blob_id TEXT PRIMARY KEY,
+    media_type TEXT,
+    created_at_ms INTEGER NOT NULL)`);
+}
+/** Put bytes into the content-addressed cache (idempotent); touches LRU. */
+export function putCachedBlob(db, blobId, bytes, nowMs, mediaType) {
+    db.exec(`INSERT INTO _syncular_blobs(
+       blob_id, bytes, byte_length, media_type, refcount, created_at_ms, last_used_ms)
+     VALUES (?,?,?,?,0,?,?)
+     ON CONFLICT(blob_id) DO UPDATE SET last_used_ms = excluded.last_used_ms`, [blobId, bytes, bytes.length, mediaType ?? null, nowMs, nowMs]);
+}
+export function getCachedBlob(db, blobId, nowMs) {
+    const rows = db.query('SELECT bytes, byte_length, media_type FROM _syncular_blobs WHERE blob_id = ?', [blobId]);
+    const row = rows[0];
+    if (row === undefined)
+        return undefined;
+    // §5.9.7 B1 LRU: a cache-hit read touches "recently used" so a hot image
+    // survives a cap trim. Skipped when no clock is supplied (pure read).
+    if (nowMs !== undefined) {
+        db.exec('UPDATE _syncular_blobs SET last_used_ms = ? WHERE blob_id = ?', [
+            nowMs,
+            blobId,
+        ]);
+    }
+    return {
+        blobId,
+        bytes: row.bytes,
+        byteLength: Number(row.byte_length),
+        ...(row.media_type !== null ? { mediaType: row.media_type } : {}),
+    };
+}
+/**
+ * §5.9.7 B1 size cap + LRU eviction. When the sum of cached body sizes exceeds
+ * `maxBytes`, evict **zero-ref, non-pinned** bodies in least-recently-used
+ * order until back under the cap. NEVER evicts a referenced body (refcount > 0
+ * — it must stay resolvable without a re-download) nor a pending-upload-pinned
+ * body (its bytes are the only copy until push, B4). If every over-cap body is
+ * referenced or pinned, the cache stays over the cap (correctness beats the
+ * cap). Evicting a zero-ref body is always safe: B3 re-enables the fetch from
+ * any surviving `blob_ref` value. Returns the evicted blobIds.
+ */
+export function enforceBlobCacheCap(db, maxBytes) {
+    const totalRow = db.query('SELECT COALESCE(SUM(byte_length), 0) AS total FROM _syncular_blobs')[0];
+    let total = Number(totalRow?.total ?? 0);
+    if (total <= maxBytes)
+        return [];
+    // Eviction candidates: zero-ref AND not pinned by a pending upload, oldest
+    // (LRU) first, then oldest created as a stable tiebreak.
+    const candidates = db.query(`SELECT blob_id, byte_length FROM _syncular_blobs
+     WHERE refcount = 0
+       AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)
+     ORDER BY last_used_ms ASC, created_at_ms ASC`);
+    const evicted = [];
+    db.transaction(() => {
+        for (const row of candidates) {
+            if (total <= maxBytes)
+                break;
+            const blobId = row.blob_id;
+            db.exec('DELETE FROM _syncular_blobs WHERE blob_id = ?', [blobId]);
+            total -= Number(row.byte_length);
+            evicted.push(blobId);
+        }
+    });
+    return evicted;
+}
+/** Record a pending upload (§5.9.7 B4); flushed before the next push. */
+export function recordPendingUpload(db, blobId, nowMs, mediaType) {
+    db.exec(`INSERT OR IGNORE INTO _syncular_blob_uploads(blob_id, media_type, created_at_ms)
+     VALUES (?,?,?)`, [blobId, mediaType ?? null, nowMs]);
+}
+export function listPendingUploads(db) {
+    return db
+        .query('SELECT blob_id, media_type FROM _syncular_blob_uploads ORDER BY created_at_ms')
+        .map((row) => ({
+        blobId: row.blob_id,
+        ...(row.media_type !== null
+            ? { mediaType: row.media_type }
+            : {}),
+    }));
+}
+export function clearPendingUpload(db, blobId) {
+    db.exec('DELETE FROM _syncular_blob_uploads WHERE blob_id = ?', [blobId]);
+}
+/**
+ * All `blob_ref` column names per table (for refcount reconciliation).
+ * Blank result ⇒ the schema has no attachments; callers skip reconciliation.
+ */
+export function blobRefColumnsBySchema(schema) {
+    const out = new Map();
+    for (const table of schema.tables.values()) {
+        const cols = table.columns
+            .filter((c) => c.type === 'blob_ref')
+            .map((c) => c.name);
+        if (cols.length > 0)
+            out.set(table.name, cols);
+    }
+    return out;
+}
+export function schemaHasBlobs(schema) {
+    for (const table of schema.tables.values()) {
+        if (table.columns.some((c) => c.type === 'blob_ref'))
+            return true;
+    }
+    return false;
+}
+/**
+ * §5.9.7 B1/B2: recompute cache refcounts from the current `blob_ref` column
+ * contents across all synced tables, then delete cache bodies that dropped
+ * to zero refs *and* have no pending upload (a pending upload pins its body,
+ * B4). Called after every apply/purge that may add or remove references.
+ *
+ * `deleteOrphans` distinguishes the two B2 transitions: revocation purge
+ * passes `true` (drop the now-unauthorized body); a benign apply passes
+ * `false` (retain zero-ref bodies as LRU cache entries — the shipped
+ * default). Bodies pinned by a pending upload are always retained.
+ */
+export function reconcileBlobRefcounts(db, schema, options) {
+    const byTable = blobRefColumnsBySchema(schema);
+    if (byTable.size === 0)
+        return;
+    // Count references to each blobId across every blob_ref column.
+    const counts = new Map();
+    for (const [tableName, columns] of byTable) {
+        for (const column of columns) {
+            const rows = db.query(`SELECT ${quoteIdent(column)} AS v FROM ${quoteIdent(tableName)}
+         WHERE ${quoteIdent(column)} IS NOT NULL`);
+            for (const row of rows) {
+                const raw = row.v;
+                if (typeof raw !== 'string')
+                    continue;
+                let ref;
+                try {
+                    ref = parseBlobRef(raw);
+                }
+                catch {
+                    continue;
+                }
+                counts.set(ref.blobId, (counts.get(ref.blobId) ?? 0) + 1);
+            }
+        }
+    }
+    db.transaction(() => {
+        // Reset all refcounts, then apply the recomputed counts.
+        db.exec('UPDATE _syncular_blobs SET refcount = 0');
+        for (const [blobId, count] of counts) {
+            db.exec('UPDATE _syncular_blobs SET refcount = ? WHERE blob_id = ?', [
+                count,
+                blobId,
+            ]);
+        }
+        if (options?.deleteOrphans === true) {
+            // §5.9.7 B2 revocation side: delete zero-ref bodies not pinned by a
+            // pending upload.
+            db.exec(`DELETE FROM _syncular_blobs
+         WHERE refcount = 0
+           AND blob_id NOT IN (SELECT blob_id FROM _syncular_blob_uploads)`);
+        }
+    });
+}
+export { parseBlobRef, serializeBlobRef };

package/dist/bun-database.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `ClientDatabase` on bun:sqlite — the test backend (REVISE B3: the core
+ * must run without a browser). Not exported from the package root so the
+ * browser entry never touches `bun:sqlite`.
+ */
+import { Database } from 'bun:sqlite';
+import { type ClientDatabase, type SqlRow, type SqlValue } from './database.js';
+export declare class BunClientDatabase implements ClientDatabase {
+    #private;
+    readonly db: Database;
+    constructor(path?: string);
+    exec(sql: string, params?: readonly SqlValue[]): void;
+    query(sql: string, params?: readonly SqlValue[]): SqlRow[];
+    transaction<T>(fn: () => T): T;
+    /**
+     * §5.3 image import: bun:sqlite attaches files, not buffers, so the
+     * image lands in a private temp file for the duration of the ATTACH.
+     */
+    withSqliteImage<T>(bytes: Uint8Array, alias: string, fn: () => T): T;
+    close(): void;
+}
+export declare function openBunDatabase(path?: string): ClientDatabase;

package/dist/bun-database.js

@@ -0,0 +1,61 @@
+/**
+ * `ClientDatabase` on bun:sqlite — the test backend (REVISE B3: the core
+ * must run without a browser). Not exported from the package root so the
+ * browser entry never touches `bun:sqlite`.
+ */
+import { Database } from 'bun:sqlite';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { assertImageAlias, runTransaction, } from './database.js';
+function coerceParams(params) {
+    return params.map((value) => {
+        if (typeof value === 'boolean')
+            return value ? 1 : 0;
+        return value;
+    });
+}
+export class BunClientDatabase {
+    db;
+    #tx = { depth: 0 };
+    constructor(path = ':memory:') {
+        this.db = new Database(path);
+    }
+    exec(sql, params = []) {
+        this.db.query(sql).run(...coerceParams(params));
+    }
+    query(sql, params = []) {
+        return this.db.query(sql).all(...coerceParams(params));
+    }
+    transaction(fn) {
+        return runTransaction(this.#tx, (sql) => this.db.run(sql), fn);
+    }
+    /**
+     * §5.3 image import: bun:sqlite attaches files, not buffers, so the
+     * image lands in a private temp file for the duration of the ATTACH.
+     */
+    withSqliteImage(bytes, alias, fn) {
+        assertImageAlias(alias);
+        const dir = mkdtempSync(join(tmpdir(), 'syncular-image-'));
+        const path = join(dir, 'segment.db');
+        try {
+            writeFileSync(path, bytes);
+            this.db.run(`ATTACH DATABASE ? AS ${alias}`, [path]);
+            try {
+                return fn();
+            }
+            finally {
+                this.db.run(`DETACH DATABASE ${alias}`);
+            }
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    }
+    close() {
+        this.db.close();
+    }
+}
+export function openBunDatabase(path = ':memory:') {
+    return new BunClientDatabase(path);
+}