@procedures/store 0.47.2 → 0.48.0

package/dist/storage/hybrid.js

@@ -2,7 +2,7 @@
  * Hybrid Storage Implementation
  *
  * A local copy (an `InMemoryStorage`, or the `local` storage that the application gives) in
- * front of a remote `CollectionStorage` (often an `ApiStorage`). The storage has four modes, and
+ * front of a remote `CollectionStorage` (often an `ApiStorage`). The storage has five modes, and
  * `setMode()` changes the mode while the storage operates (roadmap R28):
  *
  * | Mode | Reads | Writes | Remote calls |
@@ -11,6 +11,7 @@
  * | `write-through` | the local copy, the remote on a miss | the local copy, then the remote | yes |
  * | `write-back` | the local copy, the remote on a miss | the local copy and the queue, a timer sends it | yes |
  * | `remote-only` | the remote | the remote | yes, and no local copy |
+ * | `read-only` | the local copy, the remote on a miss | refused with `ReadOnlyError` | reads and pulls only |
  *
  * - The queue is durable through the `queueStore` that the application gives.
  * - A sync asks for the changes since a version when the remote has `getChangesSince`.
@@ -50,7 +51,11 @@ import { optionalMs, realClock } from "@procedures/client/browser";
 import { backoffDelay } from "@mark1russell7/service/backoff";
 import { MemoryQueueStore, idsOf, withoutId } from "./queue.js";
 import { isSyncState } from "./sync-state.js";
-const MODES = new Set(["local-only", "write-through", "write-back", "remote-only"]);
+const MODES = new Set(["local-only", "write-through", "write-back", "remote-only", "read-only"]);
+/** True for the modes that keep a local copy and read the remote changes into it. */
+const pullsRemote = (mode) => mode === "write-through" || mode === "write-back" || mode === "read-only";
+/** True for the modes that send writes to the remote. */
+const pushesRemote = (mode) => mode !== "local-only" && mode !== "read-only";
 /** The hints of an apply without hints. */
 const NO_HINTS = Object.freeze([]);
 /** The most hints that a pull keeps for the hook. A pull drops the older ones. */
@@ -178,6 +183,19 @@ export class QueueFullError extends Error {
         super(`The queue of operations is full (${max} operations): the storage refuses the write`);
     }
 }
