@syncular/core 0.58.0 → 0.60.0

package/src/realtime.ts

@@ -9,6 +9,7 @@
  * `known: false` for unrecognized event names instead of failing.
  */
 import { DecodeError } from './errors';
+import { parseJsonDocument } from './json-document';
 
 /** §8.7 channel tag: a standalone SSP2 response message — a delta. */
 export const REALTIME_TAG_DELTA = 0x00;
@@ -55,6 +56,9 @@ export type PresenceKind = 'join' | 'update' | 'leave';
 
 const PRESENCE_KINDS: readonly PresenceKind[] = ['join', 'update', 'leave'];
 
+/** §8.6.2 publisher-directed presence rejection code — a closed set of two. */
+export type PresenceErrorCode = 'presence.too_large' | 'presence.forbidden';
+
 /**
  * Server → client presence fanout (§8.6.2): a scope-mate's presence for a
  * key the receiver holds changed. `doc` is the peer's document for
@@ -70,7 +74,7 @@ export interface RealtimePresenceEvent {
     actorId?: string;
     clientId?: string;
     doc?: Record<string, unknown> | null;
-    error?: string;
+    error?: PresenceErrorCode;
     timestamp?: number;
   };
 }
@@ -87,15 +91,6 @@ export interface RealtimeAck {
   cursor: number;
 }
 
-/** Client → server presence publish/leave (§8.6.2). `doc: null` = leave. */
-export interface RealtimePresencePublish {
-  event: 'presence';
-  data: {
-    scopeKey: string;
-    doc: Record<string, unknown> | null;
-  };
-}
-
 export type ParsedRealtimeEvent =
   | { known: true; event: RealtimeServerEvent }
   | { known: false; eventName: string };
