@syncular/server 0.34.0 → 0.36.0

package/dist/blob-handlers.js

@@ -189,12 +189,19 @@ async function downloadBlob(ctx, blobId) {
         // Unreachable: presign not configured ⇒ `entry` was loaded above.
         throw syncError('blob.not_found', 'blob bytes unavailable (§5.9.5)');
     }
-    // §5.9.5: inline bytes are always octet-stream. The stored media type
-    // would make a JSON blob indistinguishable from the signed-URL envelope.
+    // §5.9.5: inline bytes carry the stored media type, so an <img> or <a>
+    // pointed at the route renders them. A JSON type stays octet-stream: a
+    // JSON body is reserved for the signed-URL envelope.
+    const mediaType = entry?.record.mediaType;
     return {
         bytes,
         headers: {
-            'Content-Type': 'application/octet-stream',
+            'Content-Type': mediaType === undefined ||
+                mediaType.toLowerCase().includes('application/json')
+                ? 'application/octet-stream'
+                : mediaType,
+            'X-Content-Type-Options': 'nosniff',
+            'Content-Security-Policy': "sandbox; default-src 'none'",
             ETag: `"${blobId}"`,
             'Cache-Control': 'private, max-age=0',
             Vary: 'Authorization, Accept-Encoding',

package/dist/blob-store.d.ts

@@ -37,7 +37,9 @@ export interface BlobStoreStats {
 export interface BlobStore {
     /**
      * Store blob bytes under `blobId` (idempotent — same id ⇒ no-op success,
-     * §5.9.3). The caller has already verified the content address matches.
+     * §5.9.3). A re-upload that declares a media type records it on a blob
+     * stored without one; a recorded media type never changes. The caller has
+     * already verified the content address matches.
      */
     put(partition: string, blobId: string, bytes: Uint8Array, nowMs: number, mediaType?: string): Promise<BlobRecord>;
     /** Presence check for the push existence rule (§5.9.6) and download. */
@@ -53,6 +55,11 @@ export interface BlobStore {
      * Returns the deleted blobIds.
      */
     sweepOrphans(partition: string, olderThanMs: number, referencedBlobIds: ReadonlySet<string>): Promise<string[]>;
+    /**
+     * §4.6.1 erasure: delete one blob whose last reference is gone. Deleting a
+     * missing blob is a no-op.
+     */
+    delete(partition: string, blobId: string): Promise<void>;
     /** Admin/console counters (work item §2.5) — ADDITIVE, optional. */
     stats?(partition: string): Promise<BlobStoreStats>;
 }
@@ -68,6 +75,7 @@ export declare class MemoryBlobStore implements BlobStore {
         bytes: Uint8Array;
     } | undefined>;
     sweepOrphans(partition: string, olderThanMs: number, referencedBlobIds: ReadonlySet<string>): Promise<string[]>;
+    delete(partition: string, blobId: string): Promise<void>;
     stats(partition: string): Promise<BlobStoreStats>;
 }
 export interface SweepOrphanBlobsOptions {

package/dist/bucket-blob-store.d.ts

@@ -51,6 +51,7 @@ export declare class BucketBlobStore implements BlobStore {
      */
     objectKeyFor(partition: string, blobId: string): string;
     put(partition: string, blobId: string, bytes: Uint8Array, nowMs: number, mediaType?: string): Promise<BlobRecord>;
+    delete(partition: string, blobId: string): Promise<void>;
     has(partition: string, blobId: string): Promise<boolean>;
     get(partition: string, blobId: string): Promise<{
         record: BlobRecord;

package/dist/bucket-blob-store.js

@@ -141,25 +141,28 @@ export class BucketBlobStore {
         // blob once, and preserve the FIRST createdAtMs so the sweep's grace clock
         // is not reset by a re-upload (§5.9.2 upload age).
         const preexisting = await this.#bucket.head(objectKey);
-        if (preexisting !== undefined) {
-            const meta = preexisting.metadata[BLOB_META_KEY];
-            if (meta !== undefined) {
-                const existing = parseMetaJson(base64urlToUtf8(meta), blobId, this.#label);
-                return {
-                    blobId,
-                    partition,
-                    byteLength: existing.byteLength,
-                    ...(existing.mediaType !== undefined
-                        ? { mediaType: existing.mediaType }
-                        : {}),
-                    createdAtMs: existing.createdAtMs,
-                };
-            }
+        const storedMeta = preexisting?.metadata[BLOB_META_KEY];
+        const existing = storedMeta === undefined
+            ? undefined
+            : parseMetaJson(base64urlToUtf8(storedMeta), blobId, this.#label);
+        if (existing !== undefined &&
+            (existing.mediaType !== undefined || mediaType === undefined)) {
+            return {
+                blobId,
+                partition,
+                byteLength: existing.byteLength,
+                ...(existing.mediaType !== undefined
+                    ? { mediaType: existing.mediaType }
+                    : {}),
+                createdAtMs: existing.createdAtMs,
+            };
         }
+        // A re-upload that names the media type an earlier upload left out
+        // rewrites the object under the same precondition, keeping its age.
         const meta = {
             byteLength: bytes.length,
             ...(mediaType !== undefined ? { mediaType } : {}),
-            createdAtMs: nowMs,
+            createdAtMs: existing?.createdAtMs ?? nowMs,
         };
         // Conditional write: of two concurrent uploads of the same blob exactly
         // one lands, so the first createdAtMs survives and the blob counts once.
@@ -176,7 +179,10 @@ export class BucketBlobStore {
             return this.put(partition, blobId, bytes, nowMs, mediaType);
         if (preexisting === undefined)
             await this.#bumpStats({ count: 1, bytes: bytes.length });
-        return record;
+        return { ...record, createdAtMs: meta.createdAtMs };
+    }
+    async delete(partition, blobId) {
+        await this.#bucket.delete(this.objectKeyFor(partition, blobId));
     }
     async has(partition, blobId) {
         if (!BLOB_ID_PATTERN.test(blobId))

package/dist/d1-storage.d.ts

@@ -42,7 +42,7 @@ import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
  */
 import { type ScopeMap } from '@syncular/core';
 import type { CompiledSchema, CompiledTable } from './schema.js';
-import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientPushResult, ClientRecord, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, ServeGate, StorageTransaction, StoredCommit, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
+import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientPushResult, ClientRecord, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, ServerStorage, ServeGate, StorageTransaction, StoredCommit, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
 export interface D1PreparedStatement {
     bind(...values: unknown[]): D1PreparedStatement;
     first<T = Record<string, unknown>>(): Promise<T | null>;
@@ -134,6 +134,8 @@ export declare class D1ServerStorage implements ServerStorage {
         readonly scopes: Record<string, string>;
     }[]>;
     listReferencedBlobIds(partition: string): Promise<string[]>;
+    listScopeValueRows(partition: string, query: ScopeValueQuery): Promise<string[]>;
+    eraseScopeValueHistory(partition: string, query: ScopeValueHistoryQuery): Promise<number>;
     listClientRecords(partition: string): Promise<ClientRecord[]>;
     listCommitMetadata(partition: string, query: CommitMetadataQuery): Promise<CommitMetadata[]>;
     getCommit(partition: string, commitSeq: number): Promise<CommitDetail | undefined>;

package/dist/d1-storage.js

@@ -47,7 +47,7 @@ import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './author
 import { syncError } from './errors.js';
 import { assertAppendOnlyMigration, assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, SYNC_COLUMN_VERSIONS_COLUMN, SYNC_PARTITION_COLUMN, SYNC_PAYLOAD_COLUMN, SYNC_ROW_ID_COLUMN, SYNC_SCOPES_COLUMN, SYNC_VERSION_COLUMN, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, tableColumnNames, toSqlValue, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
-import { asUint8Array, collectCommitWindowPage, deserializePushResult, placeholders, serializePushResult, sqliteDdlStatements, toStoredChange, toStoredRow, } from './sqlite-dialect.js';
+import { asUint8Array, collectCommitWindowPage, deserializePushResult, placeholders, ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL, eraseScopeValueHistoryParams, LIST_SCOPE_VALUE_ROWS_SQLITE_SQL, serializePushResult, sqliteDdlStatements, toStoredChange, toStoredRow, } from './sqlite-dialect.js';
 import { isD1ConstraintError, StorageConstraintError } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
 function toStoredReaction(record) {
@@ -1654,6 +1654,30 @@ export class D1ServerStorage {
             .all();
         return results.map((r) => r.blob_id);
     }
+    async listScopeValueRows(partition, query) {
+        const { results } = await this.#db
+            .prepare(LIST_SCOPE_VALUE_ROWS_SQLITE_SQL)
+            .bind(partition, query.table, query.variable, query.value, query.limit)
+            .all();
+        return results.map((row) => row.row_id);
+    }
+    async eraseScopeValueHistory(partition, query) {
+        if (!this.#pushApplySerialized)
+            throw new Error('D1 erasure requires externally serialized partition writes');
+        const params = eraseScopeValueHistoryParams(partition, query);
+        const results = await this.#db.batch(ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL.map((sql) => this.#db.prepare(sql).bind(...params)));
+        let removed = 0;
+        for (const result of results) {
+            if (typeof result !== 'object' ||
+                result === null ||
+                !('results' in result) ||
+                !Array.isArray(result.results)) {
+                throw new Error('D1 erasure returned an invalid batch result');
+            }
+            removed += result.results.length;
+        }
+        return removed;
+    }
     // -- admin/console read surface --------------------------------------------
     async listClientRecords(partition) {
         const { results } = await this.#db

package/dist/erase.d.ts

@@ -0,0 +1,28 @@
+import { type SyncServerConfig } from './context.js';
+export interface EraseScopeValueOptions {
+    readonly partition: string;
+    /** The scope variable as declared by the schema's scope patterns. */
+    readonly variable: string;
+    readonly value: string;
+    /**
+     * Rows deleted per call, and change records removed per table per call
+     * (default 200, at most the push operation cap).
+     */
+    readonly maxRows?: number;
+    /** Actor recorded on the erasure commits (default `syncular.erase`). */
+    readonly actorId?: string;
+}
+export interface EraseScopeValueResult {
+    /** Rows the erasure commit of this call deleted. */
+    readonly rowsErased: number;
+    /** The erasure commit of this call, when it deleted rows. */
+    readonly commitSeq?: number;
+    /** Change log records this call removed. */
+    readonly historyErased: number;
+    /** Blobs whose last reference this call removed; their bytes are gone. */
+    readonly blobsErased: readonly string[];
+    /** Nothing of the binding is left; further calls change nothing. */
+    readonly done: boolean;
+}
+/** Erase one scope binding of one partition, one budgeted step per call. */
+export declare function eraseScopeValue(config: SyncServerConfig, options: EraseScopeValueOptions): Promise<EraseScopeValueResult>;

package/dist/erase.js

@@ -0,0 +1,122 @@
+/**
+ * Scope-value erasure (SPEC.md §4.6.1): remove every row whose stored scope
+ * binds one variable to one value, the upsert change records that carried
+ * those rows, and the blob bytes no remaining row references.
+ *
+ * Live rows leave through one ordinary delete commit per call, applied on
+ * the shared push path (partition lock, tombstones, blob reference index,
+ * realtime fanout). The commit advances the binding's scoped change seq, so
+ * no cached segment taken before the erasure is reused, and every client
+ * holding the rows receives the deletes. Once no live row is left, each call
+ * scrubs the change log of the binding. Hosts loop until `done`.
+ */
+import { decodeRow } from '@syncular/core';
+import { limitsOf } from './context.js';
+import { SyncError } from './errors.js';
+import { blobIdsInRow, processPushOperationsWithTrace } from './push.js';
+import { compileSchema } from './schema.js';
+import { StorageQueryError } from './storage-errors.js';
+/** Erase one scope binding of one partition, one budgeted step per call. */
+export async function eraseScopeValue(config, options) {
+    const { storage } = config;
+    const { partition, variable, value } = options;
+    const maxRows = options.maxRows ?? 200;
+    const listRows = storage.listScopeValueRows?.bind(storage);
+    const eraseHistory = storage.eraseScopeValueHistory?.bind(storage);
+    const listReferences = storage.listRowsReferencingBlob?.bind(storage);
+    if (listRows === undefined ||
+        eraseHistory === undefined ||
+        listReferences === undefined) {
+        throw new StorageQueryError('sync.storage.erase_unsupported');
+    }
+    const schema = compileSchema(config.schema);
+    const tables = [...schema.tables.values()].filter((table) => table.scopePatterns.some((pattern) => pattern.variable === variable));
+    if (tables.length === 0 ||
+        value.length === 0 ||
+        !Number.isSafeInteger(maxRows) ||
+        maxRows < 1 ||
+        maxRows > limitsOf(config).maxOperationsPerRequest) {
+        throw new StorageQueryError('sync.storage.invalid_erase_query');
+    }
+    if ((await storage.getPartitionLogEpoch(partition)) === undefined) {
+        return { rowsErased: 0, historyErased: 0, blobsErased: [], done: true };
+    }
+    await storage.ensureSchema(schema, config.checkpoints);
+    const targets = [];
+    for (const table of tables) {
+        const limit = maxRows - targets.length;
+        if (limit === 0)
+            break;
+        const query = { table: table.name, variable, value, limit };
+        for (const rowId of await listRows(partition, query)) {
+            targets.push({ table: table.name, rowId });
+        }
+    }
+    if (targets.length > 0) {
+        // Erasure is the operator's act: app validators do not gate it.
+        const { validators, commitValidator, ...trusted } = config;
+        const blobIds = new Set();
+        let rowsErased = 0;
+        const processed = await processPushOperationsWithTrace({ ...trusted, partition, actorId: options.actorId ?? 'syncular.erase' }, schema, {
+            ok: true,
+            allowed: Object.fromEntries([...schema.tables.values()].flatMap((table) => table.scopePatterns.map((pattern) => [pattern.variable, ['*']]))),
+        }, 'syncular.erase', crypto.randomUUID(), async (tx) => {
+            const operations = [];
+            for (const target of targets) {
+                // Re-read under the partition lock: a row may have moved or gone.
+                const stored = await tx.getRow(target.table, target.rowId);
+                if (stored?.scopes[variable] !== value)
+                    continue;
+                const table = schema.tables.get(target.table);
+                for (const blobId of blobIdsInRow(table, decodeRow(table.columns, stored.payload))) {
+                    blobIds.add(blobId);
+                }
+                operations.push({
+                    table: target.table,
+                    op: 'delete',
+                    rowId: target.rowId,
+                });
+            }
+            rowsErased = operations.length;
+            return operations;
+        });
+        const { frame } = processed;
+        if (frame.status !== 'applied') {
+            const failed = frame.results.find((result) => 'code' in result);
+            throw failed !== undefined && 'code' in failed
+                ? new SyncError(failed.code, failed.message)
+                : new Error('eraseScopeValue: the erasure commit was not applied');
+        }
+        const blobsErased = [];
+        for (const blobId of blobIds) {
+            if ((await listReferences(partition, blobId)).length > 0)
+                continue;
+            await config.blobs?.delete(partition, blobId);
+            blobsErased.push(blobId);
+        }
+        return {
+            rowsErased,
+            ...(frame.commitSeq !== undefined ? { commitSeq: frame.commitSeq } : {}),
+            historyErased: 0,
+            blobsErased,
+            done: false,
+        };
+    }
+    const throughSeq = await storage.getMaxCommitSeq(partition);
+    let historyErased = 0;
+    for (const table of tables) {
+        historyErased += await eraseHistory(partition, {
+            table: table.name,
+            variable,
+            value,
+            throughSeq,
+            limit: maxRows,
+        });
+    }
+    return {
+        rowsErased: 0,
+        historyErased,
+        blobsErased: [],
+        done: historyErased === 0,
+    };
+}

package/dist/index.d.ts

@@ -17,6 +17,7 @@ export * from './content-encoding.js';
 export * from './context.js';
 export * from './crdt-merger.js';
 export * from './d1-storage.js';
+export * from './erase.js';
 export * from './errors.js';
 export * from './events.js';
 export * from './events-ring.js';

package/dist/index.js

@@ -17,6 +17,7 @@ export * from './content-encoding.js';
 export * from './context.js';
 export * from './crdt-merger.js';
 export * from './d1-storage.js';
+export * from './erase.js';
 export * from './errors.js';
 export * from './events.js';
 export * from './events-ring.js';

package/dist/postgres-storage.d.ts

@@ -39,7 +39,7 @@ import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
 import type { ScopeMap } from '@syncular/core';
 import { type PgExecutor } from './pg-executor.js';
 import type { CompiledSchema, CompiledTable } from './schema.js';
-import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientPushResult, ClientRecord, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, ServeGate, StorageTransaction, StoredCheckpoint, StoredCommit, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
+import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientPushResult, ClientRecord, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, ServerStorage, ServeGate, StorageTransaction, StoredCheckpoint, StoredCommit, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
 /**
  * Schema DDL. Applied by `PostgresServerStorage.migrate()` (idempotent).
  *
@@ -73,7 +73,13 @@ export declare const POSTGRES_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partition
 export declare class PostgresServerStorage implements ServerStorage {
     #private;
     constructor(exec: PgExecutor);
-    /** Apply the schema DDL (idempotent). Call once before use. */
+    /**
+     * Apply the schema DDL (idempotent). Call once before use. The last
+     * statement records a fingerprint of the applied DDL as the comment of
+     * `sync_schema_meta`; a database that carries the current fingerprint
+     * costs one catalog read instead of the DDL round trips, so a new storage
+     * instance (a Worker isolate, a Durable Object wake) starts fast.
+     */
     migrate(): Promise<void>;
     /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
     table(name: string): CompiledTable;
@@ -134,6 +140,8 @@ export declare class PostgresServerStorage implements ServerStorage {
         readonly scopes: Record<string, string>;
     }[]>;
     listReferencedBlobIds(partition: string): Promise<string[]>;
+    listScopeValueRows(partition: string, query: ScopeValueQuery): Promise<string[]>;
+    eraseScopeValueHistory(partition: string, query: ScopeValueHistoryQuery): Promise<number>;
     listClientRecords(partition: string): Promise<ClientRecord[]>;
     listCommitMetadata(partition: string, query: CommitMetadataQuery): Promise<CommitMetadata[]>;
     getCommit(partition: string, commitSeq: number): Promise<CommitDetail | undefined>;