@syncular/server 0.15.47 → 0.16.1

package/src/frame-bytes.ts

@@ -18,7 +18,14 @@ import {
   type SubStartFrame,
 } from '@syncular/core';
 
-const STUB_HEADER: RespHeaderFrame = { type: 'RESP_HEADER' };
+const stubHeader = (wireVersion: number): RespHeaderFrame =>
+  wireVersion >= 2
+    ? {
+        type: 'RESP_HEADER',
+        logEpoch: 'frame-probe',
+        resetRequired: false,
+      }
+    : { type: 'RESP_HEADER' };
 const STUB_SUB_START: SubStartFrame = {
   type: 'SUB_START',
   id: '',
@@ -30,18 +37,28 @@ const STUB_SUB_START: SubStartFrame = {
 const STUB_SUB_END: SubEndFrame = { type: 'SUB_END', nextCursor: 0 };
 
 const probe = encodeMessage({
-  wireVersion: PROTOCOL_WIRE_VERSION,
+  wireVersion: 1,
   msgKind: 'response',
-  frames: [STUB_HEADER],
+  frames: [stubHeader(1)],
 });
 
 /** The 8-byte SSP2 response envelope header (§1.2). */
-export const RESPONSE_ENVELOPE_HEADER: Uint8Array = probe.slice(0, 8);
+export function responseEnvelopeHeader(wireVersion: number): Uint8Array {
+  const encoded = encodeMessage({
+    wireVersion,
+    msgKind: 'response',
+    frames: [stubHeader(wireVersion)],
+  });
+  return encoded.slice(0, 8);
+}
 
 /** The terminating END frame (§1.2 rule 1). */
 export const END_FRAME_BYTES: Uint8Array = probe.slice(probe.length - 5);
 
-function wrapperFor(frame: ResponseFrame): {
+function wrapperFor(
+  frame: ResponseFrame,
+  wireVersion: number,
+): {
   frames: ResponseFrame[];
   index: number;
 } {
@@ -50,11 +67,11 @@ function wrapperFor(frame: ResponseFrame): {
       return { frames: [frame], index: 0 };
     case 'LEASE':
       // §7.3.2: LEASE rides immediately after RESP_HEADER.
-      return { frames: [STUB_HEADER, frame], index: 1 };
+      return { frames: [stubHeader(wireVersion), frame], index: 1 };
     case 'PUSH_RESULT':
     case 'ERROR':
     case 'UNKNOWN':
-      return { frames: [STUB_HEADER, frame], index: 1 };
+      return { frames: [stubHeader(wireVersion), frame], index: 1 };
     case 'PUSH_RESULT_DETAILS': {
       const result: PushResultFrame = {
         type: 'PUSH_RESULT',
@@ -68,17 +85,23 @@ function wrapperFor(frame: ResponseFrame): {
           retryable: false,
         })),
       };
-      return { frames: [STUB_HEADER, result, frame], index: 2 };
+      return { frames: [stubHeader(wireVersion), result, frame], index: 2 };
     }
     case 'SUB_START':
-      return { frames: [STUB_HEADER, frame, STUB_SUB_END], index: 1 };
+      return {
+        frames: [stubHeader(wireVersion), frame, STUB_SUB_END],
+        index: 1,
+      };
     case 'SUB_END':
-      return { frames: [STUB_HEADER, STUB_SUB_START, frame], index: 2 };
+      return {
+        frames: [stubHeader(wireVersion), STUB_SUB_START, frame],
+        index: 2,
+      };
     case 'COMMIT':
     case 'SEGMENT_REF':
     case 'SEGMENT_INLINE':
       return {
-        frames: [STUB_HEADER, STUB_SUB_START, frame, STUB_SUB_END],
+        frames: [stubHeader(wireVersion), STUB_SUB_START, frame, STUB_SUB_END],
         index: 2,
       };
   }
@@ -88,10 +111,13 @@ function wrapperFor(frame: ResponseFrame): {
  * Encode one response frame (5-byte frame header + payload) using the
  * reference codec.
  */
-export function encodeResponseFrame(frame: ResponseFrame): Uint8Array {
-  const { frames, index } = wrapperFor(frame);
+export function encodeResponseFrame(
+  frame: ResponseFrame,
+  wireVersion = PROTOCOL_WIRE_VERSION,
+): Uint8Array {
+  const { frames, index } = wrapperFor(frame, wireVersion);
   const encoded = encodeMessage({
-    wireVersion: PROTOCOL_WIRE_VERSION,
+    wireVersion,
     msgKind: 'response',
     frames,
   });

package/src/handler.ts

@@ -28,6 +28,7 @@ import {
   limitsOf,
   REMOTE_COMMAND_CLIENT_ID_PREFIX,
   RESOLVER_OUTAGE,
+  touchAuthenticatedPartition,
 } from './context';
 import { SyncError, syncError } from './errors';
 import {
@@ -38,7 +39,7 @@ import {
 import {
   END_FRAME_BYTES,
   encodeResponseFrame,
-  RESPONSE_ENVELOPE_HEADER,
+  responseEnvelopeHeader,
 } from './frame-bytes';
 import type { LeaseRecord } from './lease-store';
 import {
@@ -53,9 +54,12 @@ import { type ProcessedPushCommit, processPushCommitWithTrace } from './push';
 import type { CompiledSchema } from './schema';
 import { compileSchema } from './schema';
 import { computeEffective, type ResolvedScopes } from './scopes';
-import type { ClientSubscription } from './storage';
+import type { ClientSubscription, PartitionRegistryEntry } from './storage';
 
 interface RequestPlan {
+  readonly wireVersion: number;
+  readonly logEpoch: string;
+  readonly epochReset: boolean;
   readonly header: ReqHeaderFrame;
   readonly pushes: readonly PushCommitFrame[];
   readonly pull: PullHeaderFrame | undefined;
@@ -192,6 +196,7 @@ async function planRequest(
   request: RequestMessage,
   ctx: SyncRequestContext,
   schema: CompiledSchema,
+  registry: PartitionRegistryEntry,
 ): Promise<RequestPlan> {
   const header = request.frames[0];
   if (header === undefined || header.type !== 'REQ_HEADER') {
@@ -206,10 +211,32 @@ async function planRequest(
     else if (frame.type === 'SUBSCRIPTION') subFrames.push(frame);
   }
 
+  if (request.wireVersion === 1 && registry.epochRequired) {
+    throw syncError(
+      'sync.client_wire_unsupported',
+      'this partition requires a client that validates log epochs (§2.1)',
+    );
+  }
+  if (
+    request.wireVersion >= 2 &&
+    header.logEpoch === undefined &&
+    pushes.length > 0
+  ) {
+    throw syncError(
+      'sync.invalid_request',
+      'epoch acquisition requests must not carry push commits (§2.1)',
+    );
+  }
+  const epochReset =
+    request.wireVersion >= 2 && header.logEpoch !== registry.logEpoch;
+
   if (header.schemaVersion !== schema.version) {
     // §2.4: no degraded encoding — answer with the schema floor (§1.6).
     // No lease is issued on a floor round (§7.3.3).
     return {
+      wireVersion: request.wireVersion,
+      logEpoch: registry.logEpoch,
+      epochReset,
       header,
       pushes,
       pull,
@@ -220,6 +247,21 @@ async function planRequest(
     };
   }
 
+  if (epochReset) {
+    return {
+      wireVersion: request.wireVersion,
+      logEpoch: registry.logEpoch,
+      epochReset: true,
+      header,
+      pushes: [],
+      pull: undefined,
+      subscriptions: [],
+      resolved: { ok: false },
+      schemaFloor: false,
+      leaseToEmit: undefined,
+    };
+  }
+
   if (header.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
     throw syncError(
       'sync.invalid_client_id',
@@ -313,6 +355,9 @@ async function planRequest(
   });
 
   return {
+    wireVersion: request.wireVersion,
+    logEpoch: registry.logEpoch,
+    epochReset: false,
     header,
     pushes,
     pull,
@@ -325,7 +370,7 @@ async function planRequest(
 
 /** Mutable outcome box shared with the instrumented stream wrapper. */
 interface RequestReport {
-  outcome: 'ok' | 'schema_floor' | 'error';
+  outcome: 'ok' | 'schema_floor' | 'reset' | 'error';
   errorCode?: string;
 }
 
@@ -413,28 +458,48 @@ async function* streamResponse(
   report?: RequestReport,
 ): AsyncGenerator<Uint8Array> {
   const events = ctx.events;
-  yield RESPONSE_ENVELOPE_HEADER;
+  yield responseEnvelopeHeader(plan.wireVersion);
   if (plan.schemaFloor) {
     if (report !== undefined) report.outcome = 'schema_floor';
-    yield encodeResponseFrame({
+    yield encodeResponseFrame(
+      {
+        type: 'RESP_HEADER',
+        requiredSchemaVersion: schema.version,
+        latestSchemaVersion: schema.version,
+        ...(plan.wireVersion >= 2
+          ? { logEpoch: plan.logEpoch, resetRequired: plan.epochReset }
+          : {}),
+      },
+      plan.wireVersion,
+    );
+    yield END_FRAME_BYTES;
+    return;
+  }
+  yield encodeResponseFrame(
+    {
       type: 'RESP_HEADER',
-      requiredSchemaVersion: schema.version,
       latestSchemaVersion: schema.version,
-    });
+      ...(plan.wireVersion >= 2
+        ? { logEpoch: plan.logEpoch, resetRequired: plan.epochReset }
+        : {}),
+    },
+    plan.wireVersion,
+  );
+  if (plan.epochReset) {
+    if (report !== undefined) report.outcome = 'reset';
     yield END_FRAME_BYTES;
     return;
   }
-  yield encodeResponseFrame({
-    type: 'RESP_HEADER',
-    latestSchemaVersion: schema.version,
-  });
   // §7.3.2: the LEASE frame rides immediately after RESP_HEADER.
   if (plan.leaseToEmit !== undefined) {
-    yield encodeResponseFrame({
-      type: 'LEASE',
-      leaseId: plan.leaseToEmit.leaseId,
-      expiresAtMs: plan.leaseToEmit.expiresAtMs,
-    });
+    yield encodeResponseFrame(
+      {
+        type: 'LEASE',
+        leaseId: plan.leaseToEmit.leaseId,
+        expiresAtMs: plan.leaseToEmit.expiresAtMs,
+      },
+      plan.wireVersion,
+    );
     if (events !== undefined) {
       emitEvent(events, {
         type: 'lease.issued',
@@ -461,9 +526,11 @@ async function* streamResponse(
       if (events !== undefined) {
         emitPushEvent(events, ctx, plan.header.clientId, push, processed);
       }
-      yield encodeResponseFrame(frame);
+      yield encodeResponseFrame(frame, plan.wireVersion);
       const details = pushResultDetailsFrame(frame);
-      if (details !== undefined) yield encodeResponseFrame(details);
+      if (details !== undefined) {
+        yield encodeResponseFrame(details, plan.wireVersion);
+      }
     }
 
     // Pull half (§4): subscriptions echoed in request order.
@@ -485,6 +552,7 @@ async function* streamResponse(
           maxSeq,
           horizonSeq,
           trace,
+          plan.logEpoch,
         );
         let status: 'active' | 'revoked' | 'reset' = 'active';
         let bootstrap = false;
@@ -502,7 +570,7 @@ async function* streamResponse(
               changes += frame.changes.length;
             }
           }
-          yield encodeResponseFrame(frame);
+          yield encodeResponseFrame(frame, plan.wireVersion);
           step = await section.next();
         }
         if (step.value.active) cursors.push(step.value.nextCursor);
@@ -556,6 +624,7 @@ async function* streamResponse(
     await ctx.storage.putClientRecord(ctx.partition, {
       clientId: plan.header.clientId,
       actorId: ctx.actorId,
+      wireVersion: plan.wireVersion,
       cursor,
       updatedAtMs: clockOf(ctx)(),
       subscriptions,
@@ -567,15 +636,18 @@ async function* streamResponse(
         report.errorCode = error.code;
       }
       // §1.6: in-band ERROR, then END, nothing else.
-      yield encodeResponseFrame({
-        type: 'ERROR',
-        code: error.code,
-        message: error.message,
-        category: error.category,
-        retryable: error.retryable,
-        recommendedAction: error.recommendedAction,
-        ...(error.details !== undefined ? { details: error.details } : {}),
-      });
+      yield encodeResponseFrame(
+        {
+          type: 'ERROR',
+          code: error.code,
+          message: error.message,
+          category: error.category,
+          retryable: error.retryable,
+          recommendedAction: error.recommendedAction,
+          ...(error.details !== undefined ? { details: error.details } : {}),
+        },
+        plan.wireVersion,
+      );
       yield END_FRAME_BYTES;
       return;
     }
@@ -644,7 +716,8 @@ async function createStreamCore(
   // Relational row tables: create/
   // migrate on first contact; memoized per storage instance thereafter.
   await ctx.storage.ensureSchema(schema);
-  const plan = await planRequest(request, ctx, schema);
+  const registry = await touchAuthenticatedPartition(ctx);
+  const plan = await planRequest(request, ctx, schema, registry);
   if (events === undefined) return streamResponse(plan, ctx, schema);
   const report: RequestReport = { outcome: 'ok' };
   return instrumentedStream(

package/src/index.ts

@@ -64,6 +64,7 @@ export {
   type ReactionTypeMap,
 } from './reactions';
 export * from './realtime';
+export * from './restore';
 export * from './relational-rows';
 export * from './s3-blob-store';
 export * from './s3-segment-store';

package/src/operations.ts

@@ -1,3 +1,7 @@
+import {
+  type AuthoritativeRelationPlan,
+  validateAuthoritativeRelationPlan,
+} from './authoritative-query';
 import {
   decodeRow,
   decodeRemoteOperationRequest,
@@ -9,7 +13,11 @@ import {
   type ScopeMap,
 } from '@syncular/core';
 import type { SyncRequestContext } from './context';
-import { REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE } from './context';
+import {
+  REMOTE_COMMAND_CLIENT_ID_PREFIX,
+  RESOLVER_OUTAGE,
+  touchAuthenticatedPartition,
+} from './context';
 import { SyncError, syncError } from './errors';
 import { processPushOperationsWithTrace } from './push';
 import { compileSchema } from './schema';
@@ -38,6 +46,7 @@ export interface AuthoritativeQueryDescriptor<Params = undefined> {
   readonly hasParams: boolean;
   readonly sql: string;
   readonly tables: readonly string[];
+  readonly relationPlans: readonly AuthoritativeRelationPlan[];
   readonly resultColumns: readonly {
     readonly name: string;
     readonly type:
@@ -276,6 +285,9 @@ export function registerRemoteQuery<Params>(
   options: RemoteQueryOptions<Params>,
 ): RegisteredRemoteQuery {
   if (
+    !Array.isArray(descriptor.relationPlans) ||
+    !descriptor.relationPlans.some((plan) => plan.sql === descriptor.sql) ||
+    descriptor.relationPlans.some((plan) => !Array.isArray(plan.relations)) ||
     descriptor.id.length === 0 ||
     new Set(descriptor.tables).size !== descriptor.tables.length ||
     !Array.isArray(descriptor.resultColumns) ||
@@ -284,9 +296,12 @@ export function registerRemoteQuery<Params>(
       descriptor.resultColumns.length
   ) {
     throw new Error(
-      'remote query requires a non-empty id and unique tables and result columns',
+      'remote query requires generated relation plans, a non-empty id, and unique tables and result columns; regenerate queries',
     );
   }
+  for (const plan of descriptor.relationPlans) {
+    validateAuthoritativeRelationPlan(plan, descriptor.tables);
+  }
   if (
     !Number.isSafeInteger(options.maxRows) ||
     options.maxRows < 1 ||
@@ -390,12 +405,29 @@ export function registerRemoteQuery<Params>(
           'configured storage does not implement authoritative queries',
         );
       }
-      await ctx.storage.ensureSchema(schema);
       const selectedSql = descriptor.sqlFor?.(params) ?? descriptor.sql;
+      const plan = descriptor.relationPlans.find(
+        (candidate) => candidate.sql === selectedSql,
+      );
+      if (plan === undefined) {
+        throw syncError(
+          'operation.invalid_request',
+          'selected SQL has no generated relation plan; regenerate queries',
+        );
+      }
+      await ctx.storage.ensureSchema(schema);
+      const prefix = 'SELECT * FROM (';
       let result;
       try {
         result = await ctx.storage.queryAuthoritative(ctx.partition, {
-          sql: `SELECT * FROM (${selectedSql}) AS "_syncular_registered_query" LIMIT ?`,
+          plan: {
+            sql: `${prefix}${selectedSql}) AS "_syncular_registered_query" LIMIT ?`,
+            relations: plan.relations.map((relation) => ({
+              ...relation,
+              start: relation.start + prefix.length,
+              end: relation.end + prefix.length,
+            })),
+          },
           params: [...descriptor.bind(params), options.maxRows + 1],
           tables: descriptor.tables,
         });
@@ -673,6 +705,7 @@ export async function handleRemoteOperation(
     return encodeRemoteOperationError(error, 'operation.invalid_request');
   }
   try {
+    await touchAuthenticatedPartition(ctx);
     if (request.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
       throw syncError(
         'sync.invalid_client_id',