@procedures/store 0.37.0 → 0.39.0

package/src/storage/hybrid.ts

@@ -222,6 +222,24 @@ export interface HybridStorageOptions {
    */
   isUnavailable?: (error: unknown) => boolean;
 
+  /**
+   * True when an error of the remote refuses a queued write for good: a new send gets the same
+   * refusal (roadmap O67). Such a write leaves the queue, and the push goes on with the next write.
+   * An error for which `isUnavailable` gives true is never a refusal. Another error keeps the write
+   * at the head of the queue, and the next push sends it again. The default: the codes
+   * `FORBIDDEN`, `VALIDATION_ERROR`, `INVALID_REQUEST`, `NOT_EXPOSED` and `NOT_DECLARED`. A
+   * `TIMEOUT` or an `INTERNAL_ERROR` is not a refusal, because the remote can take a new send.
+   * `UNAUTHORIZED` is not a refusal by default, because a new token can let the write through.
+   */
+  isRefusal?: (error: unknown) => boolean;
+
+  /**
+   * This hook gets each queued write that the remote refused (roadmap O67). The local copy of its
+   * ids gets the remote values again, except for an id that a later queued write changes. An
+   * error of the hook does not stop the queue.
+   */
+  onRefused?: (refusal: QueueRefusal) => void | Promise<void>;
+
   /**
    * The storage of the local copy (roadmap R45). A durable storage, for example `SqliteStorage`
    * of `@procedures/sqlite`, keeps the local copy after a restart. Then a new storage in
@@ -533,6 +551,21 @@ class SyncTimer {
   }
 }
 
+/** A queued write that the remote refused: the argument of the hook `onRefused` (roadmap O67). */
+export interface QueueRefusal {
+  /** The write. It is not in the queue now. */
+  operation: QueuedOperation;
+  /** The ids of the write, or `"*"` for a clear. */
+  ids: string[] | "*";
+  /** The error of the remote. */
+  error: unknown;
+  /**
+   * True when the local copy got the remote values of the ids. A clear asks for a full pull, and
+   * gives false. A failed read of the remote also gives false.
+   */
+  restored: boolean;
+}
+
 /**
  * The remote did not take a write of the write-through mode. The write is in the local cache and
  * in the queue, and the storage sends it later (roadmap R2). `cause` is the error of the remote.
@@ -631,6 +664,15 @@ const defaultIsUnavailable = (error: unknown): boolean => {
   return retryable === true || code === undefined;
 };
 
+/** The codes of the protocol that refuse a queued write for good: a new send gets the same refusal (roadmap O67). */
+const REFUSAL_CODES: ReadonlySet<string> = new Set(["FORBIDDEN", "VALIDATION_ERROR", "INVALID_REQUEST", "NOT_EXPOSED", "NOT_DECLARED"]);
+
+/** The default of `isRefusal`: an error with a code of `REFUSAL_CODES`. */
+const defaultIsRefusal = (error: unknown): boolean => {
+  const code = (error as { code?: unknown } | null | undefined)?.code;
+  return typeof code === "string" && REFUSAL_CODES.has(code);
+};
+
 /** True when a remote does not know a procedure: an older server without `changes`. */
 const isNotFound = (error: unknown): boolean =>
   typeof error === "object" && error !== null && (error as { code?: unknown }).code === "NOT_FOUND";
@@ -891,6 +933,8 @@ export class HybridStorage<T> implements CollectionStorage<T> {
     maxOfflineOps: number;
     offlineQueue: boolean;
     isUnavailable: (error: unknown) => boolean;
+    isRefusal: (error: unknown) => boolean;
+    onRefused?: (refusal: QueueRefusal) => void | Promise<void>;
   };
   private mode: HybridMode;
   private offlineOps: QueuedOperation[] = [];
@@ -1032,6 +1076,8 @@ export class HybridStorage<T> implements CollectionStorage<T> {
       maxOfflineOps: options.maxOfflineOps ?? 1000,
       offlineQueue: options.offlineQueue ?? true,
       isUnavailable: options.isUnavailable ?? defaultIsUnavailable,
+      isRefusal: options.isRefusal ?? defaultIsRefusal,
+      ...(options.onRefused !== undefined && { onRefused: options.onRefused }),
     };
     this.statusListeners = new StorageListeners<SyncStatus>(options.onListenerError);
     this.queryPolicy = options.queryPolicy;
@@ -2846,6 +2892,22 @@ export class HybridStorage<T> implements CollectionStorage<T> {
             await this.resolvePushConflicts(op, conflicts);
             continue;
           }
+          if (
+            conflicts === undefined &&
+            !(error instanceof QueueStoreError) &&
+            !this.options.isUnavailable(error) &&
+            this.options.isRefusal(error)
+          ) {
+            // The remote refused the write: it leaves the queue, and the push goes on (roadmap O67)
+            this.isOnline = true;
+            if (this.offlineOps[0] === op) {
+              this.offlineOps.shift();
+              sent++;
+              this.storeDirty = true;
+            }
+            await this.refuseQueued(op, error);
+            continue;
+          }
           // This operation and the later ones stay queued
           if (conflicts === undefined) this.isOnline = false;
           throw error;
@@ -2869,6 +2931,49 @@ export class HybridStorage<T> implements CollectionStorage<T> {
     }
   }
 
+  /**
+   * This method ends a queued write that the remote refused (roadmap O67). The local copy of its ids
+   * gets the remote values, and the hook `onRefused` gets the refusal. A refused clear asks for a
+   * full pull.
+   */
+  private async refuseQueued(op: QueuedOperation, error: unknown): Promise<void> {
+    const ids = idsOf(op);
+    const all = ids.includes("*");
+    let restored = false;
+    if (all) {
+      this.requestPull(undefined, true);
+    } else if (this.mode !== "remote-only") {
+      restored = await this.restoreRemote(ids.filter((id) => !this.hasPendingOp(id)));
+    }
+    try {
+      await this.options.onRefused?.({ operation: op, ids: all ? "*" : ids, error, restored });
+    } catch {
+      // An error of the hook does not stop the queue
+    }
+  }
+
+  /**
+   * This method writes the remote values of these ids into the local copy. It skips an id that a
+   * queued write or an own write in flight changes. It gives false when the read of the remote fails.
+   */
+  private async restoreRemote(ids: string[]): Promise<boolean> {
+    if (ids.length === 0) return true;
+    let items: Map<string, T>;
+    try {
+      items = await this.remote.getBatch(ids);
+    } catch {
+      return false;
+    }
+    for (const id of ids) {
+      if (this.hasPendingOp(id) || this.waitsForRemote(id)) continue;
+      const item = items.get(id);
+      if (item === undefined) await this.localDelete(id, this.syncOrigin);
+      else await this.localSet(id, item, this.syncOrigin);
+      this.noteBase(id, item);
+    }
+    return true;
+  }
+
   /** Run syncs one at a time. */
   private serialize<R>(run: () => Promise<R>): Promise<R> {
     const next = this.syncChain.then(run, run);

package/src/storage/index.ts

@@ -52,6 +52,7 @@ export type {
   HybridStorageOptions,
   HybridMode,
   LocalCopyStorage,
+  QueueRefusal,
   RemoteApplyCause,
   RemoteApplyContext,
   RemoteApplyHook,