ignotum 0.0.13 → 0.0.15

package/src/client/managed-client.ts

@@ -0,0 +1,729 @@
+import { Effect, Deferred, Option, Schema } from "effect";
+import {
+  ManagedClientMessage,
+  ManagedServerMessage,
+  ManagedSelectionResponse,
+  ManagedUpgradeRequired,
+  managedSelectionPath,
+  managedSyncPath,
+} from "@ignotum/contracts/managed-sync";
+import {
+  sameExecutionSelection,
+  type ExecutionSelection,
+  type RecoveryIdentity,
+  type RecoverySessionId,
+} from "@ignotum/contracts/platform";
+import { InvocationId, SubscriptionId } from "@ignotum/contracts/runtime/sync";
+import type { RuntimeMutationOutcome } from "@ignotum/contracts/runtime/hosted";
+import { encodeTransportObject } from "@ignotum/contracts/runtime/sync";
+import type { Result, ErrorValue } from "@ignotum/contracts/runtime/result";
+import {
+  ClientInfrastructureError,
+  ConnectionUnavailable,
+  InvalidMutationArguments,
+  PlatformUpgrading,
+  ServerError,
+} from "./errors.js";
+import { ManagedUpgrade } from "./managed-upgrade.js";
+import { RecoveryJournal, type RecoveryJournalIssue } from "./recovery-journal.js";
+import { RecoveryJournalLimits } from "./recovery-journal.js";
+import { prepareMutationArguments, uploadPreparedFiles } from "./files.js";
+import { IdGenerator } from "@ignotum/shared/id";
+import type { BrowserSession } from "./id.js";
+import type { SyncClientService, syncClientInternals } from "./sync.js";
+
+interface PendingMutation {
+  readonly identity: RecoveryIdentity;
+  readonly sessionEpoch: string;
+  readonly done: Deferred.Deferred<Result<unknown, ErrorValue>, ClientInfrastructureError>;
+  readonly prepared: Deferred.Deferred<
+    Extract<ManagedServerMessage, { type: "Preparation" }>["uploads"],
+    ClientInfrastructureError
+  >;
+  readonly preparation?: Extract<ManagedClientMessage, { type: "Prepare" }>;
+}
+const issueMessage = (issue: RecoveryJournalIssue): string => {
+  switch (issue) {
+    case "denied":
+      return "Browser storage is unavailable. Some previous mutation outcomes may be unknown.";
+    case "full":
+      return "Browser recovery storage is full. Some mutation outcomes could not be saved.";
+    case "corrupt":
+      return "Saved mutation information could not be read. Its outcomes remain unknown.";
+    case "expired":
+      return "Some saved mutation information expired. Its outcomes remain unknown.";
+    case "session-changed":
+      return "The browser session changed. Previous mutation outcomes cannot be retrieved in this session.";
+  }
+};
+
+/** The managed connection is mounted by bootstrap, independently of query observers. */
+export class ManagedBrowserClient {
+  readonly upgrade: ManagedUpgrade;
+  private readonly queries;
+  private socket: WebSocket | undefined;
+  private acceptedSocket: WebSocket | undefined;
+  private session: BrowserSession["Service"] | undefined;
+  private ids: IdGenerator["Service"] | undefined;
+  private sessionEpoch: string | undefined;
+  private sessionViewRevision: number | undefined;
+  private unsubscribeSession: (() => void) | undefined;
+  private sessionDeadline = 0;
+  private clientSessionId: RecoverySessionId;
+  private journal: RecoveryJournal | undefined;
+  private readonly pending = new Map<InvocationId, PendingMutation>();
+  private readonly recovery = new Map<string, RecoveryIdentity>();
+  private readonly recoveryDeadlines = new Map<string, number>();
+  private readonly recoveryTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
+  private readonly recoveryTimers = new Set<ReturnType<typeof setTimeout>>();
+  private reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+  private handshakeTimer: ReturnType<typeof setTimeout> | undefined;
+  private sessionTimer: ReturnType<typeof setTimeout> | undefined;
+  private heartbeat: ReturnType<typeof setInterval> | undefined;
+  private reconnectDelay = 250;
+  private disposed = false;
+  private readonly readyWaiters = new Set<(ready: boolean) => void>();
+  private suspended = true;
+  private lastActivity = Date.now();
+  private validation: Promise<boolean> | undefined;
+  private connectionGeneration = 0;
+
+  constructor(
+    readonly selection: ExecutionSelection,
+    private readonly browser: Window,
+    private readonly helpers: Pick<typeof syncClientInternals, "makeQueryCache" | "resultFromWire">,
+    callbacks: { readonly stopAdmission: () => void; readonly reload: () => void },
+  ) {
+    this.upgrade = new ManagedUpgrade(selection, browser, {
+      stopAdmission: () => {
+        this.suspended = true;
+        for (const pending of this.pending.values()) {
+          if (pending.preparation !== undefined)
+            Deferred.doneUnsafe(
+              pending.prepared,
+              Effect.fail(
+                PlatformUpgrading.make({
+                  message:
+                    "The app is updating. This upload was interrupted before its mutation ran.",
+                }),
+              ),
+            );
+        }
+        callbacks.stopAdmission();
+      },
+      unresolved: () => this.pending.size,
+      persist: () => this.persistPending(),
+      reload: callbacks.reload,
+      freshSelection: this.freshSelection,
+    });
+    this.clientSessionId = this.upgrade.clientSessionId;
+    this.queries = helpers.makeQueryCache(
+      Effect.suspend(() =>
+        this.ids === undefined
+          ? Effect.die("The client identity service is not ready.")
+          : this.ids.generate(SubscriptionId),
+      ),
+      (message) =>
+        Effect.sync(() => {
+          if (this.canSend()) this.send(message);
+        }),
+    );
+  }
+  attachSession(session: BrowserSession["Service"], ids: IdGenerator["Service"]): void {
+    if (this.disposed) return;
+    this.unsubscribeSession?.();
+    this.session = session;
+    this.ids = ids;
+    this.unsubscribeSession = session.subscribe(() => {
+      const current = session.current();
+      if (
+        current === undefined ||
+        (this.sessionEpoch !== undefined &&
+          (current.sessionEpoch !== this.sessionEpoch ||
+            current.viewRevision !== this.sessionViewRevision))
+      ) {
+        this.queries.invalidatePrivate();
+        this.suspended = true;
+        this.acceptedSocket = undefined;
+        this.socket?.close();
+      }
+    });
+  }
+  whenReady(): Promise<boolean> {
+    if (this.upgrade.ready) return Promise.resolve(true);
+    if (this.upgrade.obsolete || this.disposed) return Promise.resolve(false);
+    return new Promise((resolve) => {
+      const finish = (ready: boolean) => {
+        unsubscribe();
+        this.readyWaiters.delete(finish);
+        resolve(ready);
+      };
+      const unsubscribe = this.upgrade.subscribe(() => {
+        if (this.upgrade.ready || this.upgrade.obsolete || this.disposed)
+          finish(this.upgrade.ready);
+      });
+      this.readyWaiters.add(finish);
+    });
+  }
+  retry = (): void => {
+    if (this.upgrade.obsolete) this.upgrade.retry();
+    else this.resume();
+  };
+  recoverLoad = async (): Promise<void> => {
+    await this.upgrade.check();
+  };
+  private freshSelection = async (): Promise<ExecutionSelection | undefined> => {
+    const response = await this.browser.fetch(managedSelectionPath, {
+      cache: "no-store",
+      credentials: "same-origin",
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) throw new Error("The current app selection is unavailable.");
+    const current = Schema.decodeUnknownOption(ManagedSelectionResponse)(await response.json());
+    // A newer protocol may change selection's encoding. It can require reload without granting
+    // old code admission or depending on that code decoding the new protocol.
+    return Option.getOrUndefined(current)?.selection;
+  };
+  start(): void {
+    if (this.disposed) return;
+    this.browser.addEventListener("pageshow", this.resume);
+    this.browser.addEventListener("pagehide", this.hide);
+    this.browser.addEventListener("online", this.resume);
+    this.browser.addEventListener("offline", this.offline);
+    this.browser.addEventListener("focus", this.resume);
+    this.browser.document.addEventListener("visibilitychange", this.visibility);
+    this.heartbeat = setInterval(() => {
+      const now = Date.now();
+      if (now - this.lastActivity > 15_000) this.resume();
+      this.lastActivity = now;
+    }, 5_000);
+    this.connect();
+  }
+  private canSend(): boolean {
+    return (
+      !this.disposed &&
+      !this.suspended &&
+      !this.upgrade.obsolete &&
+      this.acceptedSocket !== undefined &&
+      this.acceptedSocket === this.socket &&
+      this.socket.readyState === 1 &&
+      Date.now() < this.sessionDeadline
+    );
+  }
+  private send(message: ManagedClientMessage): void {
+    if (this.socket?.readyState !== 1) return;
+    this.socket.send(Schema.encodeSync(Schema.fromJsonString(ManagedClientMessage))(message));
+  }
+  private connect(): void {
+    if (this.disposed || this.upgrade.obsolete) return;
+    this.suspended = true;
+    this.upgrade.connecting();
+    this.acceptedSocket = undefined;
+    this.recovery.clear();
+    for (const timer of this.recoveryTimers) clearTimeout(timer);
+    this.recoveryTimers.clear();
+    this.recoveryTimeouts.clear();
+    if (this.reconnectTimer !== undefined) clearTimeout(this.reconnectTimer);
+    if (this.handshakeTimer !== undefined) clearTimeout(this.handshakeTimer);
+    this.socket?.close();
+    this.socket = undefined;
+    const generation = ++this.connectionGeneration;
+    if (this.session === undefined) return;
+    void Effect.runPromise(this.session.bootstrap).then(
+      () => {
+        if (this.disposed || this.upgrade.obsolete || generation !== this.connectionGeneration)
+          return;
+        this.openSocket();
+      },
+      () => {
+        if (this.disposed || this.upgrade.obsolete || generation !== this.connectionGeneration)
+          return;
+        this.upgrade.unavailable("The browser session could not be verified. Reconnecting…");
+        this.reconnectTimer = setTimeout(() => this.connect(), 1_000);
+      },
+    );
+  }
+  private openSocket(): void {
+    const url = new URL(managedSyncPath, this.browser.location.href);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    const socket = new WebSocket(url);
+    this.socket = socket;
+    socket.onopen = () => {
+      if (this.socket !== socket || this.disposed) return;
+      this.send({
+        type: "Connect",
+        protocolVersion: 1,
+        selection: this.selection,
+        clientSessionId: this.clientSessionId,
+      });
+    };
+    this.handshakeTimer = setTimeout(() => {
+      if (this.socket === socket && this.acceptedSocket !== socket) socket.close();
+    }, 10_000);
+    socket.onmessage = (event: MessageEvent<string>) => {
+      if (this.socket !== socket || this.disposed) return;
+      const stable = Schema.decodeUnknownOption(Schema.fromJsonString(ManagedUpgradeRequired))(
+        event.data,
+      );
+      if (Option.isSome(stable)) {
+        void this.upgrade.require(stable.value.selection);
+        return;
+      }
+      const decoded = Schema.decodeUnknownOption(Schema.fromJsonString(ManagedServerMessage))(
+        event.data,
+      );
+      if (Option.isNone(decoded)) {
+        void this.upgrade.require();
+        return;
+      }
+      this.message(socket, decoded.value);
+    };
+    socket.onerror = () => socket.close();
+    socket.onclose = (event) => {
+      if (this.socket !== socket || this.disposed) return;
+      if (event.code === 1012 || event.code === 1008) this.queries.invalidatePrivate();
+      this.acceptedSocket = undefined;
+      this.suspended = true;
+      if (this.handshakeTimer !== undefined) clearTimeout(this.handshakeTimer);
+      if (this.upgrade.obsolete) return;
+      this.upgrade.unavailable("The connection was lost. Checking for updates before resuming…");
+      this.reconnectTimer = setTimeout(() => this.connect(), this.reconnectDelay);
+      this.reconnectDelay = Math.min(this.reconnectDelay * 2, 5_000);
+    };
+  }
+  private message(socket: WebSocket, message: ManagedServerMessage): void {
+    if (message.type === "UpgradeRequired") {
+      void this.upgrade.require(message.selection);
+      return;
+    }
+    if (message.type === "Handshake") {
+      if (!sameExecutionSelection(this.selection, message.selection)) {
+        void this.upgrade.require(message.selection);
+        return;
+      }
+      if (this.upgrade.obsolete) return;
+      if (this.handshakeTimer !== undefined) clearTimeout(this.handshakeTimer);
+      const previousEpoch = this.sessionEpoch;
+      if (
+        previousEpoch !== undefined &&
+        (previousEpoch !== message.session.sessionEpoch ||
+          this.sessionViewRevision !== message.session.viewRevision)
+      )
+        this.queries.invalidatePrivate();
+      this.sessionEpoch = message.session.sessionEpoch;
+      this.sessionViewRevision = message.session.viewRevision;
+      this.sessionDeadline =
+        Date.now() + Math.max(0, message.session.validUntil - message.serverTime);
+      if (this.sessionTimer !== undefined) clearTimeout(this.sessionTimer);
+      this.sessionTimer = setTimeout(
+        () => {
+          this.session?.suspend();
+          this.queries.invalidatePrivate();
+          this.resume();
+        },
+        Math.min(2_147_483_647, Math.max(0, this.sessionDeadline - Date.now())),
+      );
+      this.session?.accept(message.session, message.serverTime);
+      this.journal = new RecoveryJournal({
+        appId: this.selection.appId,
+        sessionEpoch: message.session.sessionEpoch,
+        clientSessionId: this.clientSessionId,
+        storage: () => this.browser.sessionStorage,
+      });
+      const saved = this.journal.read();
+      for (const issue of saved.issues) this.upgrade.reportRecovery(issueMessage(issue));
+      if (saved.clientSessionId !== this.clientSessionId) {
+        this.clientSessionId = saved.clientSessionId;
+        this.connect();
+        return;
+      }
+      if (previousEpoch !== undefined && previousEpoch !== this.sessionEpoch) {
+        for (const [id, pending] of this.pending) {
+          Deferred.doneUnsafe(
+            pending.prepared,
+            Effect.fail(
+              ConnectionUnavailable.make({
+                message: "The session changed before file preparation completed.",
+              }),
+            ),
+          );
+          this.upgrade.reportRecovery(
+            `Mutation ${id} has an unknown outcome because the session changed.`,
+          );
+          Deferred.doneUnsafe(
+            pending.done,
+            Effect.fail(
+              ConnectionUnavailable.make({
+                message: "The session changed. This mutation may already have completed.",
+              }),
+            ),
+          );
+        }
+        this.pending.clear();
+      }
+      this.acceptedSocket = socket;
+      this.suspended = false;
+      this.reconnectDelay = 250;
+      this.upgrade.accepted();
+      for (const entry of this.queries.entries())
+        this.send({
+          type: "Subscribe",
+          id: entry.subscriptionId,
+          function: entry.function,
+          args: entry.args,
+        });
+      for (const entry of saved.entries) {
+        if (entry.state === "pending") {
+          if (!this.pending.has(entry.identity.invocationId)) this.recover(entry.identity);
+        } else {
+          this.upgrade.reportRecovery(`Mutation ${entry.identity.invocationId}: ${entry.state}.`);
+          this.journal.remove(entry.identity);
+        }
+      }
+      for (const pending of this.pending.values()) {
+        if (pending.preparation !== undefined) this.send(pending.preparation);
+        else this.recover(pending.identity);
+      }
+      this.journal.write([]);
+      return;
+    }
+    if (this.acceptedSocket !== socket) {
+      socket.close();
+      return;
+    }
+    switch (message.type) {
+      case "Preparation": {
+        if (!this.canSend()) return;
+        const pending = this.pending.get(message.invocationId);
+        if (pending?.preparation !== undefined)
+          Deferred.doneUnsafe(pending.prepared, Effect.succeed(message.uploads));
+        return;
+      }
+      case "QuerySnapshot": {
+        if (!this.canSend()) return;
+        if (!sameExecutionSelection(this.selection, message.selection)) {
+          void this.upgrade.require(message.selection);
+          return;
+        }
+        const result = Effect.runSync(
+          this.helpers
+            .resultFromWire(message.result.result, message.files)
+            .pipe(Effect.catchTags({ InvalidServerMessage: (error) => Effect.succeed(error) })),
+        );
+        this.queries.setResult(message.id, result, message.result.observedRevision);
+        return;
+      }
+      case "MutationOutcome": {
+        if (
+          !sameExecutionSelection(message.identity.originalSelection, this.selection) &&
+          !this.recovery.has(message.id)
+        )
+          return;
+        this.outcome(message.id, message.identity, message.outcome);
+        return;
+      }
+      case "Error": {
+        if (message.code === "PlatformUpgrading") {
+          void this.upgrade.require();
+          return;
+        }
+        if (message.code === "SessionExpired") {
+          this.suspended = true;
+          this.session?.suspend();
+          this.queries.invalidatePrivate();
+          socket.close();
+          return;
+        }
+        if (
+          message.code === "InvalidArguments" ||
+          message.code === "InvocationIdConflict" ||
+          message.code === "ResourceLimitExceeded"
+        ) {
+          for (const [invocationId, pending] of this.pending) {
+            if (invocationId !== message.id) continue;
+            const failure = Effect.fail(
+              ServerError.make({ code: message.code, message: message.message }),
+            );
+            Deferred.doneUnsafe(pending.prepared, failure);
+            Deferred.doneUnsafe(pending.done, failure);
+            this.pending.delete(invocationId);
+            this.journal?.remove(pending.identity);
+            return;
+          }
+          for (const query of this.queries.entries()) {
+            if (query.subscriptionId !== message.id) continue;
+            this.queries.setResult(
+              query.subscriptionId,
+              ServerError.make({ code: message.code, message: message.message }),
+            );
+            return;
+          }
+          return;
+        }
+        this.upgrade.unavailable(message.message);
+        socket.close();
+        return;
+      }
+    }
+  }
+  private recover(identity: RecoveryIdentity): void {
+    if (!this.canSend()) return;
+    const id = `recovery:${identity.originalSelection.dataHistoryId}:${identity.invocationId}`;
+    if (this.recovery.has(id)) return;
+    this.recovery.set(id, identity);
+    const deadline = this.recoveryDeadlines.get(id) ?? Date.now() + 30_000;
+    this.recoveryDeadlines.set(id, deadline);
+    if (Date.now() >= deadline) {
+      this.outcome(id, identity, { type: "Uncertain" });
+      return;
+    }
+    this.send({ type: "RecoverMutation", id, identity });
+    const timer = setTimeout(() => {
+      this.recoveryTimers.delete(timer);
+      this.recoveryTimeouts.delete(id);
+      if (!this.recovery.has(id)) return;
+      this.recovery.delete(id);
+      this.recover(identity);
+    }, 5_000);
+    this.recoveryTimers.add(timer);
+    this.recoveryTimeouts.set(id, timer);
+  }
+  private outcome(id: string, identity: RecoveryIdentity, outcome: RuntimeMutationOutcome): void {
+    const recovery = this.recovery.get(id);
+    const pending = this.pending.get(identity.invocationId);
+    if (recovery === undefined && pending === undefined) return;
+    const expected = recovery ?? pending!.identity;
+    if (
+      expected.invocationId !== identity.invocationId ||
+      !sameExecutionSelection(expected.originalSelection, identity.originalSelection)
+    )
+      return;
+    this.recovery.delete(id);
+    const timeout = this.recoveryTimeouts.get(id);
+    if (timeout !== undefined) {
+      clearTimeout(timeout);
+      this.recoveryTimers.delete(timeout);
+      this.recoveryTimeouts.delete(id);
+    }
+    if (outcome.type === "Pending") {
+      const timer = setTimeout(() => {
+        this.recoveryTimers.delete(timer);
+        this.recover(identity);
+      }, 1_000);
+      this.recoveryTimers.add(timer);
+      return;
+    }
+    const recoveryId = `recovery:${identity.originalSelection.dataHistoryId}:${identity.invocationId}`;
+    this.recovery.delete(recoveryId);
+    this.recoveryDeadlines.delete(recoveryId);
+    if (pending !== undefined) {
+      this.pending.delete(identity.invocationId);
+      if (outcome.type === "Settled")
+        Deferred.doneUnsafe(pending.done, this.helpers.resultFromWire(outcome.result.result));
+      else
+        Deferred.doneUnsafe(
+          pending.done,
+          Effect.fail(
+            ConnectionUnavailable.make({
+              message:
+                outcome.type === "Interrupted"
+                  ? "The mutation was interrupted before it committed."
+                  : "The mutation outcome is unknown. Check the app before trying it again.",
+            }),
+          ),
+        );
+    }
+    const state =
+      outcome.type === "Settled"
+        ? "settled"
+        : outcome.type === "Interrupted"
+          ? "interrupted"
+          : "uncertain";
+    if (recovery !== undefined || outcome.type !== "Settled") {
+      const detail =
+        outcome.type === "Settled"
+          ? outcome.result.result.type === "Success"
+            ? "completed"
+            : "completed with an error"
+          : state;
+      this.upgrade.reportRecovery(`Mutation ${identity.invocationId}: ${detail}.`);
+    }
+    for (const issue of this.journal?.reconcile(identity, state).issues ?? [])
+      this.upgrade.reportRecovery(issueMessage(issue));
+    for (const issue of this.journal?.remove(identity).issues ?? [])
+      this.upgrade.reportRecovery(issueMessage(issue));
+  }
+  private persistPending(): readonly string[] {
+    if (this.pending.size === 0) return [];
+    if (this.journal === undefined)
+      return ["Pending mutation outcomes could not be saved and remain unknown."];
+    return this.journal
+      .write([...this.pending.values()].map((entry) => entry.identity))
+      .issues.map(issueMessage);
+  }
+  readonly observe: SyncClientService["observe"] = Effect.fn("ManagedBrowserClient.observe")(
+    (address, args) => this.queries.observe(address, args),
+  );
+  readonly mutate: SyncClientService["mutate"] = Effect.fn("ManagedBrowserClient.mutate")(
+    function* (this: ManagedBrowserClient, address, args) {
+      if (this.upgrade.obsolete)
+        return yield* PlatformUpgrading.make({
+          message: "The platform is updating. Try again after the app reloads.",
+        });
+      const valid = yield* Effect.promise(() => this.validate());
+      if (this.upgrade.obsolete)
+        return yield* PlatformUpgrading.make({
+          message: "The platform is updating. Try again after the app reloads.",
+        });
+      if (!valid || !this.canSend() || this.sessionEpoch === undefined)
+        return yield* ConnectionUnavailable.make({
+          message: "The app must reconnect and verify its selection before accepting a mutation.",
+        });
+      if (this.pending.size >= RecoveryJournalLimits.maxEntries)
+        return yield* ConnectionUnavailable.make({
+          message:
+            "Too many mutations are waiting for outcomes. Wait for them to settle before trying again.",
+        });
+      const ids = this.ids;
+      if (ids === undefined)
+        return yield* ConnectionUnavailable.make({ message: "The client is not ready." });
+      const prepared = yield* prepareMutationArguments(args).pipe(
+        Effect.provideService(IdGenerator, ids),
+        Effect.mapError((cause) =>
+          InvalidMutationArguments.make({
+            cause,
+            function: address,
+            message: "The mutation arguments cannot be sent.",
+          }),
+        ),
+      );
+      const encoded = yield* Effect.try({
+        try: () => encodeTransportObject(prepared.value),
+        catch: (cause) =>
+          InvalidMutationArguments.make({
+            cause,
+            function: address,
+            message: "The mutation arguments cannot be sent.",
+          }),
+      });
+      if (!this.canSend())
+        return yield* PlatformUpgrading.make({
+          message: "The app is reconnecting or updating. Try again when it is ready.",
+        });
+      const invocationId = yield* ids.generate(InvocationId);
+      const done = yield* Deferred.make<Result<unknown, ErrorValue>, ClientInfrastructureError>();
+      const identity: RecoveryIdentity = { invocationId, originalSelection: this.selection };
+      const uploadsReady = yield* Deferred.make<
+        Extract<ManagedServerMessage, { type: "Preparation" }>["uploads"],
+        ClientInfrastructureError
+      >();
+      const preparation =
+        prepared.fileIds.length === 0
+          ? undefined
+          : {
+              type: "Prepare" as const,
+              invocationId,
+              function: address,
+              args: encoded,
+              files: prepared.fileIds,
+            };
+      this.pending.set(invocationId, {
+        identity,
+        sessionEpoch: this.sessionEpoch,
+        done,
+        prepared: uploadsReady,
+        preparation,
+      });
+      for (const issue of this.persistPending()) this.upgrade.reportRecovery(issue);
+      if (preparation !== undefined) {
+        this.send(preparation);
+        yield* Effect.gen({ self: this }, function* () {
+          const uploads = yield* Deferred.await(uploadsReady);
+          yield* uploadPreparedFiles(prepared.nativeFiles, uploads, address);
+          if (!this.canSend())
+            return yield* PlatformUpgrading.make({
+              message: "The app is reconnecting or updating. Try again when it is ready.",
+            });
+        }).pipe(
+          Effect.tapError(() =>
+            Effect.sync(() => {
+              this.pending.delete(invocationId);
+              this.journal?.remove(identity);
+            }),
+          ),
+        );
+        const pending = this.pending.get(invocationId);
+        if (pending === undefined) return yield* Deferred.await(done);
+        this.pending.set(invocationId, { ...pending, preparation: undefined });
+      }
+      this.send({ type: "Invoke", invocationId, function: address, args: encoded });
+      const timer = setTimeout(() => {
+        this.recoveryTimers.delete(timer);
+        if (this.pending.has(invocationId)) this.recover(identity);
+      }, 5_000);
+      this.recoveryTimers.add(timer);
+      return yield* Deferred.await(done);
+    },
+  ).bind(this);
+  validate = (): Promise<boolean> => {
+    if (this.upgrade.obsolete || this.disposed) return Promise.resolve(false);
+    if (this.validation !== undefined) return this.validation;
+    this.validation = this.upgrade
+      .check()
+      .then((current) => {
+        const ready = current && this.canSend();
+        if (ready && this.upgrade.getSnapshot().phase !== "ready") this.upgrade.accepted();
+        return ready;
+      })
+      .finally(() => {
+        this.validation = undefined;
+      });
+    return this.validation;
+  };
+  private resume = (): void => {
+    if (this.disposed || this.upgrade.obsolete) return;
+    this.suspended = true;
+    this.acceptedSocket = undefined;
+    this.recovery.clear();
+    this.queries.invalidate(undefined);
+    this.connect();
+  };
+  private offline = (): void => {
+    this.suspended = true;
+    this.acceptedSocket = undefined;
+    this.upgrade.unavailable(
+      "The app is offline. Reconnect to check for updates and mutation outcomes.",
+    );
+    this.socket?.close();
+  };
+  private hide = (): void => {
+    for (const issue of this.persistPending()) this.upgrade.reportRecovery(issue);
+    this.suspended = true;
+    this.acceptedSocket = undefined;
+    this.socket?.close();
+  };
+  private visibility = (): void => {
+    if (this.browser.document.visibilityState === "visible") this.resume();
+    else this.hide();
+  };
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    for (const finish of this.readyWaiters) finish(false);
+    this.unsubscribeSession?.();
+    this.persistPending();
+    this.socket?.close();
+    if (this.reconnectTimer !== undefined) clearTimeout(this.reconnectTimer);
+    if (this.handshakeTimer !== undefined) clearTimeout(this.handshakeTimer);
+    if (this.sessionTimer !== undefined) clearTimeout(this.sessionTimer);
+    if (this.heartbeat !== undefined) clearInterval(this.heartbeat);
+    for (const timer of this.recoveryTimers) clearTimeout(timer);
+    this.browser.removeEventListener("pageshow", this.resume);
+    this.browser.removeEventListener("pagehide", this.hide);
+    this.browser.removeEventListener("online", this.resume);
+    this.browser.removeEventListener("offline", this.offline);
+    this.browser.removeEventListener("focus", this.resume);
+    this.browser.document.removeEventListener("visibilitychange", this.visibility);
+    this.upgrade.dispose();
+  }
+}