@syncular/server 0.21.1 → 0.22.0

package/src/segment-store.ts

@@ -24,13 +24,229 @@ export interface SegmentMetadata {
   readonly nextRowCursor: string | null;
 }
 
+/**
+ * One publication of a content address (§5.1): the full descriptor context
+ * that authorized the bytes plus that publication's own cache lifetime.
+ * Identical bytes have one content address, so one stored entry carries one
+ * publication per distinct (partition, logEpoch, table, schemaVersion,
+ * mediaType, scopeDigest, asOfCommitSeq, cursors) context it was published
+ * under. Authorization selects a matching publication; it never unions
+ * digests across a different partition or epoch.
+ */
+export interface SegmentPublication extends SegmentMetadata {
+  readonly byteLength: number;
+  readonly createdAtMs: number;
+  readonly expiresAtMs: number;
+}
+
 export interface SegmentRecord extends SegmentMetadata {
   readonly segmentId: string;
+  /**
+   * Every scope digest this content was published under (§3.5), primary
+   * first. A compatibility view over `publications`; download and `find`
+   * authorize on a matching publication, not on this union.
+   */
+  readonly scopeDigests: readonly string[];
+  /** Every publication of this content address, oldest first (§5.1). */
+  readonly publications: readonly SegmentPublication[];
   readonly byteLength: number;
   readonly createdAtMs: number;
   readonly expiresAtMs: number;
 }
 
