@syncular/server 0.32.1 → 0.34.0

package/dist/operations.js

@@ -6,7 +6,7 @@ import { processPushOperationsWithTrace } from './push.js';
 import { compileSchema } from './schema.js';
 import { authorizeWrite, renderScopeValue, } from './scopes.js';
 import { transactionQuery } from './storage-query.js';
-import { toValidateRow } from './validate.js';
+import { toValidateRow, ValidationRejection, } from './validate.js';
 function scopeAllowed(allowed, variable, value) {
     const values = allowed[variable];
     return (values !== undefined && (values.includes('*') || values.includes(value)));
@@ -353,6 +353,15 @@ export class RemoteOperationRegistry {
     }
 }
 function encodeRemoteOperationError(error, fallbackCode) {
+    if (error instanceof ValidationRejection) {
+        return encodeRemoteOperationResponse({
+            revision: 1,
+            kind: 'error',
+            code: error.code,
+            message: error.message,
+            retryable: false,
+        });
+    }
     const sync = error instanceof SyncError
         ? error
         : syncError(fallbackCode, fallbackCode === 'operation.invalid_request'
@@ -366,7 +375,7 @@ function encodeRemoteOperationError(error, fallbackCode) {
         retryable: sync.retryable,
     });
 }
-export async function handleRemoteOperation(bytes, ctx, registry) {
+export async function handleRemoteOperation(bytes, authenticated, operations) {
     let request;
     try {
         request = decodeRemoteOperationRequest(bytes);
@@ -384,6 +393,7 @@ export async function handleRemoteOperation(bytes, ctx, registry) {
     catch (error) {
         return encodeRemoteOperationError(error, 'operation.invalid_request');
     }
+    let ctx = authenticated;
     try {
         await touchAuthenticatedPartition(ctx);
         if (request.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
@@ -397,6 +407,16 @@ export async function handleRemoteOperation(bytes, ctx, registry) {
             (typeof request.requestId !== 'string' || request.requestId.length === 0)) {
             throw syncError('operation.invalid_request');
         }
+        let registry = operations;
+        if (typeof registry === 'function') {
+            const binding = await registry(request, ctx);
+            registry = binding.registry;
+            ctx = {
+                ...ctx,
+                actorId: binding.actorId ?? ctx.actorId,
+                resolveScopes: binding.resolveScopes ?? ctx.resolveScopes,
+            };
+        }
         const operation = registry.get(request.operationId);
         if (operation === undefined) {
             throw syncError('operation.unknown');
@@ -411,7 +431,7 @@ export async function handleRemoteOperation(bytes, ctx, registry) {
         return encodeRemoteOperationResponse(await operation.run(ctx, request.clientId, request.requestId, request.params));
     }
     catch (error) {
-        if (!(error instanceof SyncError)) {
+        if (!(error instanceof SyncError || error instanceof ValidationRejection)) {
             reportError(error, ctx.onError, 'operations');
         }
         return encodeRemoteOperationError(error, 'operation.execution_failed');

package/dist/realtime.d.ts

@@ -162,6 +162,11 @@ export declare class RealtimeSession {
      * deltas immediately; it also survives a newer round-end refresh that
      * failed, because that round applied nothing.
      */
+    /**
+     * A pull outside this connection changed the client's subscriptions. A
+     * round in flight on the connection reloads them at its end anyway.
+     */
+    refreshAfterPull(): Promise<void>;
     refreshRegistrations(failClosed: boolean): Promise<void>;
     sendHeartbeat(): void;
     sendWake(reason: WakeReason): void;
@@ -230,6 +235,12 @@ export declare class RealtimeHub {
     disconnect(session: RealtimeSession): void;
     /** RealtimeNotifier: fan an applied commit out to matching sessions. */
     notifyCommit(partition: string, commit: StoredCommit): Promise<void>;
+    /**
+     * RealtimeNotifier: a pull changed a client's subscription list (§8.7).
+     * Its sockets reload their registrations with the round-end semantics, so
+     * an unreadable record keeps the previous registrations.
+     */
+    notifySubscriptions(partition: string, clientId: string): Promise<void>;
     /**
      * Host-initiated, fail-closed registration refresh (§8.7). A host calls this
      * after it changes an actor's membership or connection state, so the

package/dist/realtime.js

@@ -510,6 +510,15 @@ export class RealtimeSession {
      * deltas immediately; it also survives a newer round-end refresh that
      * failed, because that round applied nothing.
      */
+    /**
+     * A pull outside this connection changed the client's subscriptions. A
+     * round in flight on the connection reloads them at its end anyway.
+     */
+    async refreshAfterPull() {
+        if (this.#activeRound !== undefined)
+            return;
+        await this.refreshRegistrations(false);
+    }
     async refreshRegistrations(failClosed) {
         const generation = ++this.#registrationGeneration;
         let registrations;
@@ -845,67 +854,13 @@ export class RealtimeHub {
             // segment store the HTTP binding uses — never a degraded round.
             throw syncError('sync.invalid_request', 'socket sync rounds require a segment store on the realtime hub (§8.7)');
         }
+        // The whole config, so a new `SyncServerConfig` field reaches socket and
+        // hub-served HTTP rounds without being listed here.
         return {
+            ...this.#config,
+            segments,
             partition: identity.partition,
             actorId: identity.actorId,
-            schema: this.#config.schema,
-            ...(this.#config.schemaWindow !== undefined
-                ? { schemaWindow: this.#config.schemaWindow }
-                : {}),
-            storage: this.#config.storage,
-            segments,
-            resolveScopes: this.#config.resolveScopes,
-            ...(this.#config.blobs !== undefined
-                ? { blobs: this.#config.blobs }
-                : {}),
-            ...(this.#config.maxBlobBytes !== undefined
-                ? { maxBlobBytes: this.#config.maxBlobBytes }
-                : {}),
-            ...(this.#config.crdtMergers !== undefined
-                ? { crdtMergers: this.#config.crdtMergers }
-                : {}),
-            ...(this.#config.validators !== undefined
-                ? { validators: this.#config.validators }
-                : {}),
-            ...(this.#config.commitValidator !== undefined
-                ? { commitValidator: this.#config.commitValidator }
-                : {}),
-            ...(this.#config.reactionPlanner !== undefined
-                ? { reactionPlanner: this.#config.reactionPlanner }
-                : {}),
-            ...(this.#config.checkpoints !== undefined
-                ? { checkpoints: this.#config.checkpoints }
-                : {}),
-            ...(this.#config.clock !== undefined
-                ? { clock: this.#config.clock }
-                : {}),
-            ...(this.#config.limits !== undefined
-                ? { limits: this.#config.limits }
-                : {}),
-            ...(this.#config.signedUrls !== undefined
-                ? { signedUrls: this.#config.signedUrls }
-                : {}),
-            ...(this.#config.blobSignedUrls !== undefined
-                ? { blobSignedUrls: this.#config.blobSignedUrls }
-                : {}),
-            ...(this.#config.blobUploadUrls !== undefined
-                ? { blobUploadUrls: this.#config.blobUploadUrls }
-                : {}),
-            ...(this.#config.sqliteImageBuilder !== undefined
-                ? { sqliteImageBuilder: this.#config.sqliteImageBuilder }
-                : {}),
-            ...(this.#config.leases !== undefined
-                ? { leases: this.#config.leases }
-                : {}),
-            ...(this.#config.events !== undefined
-                ? { events: this.#config.events }
-                : {}),
-            ...(this.#config.onError !== undefined
-                ? { onError: this.#config.onError }
-                : {}),
-            ...(this.#config.mapError !== undefined
-                ? { mapError: this.#config.mapError }
-                : {}),
             realtime: this,
         };
     }
@@ -1012,6 +967,18 @@ export class RealtimeHub {
             session.deliverCommit(commit);
         }
     }
+    /**
+     * RealtimeNotifier: a pull changed a client's subscription list (§8.7).
+     * Its sockets reload their registrations with the round-end semantics, so
+     * an unreadable record keeps the previous registrations.
+     */
+    async notifySubscriptions(partition, clientId) {
+        for (const session of [...this.#sessions]) {
+            if (session.partition !== partition || session.clientId !== clientId)
+                continue;
+            await session.refreshAfterPull();
+        }
+    }
     /**
      * Host-initiated, fail-closed registration refresh (§8.7). A host calls this
      * after it changes an actor's membership or connection state, so the

package/dist/relational-rows.d.ts

@@ -259,11 +259,14 @@ export declare function prefetchRowsSql(table: CompiledTable): string;
  * SQLite/D1: the newest `commit_seq` in the inverted change-scope index for
  * one variable's values, as one index-only max per value (a `(partition,
  * tbl, var, value)` prefix), so the cost is independent of the table's
- * history. Bind order: [partition, tbl, var, value] per value.
+ * history. The values arrive as one JSON array, so the statement has no
+ * compound SELECT and four bound parameters for any value count (D1 caps a
+ * compound SELECT at 5 terms and a statement at 100 parameters).
+ * Params: [partition, tbl, var, values as JSON array text].
  */
-export declare function latestScopedChangeSeqSql(valueCount: number): string;
+export declare const LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL = "SELECT max((SELECT max(commit_seq) FROM sync_change_scopes\n           WHERE partition=? AND tbl=? AND var=? AND value=v.value)) AS seq\n     FROM json_each(?) AS v";
 /**
- * PostgreSQL set-based form of `latestScopedChangeSeqSql` for the
+ * PostgreSQL set-based form of `LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL` for the
  * subscriptions of one table in a pull. `$2` is a JSON array of
  * `{i, var, vals}` records. Params: [partition, specs (JSON text), tbl].
  */

package/dist/relational-rows.js

@@ -610,17 +610,16 @@ export function prefetchRowsSql(table) {
  * SQLite/D1: the newest `commit_seq` in the inverted change-scope index for
  * one variable's values, as one index-only max per value (a `(partition,
  * tbl, var, value)` prefix), so the cost is independent of the table's
- * history. Bind order: [partition, tbl, var, value] per value.
+ * history. The values arrive as one JSON array, so the statement has no
+ * compound SELECT and four bound parameters for any value count (D1 caps a
+ * compound SELECT at 5 terms and a statement at 100 parameters).
+ * Params: [partition, tbl, var, values as JSON array text].
  */
-export function latestScopedChangeSeqSql(valueCount) {
-    const perValue = [];
-    for (let i = 0; i < valueCount; i++) {
-        perValue.push('SELECT (SELECT max(commit_seq) FROM sync_change_scopes WHERE partition=? AND tbl=? AND var=? AND value=?) AS seq');
-    }
-    return `SELECT max(seq) AS seq FROM (${perValue.join(' UNION ALL ')})`;
-}
+export const LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL = `SELECT max((SELECT max(commit_seq) FROM sync_change_scopes
+           WHERE partition=? AND tbl=? AND var=? AND value=v.value)) AS seq
+     FROM json_each(?) AS v`;
 /**
- * PostgreSQL set-based form of `latestScopedChangeSeqSql` for the
+ * PostgreSQL set-based form of `LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL` for the
  * subscriptions of one table in a pull. `$2` is a JSON array of
  * `{i, var, vals}` records. Params: [partition, specs (JSON text), tbl].
  */

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

@@ -1,37 +1,15 @@
 /**
  * S3-compatible blob store (SPEC.md §5.9.2 durable objects, §5.9.5 delegated
- * presign) — AWS S3, Cloudflare R2, MinIO. The blob twin of
- * `s3-segment-store.ts`: same hand-rolled SigV4 over `fetch` (sigv4.ts), same
- * content-addressed key layout, same LIST-free-on-the-hot-path CAS stats
- * accumulator. Zero dependencies.
+ * presign) — AWS S3, Cloudflare R2's S3 endpoint, MinIO. The blob twin of
+ * `s3-segment-store.ts`.
  *
- * Key layout (deterministic — every point lookup is a GET/HEAD, never a LIST):
- *
- *   {keyPrefix}blob/sha256/{hex}
- *     The blob bytes, VERBATIM (the object body MUST be exactly the
- *     content-addressed bytes so a presigned GET serves them directly and the
- *     client's §5.9.1 hash check passes — blobs are never re-compressed at
- *     rest, §5.8/§5.9.5). The `byteLength` + optional `mediaType` ride along
- *     as object user metadata `x-amz-meta-syncular-blob` = base64url(JSON), so
- *     `get` is a single GET. `createdAtMs` is stored there too so the orphan
- *     sweep (§5.9.2) can read the upload age without a separate index.
- *
- * DURABILITY vs SEGMENT TTL — the honest interface difference (§5.9.2): a
- * blob referenced by a live row must stay downloadable INDEFINITELY. So,
- * unlike `S3SegmentStore`, this store writes **no `expiresAtMs`, no S3
- * lifecycle-expiration mapping, and no TTL config**. Expiry is
- * REFERENCE-driven, not time-driven: reclamation is the host-scheduled
- * `sweepOrphanBlobs` (blob-store.ts) deleting only objects no live row
- * references after a grace period — never a bucket lifecycle rule. Do NOT
- * put a lifecycle expiration on the `blob/` prefix; it would delete
- * still-referenced attachments.
- *
- * The orphan sweep is the ONLY operation that LISTs: `sweepOrphans` pages
- * `ListObjectsV2` over the `blob/` prefix (an admin/GC path, off the hot
- * path) to find candidates, reads each object's `createdAtMs` from its
- * metadata for the grace check, and DELETEs the unreferenced-and-old ones.
+ * The store logic (content-addressed key layout, idempotent re-put, orphan
+ * sweep, CAS stats accumulator) is `BucketBlobStore`, shared with
+ * `R2BlobStore` in `@syncular/server-workers`; this class adds the S3 REST
+ * transport (`S3ObjectBucket`) and the SigV4 presign methods, which a bucket
+ * binding cannot mint.
  */
-import type { BlobRecord, BlobStore, BlobStoreStats } from './blob-store.js';
+import { BucketBlobStore } from './bucket-blob-store.js';
 import type { BlobPresignConfig, BlobUploadPresignConfig, SegmentUrlIssue } from './signed-url.js';
 export interface S3BlobStoreConfig {
     /**
@@ -52,42 +30,9 @@ export interface S3BlobStoreConfig {
     /** Key namespace inside the bucket, e.g. `syncular/`. Default: none. */
     readonly keyPrefix?: string;
 }
-export declare class S3BlobStore implements BlobStore {
+export declare class S3BlobStore extends BucketBlobStore {
     #private;
     constructor(config: S3BlobStoreConfig);
-    /**
-     * `{keyPrefix}blob/{partition}/sha256/{hex}` — the §5.9.5 "signed key embeds
-     * the blobId". Blobs are content-addressed, but download authorization and
-     * the reference index are per-partition, so the same bytes uploaded under
-     * two partitions are two objects (a partition MUST NOT read another's
-     * attachment by guessing a content address). The partition is folded into
-     * the key as a path segment.
-     */
-    objectKeyFor(partition: string, blobId: string): string;
-    put(partition: string, blobId: string, bytes: Uint8Array, nowMs: number, mediaType?: string): Promise<BlobRecord>;
-    has(partition: string, blobId: string): Promise<boolean>;
-    get(partition: string, blobId: string): Promise<{
-        record: BlobRecord;
-        bytes: Uint8Array;
-    } | undefined>;
-    /**
-     * §5.9.2 orphan sweep — the ONLY LISTing operation. Page `ListObjectsV2`
-     * over `{prefix}blob/{partition}/`, HEAD each object for its `createdAtMs`,
-     * and DELETE the ones both older than `olderThanMs` AND absent from
-     * `referencedBlobIds`. Returns the deleted blobIds. Never deletes a
-     * referenced blob (§5.9.2). Off the hot path — a host-scheduled GC job.
-     */
-    sweepOrphans(partition: string, olderThanMs: number, referencedBlobIds: ReadonlySet<string>): Promise<string[]>;
-    /**
-     * Store-wide counters from the pointer-object accumulator (never a LIST on
-     * the read path). `approximate: true` for the same reasons `S3SegmentStore`
-     * documents: best-effort ETag-CAS maintenance and sweep deletes that may
-     * miss the decrement. Exact within a single writer; a health gauge under
-     * concurrency. Note this is store-WIDE, not partition-scoped, so a shared
-     * bucket reports the whole bucket — the parameter is accepted for interface
-     * parity but the accumulator is one object per store.
-     */
-    stats(_partition: string): Promise<BlobStoreStats>;
     /**
      * SigV4 presigned GET for a blob object (§5.9.5 delegated presign). The
      * signed key embeds the `blobId`; `urlExpiresAtMs` is the provider-enforced