+/**
+ * The storage is in `read-only` mode, so it refuses the write (roadmap CLI-89). The local copy, the
+ * queue and the remote did not change. `operation` is the name of the refused operation.
+ */
+export class ReadOnlyError extends Error {
+    operation;
+    name = "ReadOnlyError";
+    code = "READ_ONLY";
+    constructor(operation) {
+        super(`The storage is in read-only mode: it refuses the operation ${operation}`);
+        this.operation = operation;
+    }
+}
 /** The remote gave items without a key, so a sync cannot know which local items to keep. */
 export class MissingKeysError extends Error {
     name = "MissingKeysError";
@@ -273,7 +291,7 @@ const defaultKeyOf = (item) => {
 };
 function checkMode(mode) {
     if (typeof mode !== "string" || !MODES.has(mode)) {
-        throw new TypeError(`Unknown mode ${JSON.stringify(mode)}: use local-only, write-through, write-back or remote-only`);
+        throw new TypeError(`Unknown mode ${JSON.stringify(mode)}: use local-only, write-through, write-back, remote-only or read-only`);
     }
     return mode;
 }
@@ -924,7 +942,7 @@ export class HybridStorage {
         const feed = this.feed;
         if (!feed)
             return;
-        const wanted = !this.closed && (this.mode === "write-through" || this.mode === "write-back");
+        const wanted = !this.closed && pullsRemote(this.mode);
         if (wanted === (this.feedStop !== undefined))
             return;
         const token = ++this.feedToken;
@@ -988,7 +1006,7 @@ export class HybridStorage {
     async applyFeed(changes, mark) {
         if (this.loadError)
             throw this.loadError;
-        if (this.closed || (this.mode !== "write-through" && this.mode !== "write-back"))
+        if (this.closed || !pullsRemote(this.mode))
             return;
         if (changes.version === this.cursor)
             return;
@@ -1025,7 +1043,7 @@ export class HybridStorage {
     async applyHint(hint, mark) {
         if (this.loadError)
             throw this.loadError;
-        if (this.closed || (this.mode !== "write-through" && this.mode !== "write-back"))
+        if (this.closed || !pullsRemote(this.mode))
             return;
         // The remote cannot tell what changed: a full pull
         if (hint.reset === true)
@@ -1073,7 +1091,7 @@ export class HybridStorage {
             return this.track("pull", async () => {
                 if (this.loadError)
                     throw this.loadError;
-                if (this.mode === "write-through" || this.mode === "write-back")
+                if (pullsRemote(this.mode))
                     await this.pullThrough(hints.length > 0 ? "hint" : "gap", hints, full);
             });
         }))
@@ -1254,7 +1272,8 @@ export class HybridStorage {
      * - The switch waits for the operations that run. The operations that start later wait for
      *   the switch. Switches and syncs run one at a time.
      * - A switch to a remote mode sends the queue first. A switch to `local-only` makes no remote
-     *   call: the queue stays until the next remote mode.
+     *   call: the queue stays until the next remote mode. A switch to `read-only` also sends the
+     *   queue first, so this mode starts with an empty queue, or the switch fails.
      * - A switch to `remote-only` drops the local copy, after the queue reached the remote.
      * - A switch from `local-only` or `remote-only` to a mode with a local copy syncs the local
      *   copy. The reads wait for the sync.
@@ -1321,7 +1340,7 @@ export class HybridStorage {
     }
     /**
      * This method starts and stops the timers for the mode. The push timer runs in `write-back`, the
-     * pull timer in `write-through` and `write-back`, and the send of the queue after a failure only
+     * pull timer in `write-through`, `write-back` and `read-only`, and the send of the queue after a failure only
      * in `write-through`. A failed run reports its error in the status, and the next delay grows.
      */
     updateTimers() {
@@ -1331,7 +1350,7 @@ export class HybridStorage {
             this.pushTimer?.start();
         else
             this.pushTimer?.stop();
-        if (this.mode === "write-through" || this.mode === "write-back")
+        if (pullsRemote(this.mode))
             this.pullTimer?.start();
         else
             this.pullTimer?.stop();
@@ -1510,6 +1529,7 @@ export class HybridStorage {
      * One write, in the mode of the storage. The result is the result of the local copy, or of the
      * remote in `remote-only` mode.
      *
+     * - `read-only`: the write throws `ReadOnlyError`, and nothing changes.
      * - `remote-only`: the remote only. Its error passes through.
      * - `write-back` and `local-only`: the local copy and the queue. A full queue refuses the write
      *   before the local change. The queue store keeps the operation before the write ends.
@@ -1525,6 +1545,8 @@ export class HybridStorage {
      */
     write(type, data, ids, origin, applyLocal, applyRemote) {
         return this.run(false, async () => {
+            if (this.mode === "read-only")
+                throw new ReadOnlyError(type);
             const op = { type, data, timestamp: Date.now() };
             if (this.mode === "remote-only") {
                 const send = async () => {
@@ -1709,7 +1731,7 @@ export class HybridStorage {
             this.deferred.delete(id);
             const mark = this.writeSeq;
             let item = deferred.item;
-            if (this.mode === "write-through" || this.mode === "write-back") {
+            if (pullsRemote(this.mode)) {
                 try {
                     item = await this.remote.get(id);
                     this.isOnline = true;
@@ -1782,8 +1804,8 @@ export class HybridStorage {
     /**
      * Sync all pending offline operations to remote.
      * Processes queued operations in order. When one fails, it and the later operations stay in
-     * the queue: the operations that reached the remote are not sent again. In `local-only` mode,
-     * the call does nothing.
+     * the queue: the operations that reached the remote are not sent again. In the modes `local-only`
+     * and `read-only`, the call does nothing.
      */
     syncToRemote() {
         if (this.closed)
@@ -1792,7 +1814,7 @@ export class HybridStorage {
     }
     /**
      * This method sends the queue to the remote (roadmap R28). `ProcedureServer.useStorage` uses it. In
-     * `local-only` mode, it sends nothing: the queue waits for a remote mode.
+     * the modes `local-only` and `read-only`, it sends nothing: the queue waits for a mode that writes.
      */
     flush() {
         return this.syncToRemote();
@@ -1824,7 +1846,7 @@ export class HybridStorage {
             await this.loaded;
             if (this.loadError)
                 throw this.loadError;
-            if (this.mode === "write-through" || this.mode === "write-back")
+            if (pullsRemote(this.mode))
                 await this.pullThrough("pull", NO_HINTS);
         }));
     }
@@ -1834,7 +1856,7 @@ export class HybridStorage {
             await this.loaded;
             if (this.loadError)
                 throw this.loadError;
-            if (this.mode !== "local-only")
+            if (pushesRemote(this.mode))
                 await this.pushQueue();
         }));
     }
@@ -1849,7 +1871,7 @@ export class HybridStorage {
      * This method closes the storage.
      *
      * - It stops the timers, and waits for the operations, the mode switch and the syncs that run.
-     * - It sends the queue (not in `local-only` mode). The queue store keeps the operations that
+     * - It sends the queue (not in the modes `local-only` and `read-only`). The queue store keeps the operations that
      *   the remote did not take.
      * - It closes the remote and the local copy. A durable local copy keeps its items.
      * - After it, each operation rejects. A second `close()` does nothing: it gives the promise of
@@ -1877,7 +1899,7 @@ export class HybridStorage {
             // After the syncs that run: send the pending operations. The queue store keeps the ones that
             // the remote did not take, and the status gets the failure.
             await this.serialize(async () => {
-                if (this.loadError || this.offlineOps.length === 0 || this.mode === "local-only")
+                if (this.loadError || this.offlineOps.length === 0 || !pushesRemote(this.mode))
                     return;
                 await this.track("push", () => this.pushQueue()).catch(() => undefined);
             });
@@ -2018,7 +2040,7 @@ export class HybridStorage {
             // A failure goes to the status: the reads go on with the local copy
             if (this.offlineOps.length > 0)
                 await this.push().catch(() => undefined);
-            if (!this.closed && (this.mode === "write-through" || this.mode === "write-back")) {
+            if (!this.closed && pullsRemote(this.mode)) {
                 await this.pull().catch(() => undefined);
             }
         }