@@ -176,13 +171,10 @@ const WAKE_REASONS: readonly WakeReason[] = [
 ];
 
 export function parseRealtimeServerEvent(text: string): ParsedRealtimeEvent {
-  let value: unknown;
-  try {
-    value = JSON.parse(text);
-  } catch {
-    malformed('not valid JSON');
-  }
-  const root = requireObject(value, 'control message');
+  const root = requireObject(
+    parseJsonDocument(text, 'control message'),
+    'control message',
+  );
   const event = requireString(root.event, 'event');
   if (event === 'hello') {
     const data = requireObject(root.data, 'hello.data');
@@ -311,33 +303,3 @@ function requirePresenceDocObject(value: unknown): void {
     malformed('presence.data.doc must be a JSON object');
   }
 }
-
-/**
- * Parse a client → server presence publish/leave (§8.6.2). Used by the
- * server to validate inbound `presence` control messages. A malformed
- * message (missing/empty `scopeKey`, or a `doc` that is neither an object
- * nor `null`) throws a `DecodeError` — a known event with wrong-shape data
- * is never a tolerated variant (§8.1).
- */
-export function parseRealtimePresencePublish(
-  text: string,
-): RealtimePresencePublish {
-  let value: unknown;
-  try {
-    value = JSON.parse(text);
-  } catch {
-    malformed('not valid JSON');
-  }
-  const root = requireObject(value, 'control message');
-  if (root.event !== 'presence') {
-    malformed('not a presence control message');
-  }
-  const data = requireObject(root.data, 'presence.data');
-  const scopeKey = validatePresenceScopeKey(data.scopeKey);
-  const doc = data.doc;
-  if (doc !== null) requirePresenceDocObject(doc);
-  return {
-    event: 'presence',
-    data: { scopeKey, doc: doc as Record<string, unknown> | null },
-  };
-}

package/src/render.ts

@@ -80,6 +80,13 @@ function renderStringMap(map: Readonly<Record<string, string>>): JsonValue {
   return { ...map };
 }
 
+/** Digest fields render as lowercase hex (Conventions: hashes are hex). */
+function renderDigest(digest: Uint8Array): string {
+  let hex = '';
+  for (const byte of digest) hex += byte.toString(16).padStart(2, '0');
+  return hex;
+}
+
 function renderOperation(operation: PushOperation): JsonValue {
   return {
     table: operation.table,
@@ -123,9 +130,7 @@ function renderChange(change: CommitChange): JsonValue {
     tableIndex: change.tableIndex,
     rowId: change.rowId,
     op: change.op,
-    ...(change.rowVersion !== undefined
-      ? { rowVersion: change.rowVersion }
-      : {}),
+    rowVersion: change.rowVersion,
     scopes: renderStringMap(change.scopes),
     ...(change.row !== undefined ? { row: bytesToBase64(change.row) } : {}),
   };
@@ -139,6 +144,7 @@ function renderFrame(frame: RequestFrame | ResponseFrame): JsonValue {
         clientId: frame.clientId,
         schemaVersion: frame.schemaVersion,
         ...(frame.logEpoch !== undefined ? { logEpoch: frame.logEpoch } : {}),
+        ...(frame.outboxId !== undefined ? { outboxId: frame.outboxId } : {}),
       };
     case 'ROUND_FAILURE':
       return { type: 'ROUND_FAILURE', code: frame.code };
@@ -146,6 +152,7 @@ function renderFrame(frame: RequestFrame | ResponseFrame): JsonValue {
       return {
         type: 'PUSH_COMMIT',
         clientCommitId: frame.clientCommitId,
+        clientSeq: frame.clientSeq,
         operations: frame.operations.map(renderOperation),
       };
     case 'PULL_HEADER':
@@ -155,16 +162,16 @@ function renderFrame(frame: RequestFrame | ResponseFrame): JsonValue {
         limitSnapshotRows: frame.limitSnapshotRows,
         maxSnapshotPages: frame.maxSnapshotPages,
         accept: frame.accept,
+        cursor: frame.cursor,
+        registrationDigest: renderDigest(frame.registrationDigest),
+        echoDigest: renderDigest(frame.echoDigest),
       };
-    case 'SUBSCRIPTION':
+    case 'UNIT':
+      return { type: 'UNIT', scopes: renderStringMap(frame.scopes) };
+    case 'PROGRESS':
       return {
-        type: 'SUBSCRIPTION',
+        type: 'PROGRESS',
         id: frame.id,
-        table: frame.table,
-        scopes: renderScopeLists(frame.scopes),
-        ...(frame.params !== undefined
-          ? { params: parseJson(frame.params) }
-          : {}),
         cursor: frame.cursor,
         ...(frame.bootstrapState !== undefined
           ? { bootstrapState: parseJson(frame.bootstrapState) }
@@ -228,8 +235,24 @@ function renderFrame(frame: RequestFrame | ResponseFrame): JsonValue {
         id: frame.id,
         status: frame.status,
         reasonCode: frame.reasonCode,
-        effectiveScopes: renderScopeLists(frame.effectiveScopes),
         bootstrap: frame.bootstrap,
+        fenced: frame.fenced.map((record) => ({
+          table: record.table,
+          status: record.status,
+          scopes: renderScopeLists(record.scopes),
+        })),
+      };
+    case 'LIVE_START':
+      return {
+        type: 'LIVE_START',
+        status: frame.status,
+        reasonCode: frame.reasonCode,
+      };
+    case 'LIVE_END':
+      return {
+        type: 'LIVE_END',
+        throughSeq: frame.throughSeq,
+        echoDigest: renderDigest(frame.echoDigest),
       };
     case 'COMMIT':
       return {

package/src/row-codec.ts

@@ -15,6 +15,7 @@
 import { parseBlobRef } from './blob-ref';
 import { ByteReader, ByteWriter } from './bytes';
 import { DecodeError, EncodeError } from './errors';
+import { parseJsonDocument } from './json-document';
 
 export type ColumnType =
   | 'string'
@@ -148,9 +149,10 @@ function readValue(reader: ByteReader, column: RowColumn): RowValue {
     case 'string':
       return reader.str();
     case 'json': {
-      // Conventions `json` MUST, applied at row-codec decode (SPEC.md §2.4
-      // tag 5): the value must parse as a JSON document; the raw string is
-      // preserved verbatim for round-trip fidelity.
+      // SPEC.md §2.4 tag 5: the value must parse as a JSON document; the raw
+      // string is preserved verbatim for round-trip fidelity. Full rows stay
+      // this permissive so stored rows keep decoding; `decodeSparseRow`
+      // applies the JSON validity rule on top.
       const raw = reader.str();
       try {
         JSON.parse(raw);
@@ -164,8 +166,8 @@ function readValue(reader: ByteReader, column: RowColumn): RowValue {
     }
     case 'blob_ref': {
       // §2.4 tag 7: the value is a canonical BlobRef JSON document
-      // (§5.9.1). Validated at decode, same class as tag-5 json; the raw
-      // string is preserved verbatim for re-encoding.
+      // (§5.9.1), checked on every decode path; the raw string is preserved
+      // verbatim for re-encoding.
       const raw = reader.str();
       parseBlobRef(raw);
       return raw;
@@ -262,7 +264,10 @@ export function encodeSparseRow(
  *
  * Decode checks, in order (each a decode error, RFC §6.1): a set presence
  * padding bit, an absent primary-key column, a set null-bitmap padding bit
- * (a null for an absent column), a null bit for a non-nullable column.
+ * (a null for an absent column), a null bit for a non-nullable column. Each
+ * present value must also be a push admission value (SPEC.md §2.4): no
+ * U+0000 in a `string`, a `json` value under the JSON validity rule, a finite
+ * `float`, a canonical `blob_ref`.
  */
 export function decodeSparseRow(
   columns: readonly RowColumn[],
@@ -318,7 +323,34 @@ export function decodeSparseRow(
     const isNull = bitmapBit(nulls, present);
     present++;
     if (!isNull) {
-      values.push(readValue(reader, column));
+      const value = readValue(reader, column);
+      // Push admission values (SPEC.md §2.4): one value set every storage
+      // backend and core accepts. `blob_ref` canonicality is already checked
+      // by `readValue` on every path.
+      if (
+        column.type === 'string' &&
+        typeof value === 'string' &&
+        value.includes('\u0000')
+      ) {
+        throw new DecodeError(
+          'sync.invalid_request',
+          `string column ${column.name} holds U+0000`,
+        );
+      }
+      if (column.type === 'json' && typeof value === 'string') {
+        parseJsonDocument(value, `json column ${column.name}`);
+      }
+      if (
+        column.type === 'float' &&
+        typeof value === 'number' &&
+        !Number.isFinite(value)
+      ) {
+        throw new DecodeError(
+          'sync.invalid_request',
+          `float column ${column.name} holds NaN or an infinity`,
+        );
+      }
+      values.push(value);
       continue;
     }
     if (!column.nullable) {