@enbox/agent 0.5.11 → 0.5.13

package/src/sync-engine-level.ts

@@ -1173,7 +1173,19 @@ export class SyncEngineLevel implements SyncEngine {
     // Resolve the cursor from the link's pull checkpoint (preferred) or legacy storage.
     const cursorKey = this.buildCursorKey(did, dwnUrl, protocol);
     const link = this._activeLinks.get(cursorKey);
-    const cursor = link?.pull.contiguousAppliedToken ?? await this.getCursor(cursorKey);
+    let cursor = link?.pull.contiguousAppliedToken ?? await this.getCursor(cursorKey);
+
+    // Guard against corrupted tokens with empty fields — these would fail
+    // MessagesSubscribe JSON schema validation (minLength: 1). Discard and
+    // start from the beginning rather than crash the subscription.
+    if (cursor && (!cursor.streamId || !cursor.messageCid || !cursor.epoch || !cursor.position)) {
+      console.warn(`SyncEngineLevel: Discarding stored cursor with empty field(s) for ${did} -> ${dwnUrl}`);
+      cursor = undefined;
+      if (link) {
+        ReplicationLedger.resetCheckpoint(link.pull);
+        await this.ledger.saveLink(link);
+      }
+    }
 
     // Build the MessagesSubscribe filters.
     // When the link has protocolPathPrefixes, include them in the filter so the
@@ -1426,7 +1438,11 @@ export class SyncEngineLevel implements SyncEngine {
     // a fresh cursor-stamped message after reconnection.
     const resubscribeFactory: ResubscribeFactory = async (resumeCursor?: ProgressToken) => {
       // On reconnect, use the latest durable checkpoint position if available.
-      const effectiveCursor = resumeCursor ?? link?.pull.contiguousAppliedToken ?? cursor;
+      // Discard tokens with empty fields to avoid schema validation failures.
+      let effectiveCursor = resumeCursor ?? link?.pull.contiguousAppliedToken ?? cursor;
+      if (effectiveCursor && (!effectiveCursor.streamId || !effectiveCursor.messageCid || !effectiveCursor.epoch || !effectiveCursor.position)) {
+        effectiveCursor = undefined;
+      }
       const resumeRequest = {
         ...subscribeRequest,
         messageParams: { ...subscribeRequest.messageParams, cursor: effectiveCursor },
@@ -1496,6 +1512,19 @@ export class SyncEngineLevel implements SyncEngine {
   }): Promise<void> {
     const { did, delegateDid, dwnUrl, protocol } = target;
 
+    // Guard against corrupted push cursors — same validation as the pull side.
+    let pushCursor = target.pushCursor;
+    if (pushCursor && (!pushCursor.streamId || !pushCursor.messageCid || !pushCursor.epoch || !pushCursor.position)) {
+      console.warn(`SyncEngineLevel: Discarding stored push cursor with empty field(s) for ${did} -> ${dwnUrl}`);
+      pushCursor = undefined;
+      const cursorKey = this.buildCursorKey(did, dwnUrl, protocol);
+      const link = this._activeLinks.get(cursorKey);
+      if (link) {
+        ReplicationLedger.resetCheckpoint(link.push);
+        await this.ledger.saveLink(link);
+      }
+    }
+
     // Build filters scoped to the protocol (if any).
     const filters = protocol ? [{ protocol }] : [];
 
@@ -1584,7 +1613,7 @@ export class SyncEngineLevel implements SyncEngine {
       target              : did,
       messageType         : DwnInterface.MessagesSubscribe,
       granteeDid          : delegateDid,
-      messageParams       : { filters, permissionGrantId, cursor: target.pushCursor },
+      messageParams       : { filters, permissionGrantId, cursor: pushCursor },
       subscriptionHandler : subscriptionHandler as any,
     });
 
@@ -1655,10 +1684,13 @@ export class SyncEngineLevel implements SyncEngine {
           await this.ledger.saveLink(link);
         }
 
-        // Re-queue failed entries so they are retried on the next debounce
-        // cycle (or picked up by the SMT integrity check).
+        // Re-queue only TRANSIENT failures for retry. Permanent failures (400/401/403)
+        // are dropped — they will never succeed regardless of retry.
         if (result.failed.length > 0) {
-          console.error(`SyncEngineLevel: Push-on-write failed for ${did} -> ${dwnUrl}: ${result.failed.length} of ${cids.length} messages failed`);
+          console.error(
+            `SyncEngineLevel: Push-on-write failed for ${did} -> ${dwnUrl}: ` +
+            `${result.failed.length} transient failures of ${cids.length} messages`
+          );
           const failedSet = new Set(result.failed);
           const failedEntries = pushEntries.filter(e => failedSet.has(e.cid));
           let requeued = this._pendingPushCids.get(targetKey);
@@ -1672,9 +1704,12 @@ export class SyncEngineLevel implements SyncEngine {
           if (!this._pushDebounceTimer) {
             this._pushDebounceTimer = setTimeout((): void => {
               void this.flushPendingPushes();
-            }, PUSH_DEBOUNCE_MS * 4); // Back off: 1 second instead of 250ms.
+            }, PUSH_DEBOUNCE_MS * 4);
           }
         }
+        // Permanent failures are logged by pushMessages but NOT re-queued.
+        // They will be rediscovered by the next SMT integrity check if the
+        // local/remote state has changed, but won't spin in a retry loop.
       } catch (error: any) {
         // Truly unexpected error (not per-message failure). Re-queue entire
         // batch so entries aren't silently dropped from the debounce queue.
@@ -1717,10 +1752,10 @@ export class SyncEngineLevel implements SyncEngine {
       try {
         const parsed = JSON.parse(raw);
         if (parsed && typeof parsed === 'object' &&
-            typeof parsed.streamId === 'string' &&
-            typeof parsed.epoch === 'string' &&
-            typeof parsed.position === 'string' &&
-            typeof parsed.messageCid === 'string') {
+            typeof parsed.streamId === 'string' && parsed.streamId.length > 0 &&
+            typeof parsed.epoch === 'string' && parsed.epoch.length > 0 &&
+            typeof parsed.position === 'string' && parsed.position.length > 0 &&
+            typeof parsed.messageCid === 'string' && parsed.messageCid.length > 0) {
           return parsed as ProgressToken;
         }
       } catch {

package/src/sync-messages.ts

@@ -37,6 +37,20 @@ export function syncMessageReplyIsSuccessful(reply: UnionMessageReply): boolean
     );
 }
 
+/**
+ * Determines whether a failed push reply represents a permanent failure that
+ * should NOT be retried. Permanent failures include protocol violations (400),
+ * authorization errors (401/403), and schema validation errors that will never
+ * succeed regardless of retry.
+ *
+ * Transient failures (5xx, network errors) are worth retrying.
+ */
+export function isPermanentPushFailure(reply: UnionMessageReply): boolean {
+  return reply.status.code === 400 ||
+    reply.status.code === 401 ||
+    reply.status.code === 403;
+}
+
 /**
  * Helper to get the CID of a message for logging purposes.
  */
@@ -313,6 +327,7 @@ export async function pushMessages({ did, dwnUrl, delegateDid, protocol, message
 }): Promise<PushResult> {
   const succeeded: string[] = [];
   const failed: string[] = [];
+  const permanentlyFailed: string[] = [];
 
   // Step 1: Fetch all local messages (streams are pull-based, not yet consumed).
   const fetched: SyncMessageEntry[] = [];
@@ -342,17 +357,25 @@ export async function pushMessages({ did, dwnUrl, delegateDid, protocol, message
 
       if (syncMessageReplyIsSuccessful(reply)) {
         succeeded.push(cid);
+      } else if (isPermanentPushFailure(reply)) {
+        // Permanent failures (400/401/403) will never succeed — do NOT retry.
+        // These include protocol violations (RecordLimitExceeded), auth errors,
+        // and schema validation failures.
+        console.warn(`SyncEngineLevel: push permanently failed for ${cid}: ${reply.status.code} ${reply.status.detail}`);
+        permanentlyFailed.push(cid);
       } else {
+        // Transient failures (5xx, etc.) — worth retrying.
         console.error(`SyncEngineLevel: push failed for ${cid}: ${reply.status.code} ${reply.status.detail}`);
         failed.push(cid);
       }
     } catch (error: any) {
+      // Network errors — transient, worth retrying.
       console.error(`SyncEngineLevel: push error for ${cid}: ${error.message ?? error}`);
       failed.push(cid);
     }
   }
 
-  return { succeeded, failed };
+  return { succeeded, failed, permanentlyFailed };
 }
 
 /**

package/src/types/sync.ts

@@ -194,8 +194,10 @@ export type ReplicationLinkState = {
 export type PushResult = {
   /** messageCids that were accepted (202/204/409 — idempotent success). */
   succeeded: string[];
-  /** messageCids that failed (retryable or hard error). */
+  /** messageCids that failed with a transient error (5xx, network) — worth retrying. */
   failed: string[];
+  /** messageCids that failed permanently (400/401/403) — will never succeed, do NOT retry. */
+  permanentlyFailed: string[];
 };
 
 /**