@syncular/core 0.1.2 → 0.2.0

package/src/realtime.ts

@@ -0,0 +1,340 @@
+/**
+ * Realtime JSON control messages and channel tags (SPEC.md §8).
+ *
+ * Control messages are JSON text frames; binary frames carry a one-byte
+ * channel tag (§8.7) followed by either a complete SSP2 response message
+ * (deltas) or a chunk of an in-flight sync round's byte stream, handled
+ * by the message codec / stream scanner. Per §8.1 a client MUST tolerate
+ * and ignore unknown JSON control events, so parsing returns
+ * `known: false` for unrecognized event names instead of failing.
+ */
+import { DecodeError } from './errors';
+
+/** §8.7 channel tag: a standalone SSP2 response message — a delta. */
+export const REALTIME_TAG_DELTA = 0x00;
+/** §8.7 channel tag: one chunk of the in-flight sync round's byte
+ * stream (request client→server, response server→client). */
+export const REALTIME_TAG_ROUND = 0x01;
+
+export interface RealtimeHelloEvent {
+  event: 'hello';
+  data: {
+    protocolVersion: number;
+    sessionId: string;
+    actorId: string;
+    clientId: string;
+    cursor: number;
+    latestCursor: number;
+    requiresSync: boolean;
+    timestamp: number;
+  };
+}
+
+export type WakeReason =
+  | 'delta-too-large'
+  | 'catchup-required'
+  | 'reset-required';
+
+export interface RealtimeSyncEvent {
+  event: 'sync';
+  data: {
+    cursor: number;
+    requiresPull: true;
+    reason: WakeReason;
+    timestamp: number;
+  };
+}
+
+export interface RealtimeHeartbeatEvent {
+  event: 'heartbeat';
+  data: { timestamp: number };
+}
+
+/** §8.6.2 presence fanout kind — a closed set of three. */
+export type PresenceKind = 'join' | 'update' | 'leave';
+
+const PRESENCE_KINDS: readonly PresenceKind[] = ['join', 'update', 'leave'];
+
+/**
+ * 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
+ * `join`/`update` and `null` for `leave`. An `error` variant carries a
+ * client-runtime `presence.*` code back to the publisher (size cap /
+ * forbidden, §8.6.2); it never fans out to peers.
+ */
+export interface RealtimePresenceEvent {
+  event: 'presence';
+  data: {
+    scopeKey: string;
+    kind?: PresenceKind;
+    actorId?: string;
+    clientId?: string;
+    doc?: Record<string, unknown> | null;
+    error?: string;
+    timestamp?: number;
+  };
+}
+
+export type RealtimeServerEvent =
+  | RealtimeHelloEvent
+  | RealtimeSyncEvent
+  | RealtimeHeartbeatEvent
+  | RealtimePresenceEvent;
+
+/** Client → server delta acknowledgement (§8.2). */
+export interface RealtimeAck {
+  type: 'ack';
+  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 };
+
+/** Serialize a client→server presence publish/leave (§8.6.2). */
+export function encodePresencePublish(
+  scopeKey: string,
+  doc: Record<string, unknown> | null,
+): string {
+  return JSON.stringify({ event: 'presence', data: { scopeKey, doc } });
+}
+
+/** Serialize a server→client presence fanout event (§8.6.2). */
+export function encodePresenceFanout(
+  scopeKey: string,
+  kind: PresenceKind,
+  actorId: string,
+  clientId: string,
+  doc: Record<string, unknown> | null,
+  timestamp: number,
+): string {
+  return JSON.stringify({
+    event: 'presence',
+    data: { scopeKey, kind, actorId, clientId, doc, timestamp },
+  });
+}
+
+/** Serialize a server→client presence error directed at the publisher
+ * (§8.6.2 `presence.too_large` / `presence.forbidden`). */
+export function encodePresenceError(
+  scopeKey: string,
+  error: string,
+  timestamp: number,
+): string {
+  return JSON.stringify({
+    event: 'presence',
+    data: { scopeKey, error, timestamp },
+  });
+}
+
+function malformed(what: string): never {
+  throw new DecodeError(
+    'sync.invalid_request',
+    `malformed realtime control message: ${what}`,
+  );
+}
+
+function requireObject(value: unknown, what: string): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    malformed(`${what} must be a JSON object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireNumber(value: unknown, what: string): number {
+  // Realtime numeric fields are integers within the ±(2^53−1) i64 contract
+  // (SPEC.md §8.1); fractional or non-finite numbers are malformed.
+  if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+    malformed(`${what} must be an integer within the i64 safe range`);
+  }
+  return value;
+}
+
+function requireString(value: unknown, what: string): string {
+  if (typeof value !== 'string') malformed(`${what} must be a string`);
+  return value;
+}
+
+function requireBoolean(value: unknown, what: string): boolean {
+  if (typeof value !== 'boolean') malformed(`${what} must be a boolean`);
+  return value;
+}
+
+const WAKE_REASONS: readonly WakeReason[] = [
+  'delta-too-large',
+  'catchup-required',
+  'reset-required',
+];
+
+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 event = requireString(root.event, 'event');
+  if (event === 'hello') {
+    const data = requireObject(root.data, 'hello.data');
+    return {
+      known: true,
+      event: {
+        event: 'hello',
+        data: {
+          protocolVersion: requireNumber(
+            data.protocolVersion,
+            'hello.data.protocolVersion',
+          ),
+          sessionId: requireString(data.sessionId, 'hello.data.sessionId'),
+          actorId: requireString(data.actorId, 'hello.data.actorId'),
+          clientId: requireString(data.clientId, 'hello.data.clientId'),
+          cursor: requireNumber(data.cursor, 'hello.data.cursor'),
+          latestCursor: requireNumber(
+            data.latestCursor,
+            'hello.data.latestCursor',
+          ),
+          requiresSync: requireBoolean(
+            data.requiresSync,
+            'hello.data.requiresSync',
+          ),
+          timestamp: requireNumber(data.timestamp, 'hello.data.timestamp'),
+        },
+      },
+    };
+  }
+  if (event === 'sync') {
+    const data = requireObject(root.data, 'sync.data');
+    const reason = requireString(data.reason, 'sync.data.reason');
+    if (!(WAKE_REASONS as readonly string[]).includes(reason)) {
+      malformed(`unknown wake reason ${JSON.stringify(reason)}`);
+    }
+    if (data.requiresPull !== true) {
+      malformed('sync.data.requiresPull must be true');
+    }
+    return {
+      known: true,
+      event: {
+        event: 'sync',
+        data: {
+          cursor: requireNumber(data.cursor, 'sync.data.cursor'),
+          requiresPull: true,
+          reason: reason as WakeReason,
+          timestamp: requireNumber(data.timestamp, 'sync.data.timestamp'),
+        },
+      },
+    };
+  }
+  if (event === 'heartbeat') {
+    const data = requireObject(root.data, 'heartbeat.data');
+    return {
+      known: true,
+      event: {
+        event: 'heartbeat',
+        data: {
+          timestamp: requireNumber(data.timestamp, 'heartbeat.data.timestamp'),
+        },
+      },
+    };
+  }
+  if (event === 'presence') {
+    // §8.6.2: validate the presence shape but carry `data` through
+    // verbatim so re-encoding is byte-identical (host-defined `doc`). A
+    // `presence` message is recognized in both directions: a fanout (has
+    // `kind`), a publisher-directed error (has `error`), or a client→server
+    // publish (neither — just `scopeKey`/`doc`, §8.6.2).
+    const data = requireObject(root.data, 'presence.data');
+    validatePresenceScopeKey(data.scopeKey);
+    if ('error' in data) {
+      // The publisher-directed error variant (`presence.too_large` /
+      // `presence.forbidden`, §8.6.2) — a string code, no `kind`/`doc`.
+      requireString(data.error, 'presence.data.error');
+    } else if ('kind' in data) {
+      validatePresenceKind(data.kind);
+      requireString(data.actorId, 'presence.data.actorId');
+      requireString(data.clientId, 'presence.data.clientId');
+      validatePresenceFanoutDoc(data.kind as PresenceKind, data.doc);
+    } else {
+      // Client→server publish/leave: scopeKey + doc (object or null).
+      if (data.doc !== null) requirePresenceDocObject(data.doc);
+    }
+    if (data.timestamp !== undefined) {
+      requireNumber(data.timestamp, 'presence.data.timestamp');
+    }
+    return {
+      known: true,
+      event: { event: 'presence', data: data as RealtimePresenceEvent['data'] },
+    };
+  }
+  return { known: false, eventName: event };
+}
+
+function validatePresenceScopeKey(value: unknown): string {
+  const key = requireString(value, 'presence.data.scopeKey');
+  if (key.length === 0) malformed('presence.data.scopeKey must be non-empty');
+  return key;
+}
+
+function validatePresenceKind(value: unknown): void {
+  const kind = requireString(value, 'presence.data.kind');
+  if (!(PRESENCE_KINDS as readonly string[]).includes(kind)) {
+    malformed(`unknown presence kind ${JSON.stringify(kind)}`);
+  }
+}
+
+/** §8.6.2 `doc`-present-iff-not-`leave`: a leave carries null, a
+ * join/update carries an object. */
+function validatePresenceFanoutDoc(kind: PresenceKind, doc: unknown): void {
+  if (kind === 'leave') {
+    if (doc !== null && doc !== undefined) {
+      malformed('presence leave must carry doc: null');
+    }
+    return;
+  }
+  requirePresenceDocObject(doc);
+}
+
+function requirePresenceDocObject(value: unknown): void {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    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

@@ -0,0 +1,325 @@
+/**
+ * Canonical JSON debug rendering (SPEC.md §11).
+ *
+ * Non-contractual for the wire; contractual for golden vectors. Rendering
+ * rules: frames in wire order with END omitted, field order per the SPEC
+ * field tables, absent opt() fields omitted, binary fields as standard
+ * base64, enums by their spec names, i64 as JSON numbers, json-typed
+ * fields embedded as parsed JSON.
+ */
+import type {
+  CommitChange,
+  PushOperation,
+  PushOperationResult,
+  RequestFrame,
+  ResponseFrame,
+  SyncMessage,
+} from './message';
+import { decodeMessage } from './message';
+import type { RowColumn, RowValue } from './row-codec';
+import type { RowsSegment } from './segment';
+import { decodeRowsSegment, ROWS_SEGMENT_FORMAT_VERSION } from './segment';
+
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+const BASE64_ALPHABET =
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+/** Standard base64 (§11.1 rule 4). Dependency- and runtime-agnostic. */
+export function bytesToBase64(bytes: Uint8Array): string {
+  let out = '';
+  let i = 0;
+  for (; i + 2 < bytes.length; i += 3) {
+    const chunk =
+      ((bytes[i] ?? 0) << 16) |
+      ((bytes[i + 1] ?? 0) << 8) |
+      (bytes[i + 2] ?? 0);
+    out +=
+      BASE64_ALPHABET.charAt((chunk >> 18) & 63) +
+      BASE64_ALPHABET.charAt((chunk >> 12) & 63) +
+      BASE64_ALPHABET.charAt((chunk >> 6) & 63) +
+      BASE64_ALPHABET.charAt(chunk & 63);
+  }
+  const rest = bytes.length - i;
+  if (rest === 1) {
+    const chunk = (bytes[i] ?? 0) << 16;
+    out +=
+      BASE64_ALPHABET.charAt((chunk >> 18) & 63) +
+      BASE64_ALPHABET.charAt((chunk >> 12) & 63) +
+      '==';
+  } else if (rest === 2) {
+    const chunk = ((bytes[i] ?? 0) << 16) | ((bytes[i + 1] ?? 0) << 8);
+    out +=
+      BASE64_ALPHABET.charAt((chunk >> 18) & 63) +
+      BASE64_ALPHABET.charAt((chunk >> 12) & 63) +
+      BASE64_ALPHABET.charAt((chunk >> 6) & 63) +
+      '=';
+  }
+  return out;
+}
+
+function parseJson(raw: string): JsonValue {
+  return JSON.parse(raw) as JsonValue;
+}
+
+function renderScopeLists(
+  scopes: Readonly<Record<string, string[]>>,
+): JsonValue {
+  return Object.fromEntries(
+    Object.entries(scopes).map(([key, values]) => [key, [...values]]),
+  );
+}
+
+function renderStringMap(map: Readonly<Record<string, string>>): JsonValue {
+  return { ...map };
+}
+
+function renderOperation(operation: PushOperation): JsonValue {
+  return {
+    table: operation.table,
+    rowId: operation.rowId,
+    op: operation.op,
+    ...(operation.baseVersion !== undefined
+      ? { baseVersion: operation.baseVersion }
+      : {}),
+    ...(operation.payload !== undefined
+      ? { payload: bytesToBase64(operation.payload) }
+      : {}),
+  };
+}
+
+function renderResult(result: PushOperationResult): JsonValue {
+  if (result.status === 'applied') {
+    return { opIndex: result.opIndex, status: 'applied' };
+  }
+  if (result.status === 'conflict') {
+    return {
+      opIndex: result.opIndex,
+      status: 'conflict',
+      code: result.code,
+      message: result.message,
+      serverVersion: result.serverVersion,
+      serverRow: bytesToBase64(result.serverRow),
+    };
+  }
+  return {
+    opIndex: result.opIndex,
+    status: 'error',
+    code: result.code,
+    message: result.message,
+    retryable: result.retryable,
+  };
+}
+
+function renderChange(change: CommitChange): JsonValue {
+  return {
+    tableIndex: change.tableIndex,
+    rowId: change.rowId,
+    op: change.op,
+    ...(change.rowVersion !== undefined
+      ? { rowVersion: change.rowVersion }
+      : {}),
+    scopes: renderStringMap(change.scopes),
+    ...(change.row !== undefined ? { row: bytesToBase64(change.row) } : {}),
+  };
+}
+
+function renderFrame(frame: RequestFrame | ResponseFrame): JsonValue {
+  switch (frame.type) {
+    case 'REQ_HEADER':
+      return {
+        type: 'REQ_HEADER',
+        clientId: frame.clientId,
+        schemaVersion: frame.schemaVersion,
+      };
+    case 'PUSH_COMMIT':
+      return {
+        type: 'PUSH_COMMIT',
+        clientCommitId: frame.clientCommitId,
+        operations: frame.operations.map(renderOperation),
+      };
+    case 'PULL_HEADER':
+      return {
+        type: 'PULL_HEADER',
+        limitCommits: frame.limitCommits,
+        limitSnapshotRows: frame.limitSnapshotRows,
+        maxSnapshotPages: frame.maxSnapshotPages,
+        accept: frame.accept,
+      };
+    case 'SUBSCRIPTION':
+      return {
+        type: 'SUBSCRIPTION',
+        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) }
+          : {}),
+      };
+    case 'RESP_HEADER':
+      return {
+        type: 'RESP_HEADER',
+        ...(frame.requiredSchemaVersion !== undefined
+          ? { requiredSchemaVersion: frame.requiredSchemaVersion }
+          : {}),
+        ...(frame.latestSchemaVersion !== undefined
+          ? { latestSchemaVersion: frame.latestSchemaVersion }
+          : {}),
+      };
+    case 'LEASE':
+      return {
+        type: 'LEASE',
+        leaseId: frame.leaseId,
+        expiresAtMs: frame.expiresAtMs,
+      };
+    case 'PUSH_RESULT':
+      return {
+        type: 'PUSH_RESULT',
+        clientCommitId: frame.clientCommitId,
+        status: frame.status,
+        ...(frame.commitSeq !== undefined
+          ? { commitSeq: frame.commitSeq }
+          : {}),
+        results: frame.results.map(renderResult),
+      };
+    case 'SUB_START':
+      return {
+        type: 'SUB_START',
+        id: frame.id,
+        status: frame.status,
+        reasonCode: frame.reasonCode,
+        effectiveScopes: renderScopeLists(frame.effectiveScopes),
+        bootstrap: frame.bootstrap,
+      };
+    case 'COMMIT':
+      return {
+        type: 'COMMIT',
+        commitSeq: frame.commitSeq,
+        createdAtMs: frame.createdAtMs,
+        actorId: frame.actorId,
+        tables: [...frame.tables],
+        changes: frame.changes.map(renderChange),
+      };
+    case 'SEGMENT_REF':
+      return {
+        type: 'SEGMENT_REF',
+        segmentId: frame.segmentId,
+        mediaType: frame.mediaType,
+        table: frame.table,
+        byteLength: frame.byteLength,
+        rowCount: frame.rowCount,
+        asOfCommitSeq: frame.asOfCommitSeq,
+        scopeDigest: frame.scopeDigest,
+        ...(frame.rowCursor !== undefined
+          ? { rowCursor: frame.rowCursor }
+          : {}),
+        ...(frame.nextRowCursor !== undefined
+          ? { nextRowCursor: frame.nextRowCursor }
+          : {}),
+        ...(frame.url !== undefined ? { url: frame.url } : {}),
+        ...(frame.urlExpiresAtMs !== undefined
+          ? { urlExpiresAtMs: frame.urlExpiresAtMs }
+          : {}),
+      };
+    case 'SEGMENT_INLINE':
+      return {
+        type: 'SEGMENT_INLINE',
+        payload: bytesToBase64(frame.payload),
+      };
+    case 'SUB_END':
+      return {
+        type: 'SUB_END',
+        nextCursor: frame.nextCursor,
+        ...(frame.bootstrapState !== undefined
+          ? { bootstrapState: parseJson(frame.bootstrapState) }
+          : {}),
+      };
+    case 'ERROR':
+      return {
+        type: 'ERROR',
+        code: frame.code,
+        message: frame.message,
+        category: frame.category,
+        retryable: frame.retryable,
+        recommendedAction: frame.recommendedAction,
+        ...(frame.details !== undefined
+          ? { details: parseJson(frame.details) }
+          : {}),
+      };
+    case 'UNKNOWN':
+      return {
+        type: 'UNKNOWN',
+        frameType: frame.frameType,
+        payload: bytesToBase64(frame.payload),
+      };
+  }
+}
+
+export function renderMessageValue(message: SyncMessage): JsonValue {
+  return {
+    magic: 'SSP2',
+    wireVersion: message.wireVersion,
+    msgKind: message.msgKind,
+    frames: message.frames.map((frame: RequestFrame | ResponseFrame) =>
+      renderFrame(frame),
+    ),
+  };
+}
+
+/** `render(bytes) → json` for SSP2 messages (§11). */
+export function renderMessage(bytes: Uint8Array): JsonValue {
+  return renderMessageValue(decodeMessage(bytes));
+}
+
+function renderRowValue(column: RowColumn, value: RowValue): JsonValue {
+  if (value === null) return null;
+  if (value instanceof Uint8Array) return bytesToBase64(value);
+  if (
+    (column.type === 'json' || column.type === 'blob_ref') &&
+    typeof value === 'string'
+  ) {
+    // §11: json and blob_ref (tag 7) render as embedded parsed JSON.
+    return parseJson(value);
+  }
+  return value;
+}
+
+export function renderRowsSegmentValue(segment: RowsSegment): JsonValue {
+  return {
+    magic: 'SSG2',
+    formatVersion: ROWS_SEGMENT_FORMAT_VERSION,
+    table: segment.table,
+    schemaVersion: segment.schemaVersion,
+    columns: segment.columns.map((column) => ({
+      name: column.name,
+      type: column.type,
+      nullable: column.nullable,
+    })),
+    blocks: segment.blocks.map((block) =>
+      block.map((row) => ({
+        serverVersion: row.serverVersion,
+        values: Object.fromEntries(
+          segment.columns.map((column, i) => [
+            column.name,
+            renderRowValue(column, row.values[i] ?? null),
+          ]),
+        ),
+      })),
+    ),
+  };
+}
+
+/** `render(bytes) → json` for standalone SSG2 rows segments (§11 rule 8). */
+export function renderRowsSegment(bytes: Uint8Array): JsonValue {
+  return renderRowsSegmentValue(decodeRowsSegment(bytes));
+}