+/** Canonical identity of one publication; two equal keys are one grant. */
+export function publicationKey(metadata: SegmentMetadata): string {
+  return JSON.stringify([
+    metadata.partition,
+    metadata.logEpoch,
+    metadata.table,
+    metadata.schemaVersion,
+    metadata.mediaType,
+    metadata.scopeDigest,
+    metadata.asOfCommitSeq,
+    metadata.rowCursor,
+    metadata.nextRowCursor,
+  ]);
+}
+
+/**
+ * Materialize publications for a record written before provenance existed
+ * (in-flight 0.21 objects, §5.1). Only the merged top-level context is
+ * known, so each recorded digest is one publication under it: that is the
+ * old single-record read behavior preserved verbatim.
+ */
+export function publicationsForRecord(
+  record: SegmentMetadata & {
+    readonly scopeDigests: readonly string[];
+    readonly byteLength: number;
+    readonly createdAtMs: number;
+    readonly expiresAtMs: number;
+  },
+): SegmentPublication[] {
+  return record.scopeDigests.map((scopeDigest) => ({
+    partition: record.partition,
+    logEpoch: record.logEpoch,
+    table: record.table,
+    schemaVersion: record.schemaVersion,
+    mediaType: record.mediaType,
+    scopeDigest,
+    asOfCommitSeq: record.asOfCommitSeq,
+    rowCount: record.rowCount,
+    rowCursor: record.rowCursor,
+    nextRowCursor: record.nextRowCursor,
+    byteLength: record.byteLength,
+    createdAtMs: record.createdAtMs,
+    expiresAtMs: record.expiresAtMs,
+  }));
+}
+
+/**
+ * The newest publication matching a context, or undefined (§5.5). Optional
+ * `nowMs` skips publications whose own TTL has elapsed, so an expired
+ * `asOf`/schema publication never shadows a newer live one.
+ */
+export interface SegmentPublicationSelector {
+  readonly partition: string;
+  readonly logEpoch: string;
+  readonly scopeDigest: string;
+  readonly table?: string;
+  readonly schemaVersion?: number;
+  readonly mediaType?: 'rows' | 'sqlite';
+  readonly asOfCommitSeq?: number;
+  readonly rowCursor?: string | null;
+  readonly nowMs?: number;
+}
+
+export function selectSegmentPublication(
+  record: SegmentRecord,
+  context: SegmentPublicationSelector,
+): SegmentPublication | undefined {
+  for (let index = record.publications.length - 1; index >= 0; index--) {
+    const publication = record.publications[index]!;
+    if (
+      publication.partition === context.partition &&
+      publication.logEpoch === context.logEpoch &&
+      publication.scopeDigest === context.scopeDigest &&
+      (context.table === undefined || publication.table === context.table) &&
+      (context.schemaVersion === undefined ||
+        publication.schemaVersion === context.schemaVersion) &&
+      (context.mediaType === undefined ||
+        publication.mediaType === context.mediaType) &&
+      (context.asOfCommitSeq === undefined ||
+        publication.asOfCommitSeq === context.asOfCommitSeq) &&
+      (context.rowCursor === undefined ||
+        publication.rowCursor === context.rowCursor) &&
+      (context.nowMs === undefined || publication.expiresAtMs > context.nowMs)
+    ) {
+      return publication;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Project a record onto one publication. The compatibility view is narrowed
+ * to that grant: `scopeDigests` and `publications` hold only the chosen
+ * publication, so a caller that authorizes from them cannot union a grant
+ * from a different partition or epoch.
+ */
+export function publicationRecord(
+  record: SegmentRecord,
+  publication: SegmentPublication,
+): SegmentRecord {
+  return {
+    ...record,
+    ...publication,
+    scopeDigests: [publication.scopeDigest],
+    publications: [publication],
+  };
+}
+
+/** Byte equality for the content-address collision check (§5.1). */
+export function segmentBytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * Merge one publication into the stored entry for the same content address
+ * (§5.1). Identical bytes are one entry: the record takes the incoming
+ * publication's metadata (a later publisher's descriptor, scope digest, and
+ * cursors stay consistent with what it just published), the scope digests
+ * union with the incoming digest first (the record's primary `scopeDigest`),
+ * `createdAtMs` keeps the earliest sighting, and `expiresAtMs` takes the
+ * later expiry. A publication with the incoming context merges into that
+ * publication's own lifetime; a publication with a new context is appended,
+ * so no context's grant is overwritten or extended by another. Publications
+ * whose own TTL has elapsed at `nowMs` are pruned from the stored entry —
+ * SPEC §5.5 lets the cache forget expired grants, and pruning on put keeps
+ * the publication set bounded by live contexts instead of by every context
+ * ever seen. Callers MUST have proven the bytes identical first.
+ */
+export function mergeSegmentRecord(
+  existing: SegmentRecord | undefined,
+  metadata: SegmentMetadata,
+  segmentId: string,
+  byteLength: number,
+  nowMs: number,
+  ttlMs: number,
+): SegmentRecord {
+  // Prune grants that have already elapsed at this write (§5.5): bounded by
+  // live contexts, not by the unbounded set of contexts ever published.
+  const prior = (existing?.publications ?? []).filter(
+    (publication) => publication.expiresAtMs > nowMs,
+  );
+  const fresh: SegmentPublication = {
+    ...metadata,
+    byteLength,
+    createdAtMs: nowMs,
+    expiresAtMs: nowMs + ttlMs,
+  };
+  const key = publicationKey(metadata);
+  const at = prior.findIndex(
+    (publication) => publicationKey(publication) === key,
+  );
+  // Re-publication of one context merges that publication's lifetime only:
+  // an unrelated refresh must not extend another publication's grant (§5.1).
+  const publications =
+    at < 0
+      ? [...prior, fresh]
+      : prior.map((publication, index) =>
+          index === at
+            ? {
+                ...fresh,
+                createdAtMs: Math.min(publication.createdAtMs, nowMs),
+                expiresAtMs: Math.max(publication.expiresAtMs, nowMs + ttlMs),
+              }
+            : publication,
+        );
+  return {
+    ...metadata,
+    segmentId,
+    // Compatibility view over the retained publications only, incoming
+    // primary first: a pruned publication's digest is gone, not just its
+    // descriptor.
+    scopeDigests: [
+      metadata.scopeDigest,
+      ...new Set(
+        publications
+          .map((publication) => publication.scopeDigest)
+          .filter((digest) => digest !== metadata.scopeDigest),
+      ),
+    ],
+    publications,
+    byteLength,
+    createdAtMs: Math.min(existing?.createdAtMs ?? nowMs, nowMs),
+    expiresAtMs: Math.max(
+      existing?.expiresAtMs ?? nowMs + ttlMs,
+      nowMs + ttlMs,
+    ),
+  };
+}
+
 /**
  * The §5.3 reuse key: sqlite images are not byte-deterministic, so
  * cross-client dedup is a metadata lookup, not hash convergence — one
@@ -81,6 +297,14 @@ export interface SegmentStore {
    * Unexpired record for the §5.3 reuse key (whole-table segments only:
    * `rowCursor` null), or undefined. Servers MUST reuse instead of
    * rebuilding sqlite images while one exists (§5.3).
+   *
+   * The digest matches when it is one of the record's `scopeDigests`
+   * (§5.1). That cannot hand a sqlite image to the wrong digest: a sqlite
+   * image embeds its `scopeDigest` in its bytes, and a merge requires byte
+   * equality, so two images published under different digests are never
+   * byte-identical and never share one entry. Only rows segments merge
+   * across digests, and their bytes carry no digest for a reader to compare
+   * against the descriptor.
    */
   find(key: SegmentFindKey, nowMs: number): Promise<SegmentRecord | undefined>;
   /** Admin/console counters: ADDITIVE, optional. */
@@ -105,13 +329,20 @@ export class MemorySegmentStore implements SegmentStore {
     nowMs: number,
   ): Promise<SegmentRecord> {
     const segmentId = await segmentIdFor(bytes);
-    const record: SegmentRecord = {
-      ...metadata,
+    const existing = this.#entries.get(segmentId);
+    if (existing !== undefined && !segmentBytesEqual(existing.bytes, bytes)) {
+      throw new Error(
+        `MemorySegmentStore: content-address collision at ${segmentId} (§5.1)`,
+      );
+    }
+    const record = mergeSegmentRecord(
+      existing?.record,
+      metadata,
       segmentId,
-      byteLength: bytes.length,
-      createdAtMs: nowMs,
-      expiresAtMs: nowMs + this.#ttlMs,
-    };
+      bytes.length,
+      nowMs,
+      this.#ttlMs,
+    );
     this.#entries.set(segmentId, { record, bytes });
     return record;
   }
@@ -127,18 +358,19 @@ export class MemorySegmentStore implements SegmentStore {
     nowMs: number,
   ): Promise<SegmentRecord | undefined> {
     for (const { record } of this.#entries.values()) {
-      if (
-        record.partition === key.partition &&
-        record.logEpoch === key.logEpoch &&
-        record.table === key.table &&
-        record.schemaVersion === key.schemaVersion &&
-        record.mediaType === key.mediaType &&
-        record.scopeDigest === key.scopeDigest &&
-        record.asOfCommitSeq === key.asOfCommitSeq &&
-        record.rowCursor === null &&
-        record.expiresAtMs > nowMs
-      ) {
-        return record;
+      const publication = selectSegmentPublication(record, {
+        partition: key.partition,
+        logEpoch: key.logEpoch,
+        table: key.table,
+        schemaVersion: key.schemaVersion,
+        mediaType: key.mediaType,
+        scopeDigest: key.scopeDigest,
+        asOfCommitSeq: key.asOfCommitSeq,
+        rowCursor: null,
+        nowMs,
+      });
+      if (publication !== undefined) {
+        return publicationRecord(record, publication);
       }
     }
     return undefined;

package/src/signed-url.ts

@@ -264,13 +264,19 @@ const DEFAULT_SKEW_SECONDS = 60;
 /**
  * Verify a segment token per §5.4. Throws `SyncError sync.forbidden` on any
  * failure (MAC, expiry, or claim mismatch).
+ *
+ * `scopeDigest` is the set of scope digests the token may authorize. Pass the
+ * digests of the stored record's publications that match the verifying host's
+ * partition: identical bytes are one content address (§5.1), but a digest
+ * recorded under another partition is not this host's grant (§5.4). A single
+ * string stays valid for a record with one publication.
  */
 export async function verifySegmentToken(
   key: string | Uint8Array,
   token: string,
   expected: {
     readonly segmentId: string;
-    readonly scopeDigest: string;
+    readonly scopeDigest: string | readonly string[];
     readonly audience: string;
     readonly nowMs: number;
     readonly skewSeconds?: number;
@@ -301,7 +307,11 @@ export async function verifySegmentToken(
     throw forbidden('token expired');
   }
   if (claims.seg !== expected.segmentId) throw forbidden('segment mismatch');
-  if (claims.sd !== expected.scopeDigest)
+  const scopeDigests =
+    typeof expected.scopeDigest === 'string'
+      ? [expected.scopeDigest]
+      : expected.scopeDigest;
+  if (!scopeDigests.includes(claims.sd))
     throw forbidden('scope-digest mismatch');
   if (claims.aud !== expected.audience) throw forbidden('audience mismatch');
   return claims;

package/src/sqlite-dialect.ts

@@ -36,6 +36,12 @@ import type {
  * range that returns already-ordered rows — the same covering-index shape
  * the Postgres storage documents (§3.1, performance-by-
  * construction).
+ *
+ * `sync_row_scopes_by_row` is the one secondary scope index: a per-row
+ * scope replacement predicates on `(partition, tbl, row_id)`, and `row_id`
+ * is the LAST PRIMARY KEY column, so that predicate cannot narrow the
+ * inverted index. Declared here so every SQLite-family storage (and D1,
+ * which applies this same DDL) keeps the same plan shape as Postgres.
  */
 export const SQLITE_DDL = `
 CREATE TABLE IF NOT EXISTS sync_partitions(
@@ -54,6 +60,8 @@ CREATE TABLE IF NOT EXISTS sync_row_scopes(
   var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,
   PRIMARY KEY(partition, tbl, var, value, row_id)
 );
+CREATE INDEX IF NOT EXISTS sync_row_scopes_by_row
+  ON sync_row_scopes(partition, tbl, row_id);
 CREATE TABLE IF NOT EXISTS sync_commits(
   partition TEXT NOT NULL, commit_seq INTEGER NOT NULL,
   client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,