@syncular/core 0.40.0 → 0.41.0

package/dist/frames.d.ts

@@ -5,6 +5,7 @@ export declare const FrameType: {
     readonly PUSH_COMMIT: 2;
     readonly PULL_HEADER: 3;
     readonly SUBSCRIPTION: 4;
+    readonly ROUND_FAILURE: 5;
     readonly RESP_HEADER: 16;
     readonly PUSH_RESULT: 17;
     readonly SUB_START: 18;

package/dist/frames.js

@@ -5,6 +5,7 @@ export const FrameType = {
     PUSH_COMMIT: 0x02,
     PULL_HEADER: 0x03,
     SUBSCRIPTION: 0x04,
+    ROUND_FAILURE: 0x05,
     RESP_HEADER: 0x10,
     PUSH_RESULT: 0x11,
     SUB_START: 0x12,
@@ -22,6 +23,7 @@ export const REQUEST_FRAME_TYPES = new Set([
     FrameType.PUSH_COMMIT,
     FrameType.PULL_HEADER,
     FrameType.SUBSCRIPTION,
+    FrameType.ROUND_FAILURE,
 ]);
 /** Known response frame types (excluding END). */
 export const RESPONSE_FRAME_TYPES = new Set([

package/dist/message.d.ts

@@ -45,7 +45,15 @@ export interface UnknownFrame {
     frameType: number;
     payload: Uint8Array;
 }
-export type RequestFrame = ReqHeaderFrame | PushCommitFrame | PullHeaderFrame | SubscriptionFrame | UnknownFrame;
+/**
+ * §1.5: the code of the client's last round that failed where the server
+ * could not see it. Reported once, immediately after `REQ_HEADER`.
+ */
+export interface RoundFailureFrame {
+    type: 'ROUND_FAILURE';
+    code: string;
+}
+export type RequestFrame = ReqHeaderFrame | RoundFailureFrame | PushCommitFrame | PullHeaderFrame | SubscriptionFrame | UnknownFrame;
 export interface RespHeaderFrame {
     type: 'RESP_HEADER';
     requiredSchemaVersion?: number;
@@ -183,6 +191,8 @@ export interface ResponseMessage {
     frames: ResponseFrame[];
 }
 export type SyncMessage = RequestMessage | ResponseMessage;
+/** §1.5: `code` is a legal `ROUND_FAILURE` code (grammar and byte length). */
+export declare function isRoundFailureCode(code: string): boolean;
 export declare function validateFrameSequence(message: SyncMessage): void;
 export declare function encodeMessage(message: SyncMessage): Uint8Array;
 export declare function decodeMessage(bytes: Uint8Array): SyncMessage;

package/dist/message.js

@@ -37,6 +37,19 @@ function requireJsonDocument(raw, what) {
     }
     return raw;
 }
+/** §1.5: a `ROUND_FAILURE` code is a lowercase dotted catalog code. */
+const ROUND_FAILURE_CODE = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/;
+/** §1.5: `code` is a legal `ROUND_FAILURE` code (grammar and byte length). */
+export function isRoundFailureCode(code) {
+    // At most 64 bytes on the wire (§1.5), so the UTF-8 length decides it.
+    return ROUND_FAILURE_CODE.test(code) && utf8Encode(code).length <= 64;
+}
+/** Shared by the frame decoder and encoder (§1.5 payload invariants). */
+function validateRoundFailureCode(code, fail) {
+    if (!isRoundFailureCode(code)) {
+        fail('ROUND_FAILURE.code must be a lowercase dotted code of at most 64 bytes');
+    }
+}
 // ---------------------------------------------------------------------------
 // Frame payload decoders (each consumes exactly the frame payload)
 // ---------------------------------------------------------------------------
@@ -62,6 +75,11 @@ function decodeReqHeader(r, wireVersion) {
         logEpoch: logEpoch,
     });
 }
+function decodeRoundFailure(r) {
+    const code = r.str();
+    validateRoundFailureCode(code, invalid);
+    return { type: 'ROUND_FAILURE', code };
+}
 function decodePushCommit(r) {
     const clientCommitId = r.str();
     if (clientCommitId.length === 0) {
@@ -388,6 +406,9 @@ function decodeRequestFrame(frameType, payload, wireVersion) {
         case FrameType.REQ_HEADER:
             frame = decodeReqHeader(r, wireVersion);
             break;
+        case FrameType.ROUND_FAILURE:
+            frame = decodeRoundFailure(r);
+            break;
         case FrameType.PUSH_COMMIT:
             frame = decodePushCommit(r);
             break;
@@ -459,11 +480,22 @@ function validateRequestSequence(frames) {
     }
     let pushCount = 0;
     let hasPull = false;
+    let index = 1;
+    let sawRoundFailure = false;
     for (const frame of frames.slice(1)) {
         switch (frame.type) {
             case 'REQ_HEADER':
                 invalid('duplicate REQ_HEADER frame');
                 break;
+            case 'ROUND_FAILURE':
+                // §1.5: at most one, immediately after REQ_HEADER.
+                if (sawRoundFailure)
+                    invalid('duplicate ROUND_FAILURE frame');
+                if (index !== 1) {
+                    invalid('ROUND_FAILURE frame must immediately follow REQ_HEADER');
+                }
+                sawRoundFailure = true;
+                break;
             case 'PUSH_COMMIT':
                 if (hasPull)
                     invalid('PUSH_COMMIT frame after PULL_HEADER');
@@ -481,6 +513,7 @@ function validateRequestSequence(frames) {
             case 'UNKNOWN':
                 break;
         }
+        index += 1;
     }
     if (pushCount === 0 && !hasPull) {
         invalid('request must contain PUSH_COMMIT or PULL_HEADER frames');
@@ -631,6 +664,11 @@ function encodeFrame(frame, wireVersion) {
             }
             break;
         }
+        case 'ROUND_FAILURE': {
+            validateRoundFailureCode(frame.code, encodeInvalid);
+            w.str(frame.code);
+            break;
+        }
         case 'PUSH_COMMIT': {
             if (frame.clientCommitId.length === 0) {
                 encodeInvalid('PUSH_COMMIT.clientCommitId must be non-empty');

package/dist/render.js

@@ -99,6 +99,8 @@ function renderFrame(frame) {
                 schemaVersion: frame.schemaVersion,
                 ...(frame.logEpoch !== undefined ? { logEpoch: frame.logEpoch } : {}),
             };
+        case 'ROUND_FAILURE':
+            return { type: 'ROUND_FAILURE', code: frame.code };
         case 'PUSH_COMMIT':
             return {
                 type: 'PUSH_COMMIT',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/core",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Core protocol types and shared utilities for the Syncular sync framework",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",

package/src/frames.ts

@@ -5,6 +5,7 @@ export const FrameType = {
   PUSH_COMMIT: 0x02,
   PULL_HEADER: 0x03,
   SUBSCRIPTION: 0x04,
+  ROUND_FAILURE: 0x05,
   RESP_HEADER: 0x10,
   PUSH_RESULT: 0x11,
   SUB_START: 0x12,
@@ -25,6 +26,7 @@ export const REQUEST_FRAME_TYPES: ReadonlySet<number> = new Set([
   FrameType.PUSH_COMMIT,
   FrameType.PULL_HEADER,
   FrameType.SUBSCRIPTION,
+  FrameType.ROUND_FAILURE,
 ]);
 
 /** Known response frame types (excluding END). */

package/src/message.ts

@@ -89,8 +89,18 @@ export interface UnknownFrame {
   payload: Uint8Array;
 }
 
+/**
+ * §1.5: the code of the client's last round that failed where the server
+ * could not see it. Reported once, immediately after `REQ_HEADER`.
+ */
+export interface RoundFailureFrame {
+  type: 'ROUND_FAILURE';
+  code: string;
+}
+
 export type RequestFrame =
   | ReqHeaderFrame
+  | RoundFailureFrame
   | PushCommitFrame
   | PullHeaderFrame
   | SubscriptionFrame
@@ -285,6 +295,27 @@ function requireJsonDocument(raw: string, what: string): string {
   return raw;
 }
 
+/** §1.5: a `ROUND_FAILURE` code is a lowercase dotted catalog code. */
+const ROUND_FAILURE_CODE = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/;
+
+/** §1.5: `code` is a legal `ROUND_FAILURE` code (grammar and byte length). */
+export function isRoundFailureCode(code: string): boolean {
+  // At most 64 bytes on the wire (§1.5), so the UTF-8 length decides it.
+  return ROUND_FAILURE_CODE.test(code) && utf8Encode(code).length <= 64;
+}
+
+/** Shared by the frame decoder and encoder (§1.5 payload invariants). */
+function validateRoundFailureCode(
+  code: string,
+  fail: (message: string) => never,
+): void {
+  if (!isRoundFailureCode(code)) {
+    fail(
+      'ROUND_FAILURE.code must be a lowercase dotted code of at most 64 bytes',
+    );
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Frame payload decoders (each consumes exactly the frame payload)
 // ---------------------------------------------------------------------------
@@ -311,6 +342,12 @@ function decodeReqHeader(r: ByteReader, wireVersion: number): ReqHeaderFrame {
   });
 }
 
+function decodeRoundFailure(r: ByteReader): RoundFailureFrame {
+  const code = r.str();
+  validateRoundFailureCode(code, invalid);
+  return { type: 'ROUND_FAILURE', code };
+}
+
 function decodePushCommit(r: ByteReader): PushCommitFrame {
   const clientCommitId = r.str();
   if (clientCommitId.length === 0) {
@@ -649,6 +686,9 @@ function decodeRequestFrame(
     case FrameType.REQ_HEADER:
       frame = decodeReqHeader(r, wireVersion);
       break;
+    case FrameType.ROUND_FAILURE:
+      frame = decodeRoundFailure(r);
+      break;
     case FrameType.PUSH_COMMIT:
       frame = decodePushCommit(r);
       break;
@@ -731,11 +771,21 @@ function validateRequestSequence(frames: readonly RequestFrame[]): void {
   }
   let pushCount = 0;
   let hasPull = false;
+  let index = 1;
+  let sawRoundFailure = false;
   for (const frame of frames.slice(1)) {
     switch (frame.type) {
       case 'REQ_HEADER':
         invalid('duplicate REQ_HEADER frame');
         break;
+      case 'ROUND_FAILURE':
+        // §1.5: at most one, immediately after REQ_HEADER.
+        if (sawRoundFailure) invalid('duplicate ROUND_FAILURE frame');
+        if (index !== 1) {
+          invalid('ROUND_FAILURE frame must immediately follow REQ_HEADER');
+        }
+        sawRoundFailure = true;
+        break;
       case 'PUSH_COMMIT':
         if (hasPull) invalid('PUSH_COMMIT frame after PULL_HEADER');
         pushCount += 1;
@@ -750,6 +800,7 @@ function validateRequestSequence(frames: readonly RequestFrame[]): void {
       case 'UNKNOWN':
         break;
     }
+    index += 1;
   }
   if (pushCount === 0 && !hasPull) {
     invalid('request must contain PUSH_COMMIT or PULL_HEADER frames');
@@ -913,6 +964,11 @@ function encodeFrame(
       }
       break;
     }
+    case 'ROUND_FAILURE': {
+      validateRoundFailureCode(frame.code, encodeInvalid);
+      w.str(frame.code);
+      break;
+    }
     case 'PUSH_COMMIT': {
       if (frame.clientCommitId.length === 0) {
         encodeInvalid('PUSH_COMMIT.clientCommitId must be non-empty');

package/src/render.ts

@@ -140,6 +140,8 @@ function renderFrame(frame: RequestFrame | ResponseFrame): JsonValue {
         schemaVersion: frame.schemaVersion,
         ...(frame.logEpoch !== undefined ? { logEpoch: frame.logEpoch } : {}),
       };
+    case 'ROUND_FAILURE':
+      return { type: 'ROUND_FAILURE', code: frame.code };
     case 'PUSH_COMMIT':
       return {
         type: 'PUSH_COMMIT',