eraspace 0.1.0 → 0.2.0

package/sdk/src/client/connection.ts

@@ -1,11 +1,13 @@
-import { Socket, type Channel } from "phoenix";
+import { Socket, type Channel } from "./transport.ts";
 import { signal, effect, batch, type Signal } from "@preact/signals";
 import { applyPatch } from "./result-diff.ts";
-import { EraspaceError } from "./errors.ts";
+import { EraspaceError, OutcomeUnknownError } from "./errors.ts";
 import { readConfig, type ClientOptions } from "./config.ts";
+import { requestKey } from "./request-key.ts";
 import { subKey } from "./sub-key.ts";
 import { Subscription, type FullResult, type DataMessage } from "./subscription.ts";
 import { RoomConn } from "./room.ts";
+import { retryDelay } from "./retry.ts";
 import type { Status } from "./types.ts";
 
 type Fn = (...args: any[]) => any;
@@ -21,6 +23,11 @@ export class ClientImpl {
   private socket: Socket | undefined;
   private channel: Channel | undefined;
   private joinedOnce = false;
+  /** Counts app channel joins. Server subscription ids live only as long as the join that created them. */
+  private joins = 0;
+  /** Server time minus local time, from the latest join reply. */
+  private clockOffset = 0;
+  private gone: EraspaceError | undefined;
   private nextSub = 1;
   private nextMutation = 1;
   private subs = new Map<string, Subscription>();
@@ -42,16 +49,13 @@ export class ClientImpl {
 
   private ensureSocket(): Socket {
     if (this.socket) return this.socket;
-    const socketOpts: Record<string, unknown> = {
-      params: () => ({ app: this.app }),
-      timeout: this.opts.timeout ?? 15000,
+    const socket = new Socket(this.socketUrl, {
+      timeout: this.opts.timeout,
       ...this.opts.socketOptions,
-    };
-    if (this.opts.transport) socketOpts.transport = this.opts.transport;
-    const socket = new Socket(this.socketUrl, socketOpts as any);
+      transport: this.opts.transport,
+    });
     socket.onOpen(() => { this.status.value = "open"; });
     socket.onClose(() => { this.status.value = "closed"; });
-    socket.onError(() => { this.status.value = "closed"; });
     socket.connect();
     this.socket = socket;
     return socket;
@@ -60,41 +64,103 @@ export class ClientImpl {
   private ensureChannel(): Channel {
     if (this.channel) return this.channel;
     const socket = this.ensureSocket();
-    const channel = socket.channel(`app:${this.app}`, { patches: true, watermarks: true });
+    const channel = socket.channel(`app:${this.app}`, {});
     channel.on("data", (m: DataMessage) => this.onData(m));
     channel.on("error", (m: { id?: string; name?: string; message?: string }) => {
       const sub = m.id !== undefined ? this.subsById.get(String(m.id)) : undefined;
-      if (sub) sub.error.value = EraspaceError.from(m);
+      if (sub) {
+        sub.error.value = EraspaceError.from(m);
+        this.retrySub(sub);
+      }
     });
+    channel.on("gone", () => this.onGone());
+    // Transport loss changes status; reconnect rejoins and resubscribes while cached values stay valid.
+    // A join the server rejects is reported to every subscription.
+    const failed = (payload: unknown, rejected: boolean) => {
+      if (this.gone) return;
+      if (payload instanceof EraspaceError && payload.name === "AppGone") { this.onGone(); return; }
+      this.status.value = "closed";
+      if (rejected) for (const sub of this.subs.values()) sub.error.value = EraspaceError.from(payload, "App channel join failed");
+    };
+    channel.onError((reason, rejected) => failed(reason, rejected));
+    channel.onClose(() => failed(undefined, false));
     channel.on("deployed", (m: { version?: number }) => this.onDeployed(m?.version));
-    channel.join().receive("ok", (resp: { self?: string } | undefined) => {
+    channel.onJoin((resp) => {
+      this.joins++;
+      if (this.gone) return;
+      this.status.value = "open";
       if (resp && typeof resp.self === "string") this.self.value = resp.self;
+      if (resp && typeof resp.now === "number") this.clockOffset = resp.now - Date.now();
       // The channel process is new after a reconnect, so every live subscription is sent again.
       if (this.joinedOnce) this.resubscribeAll();
       this.joinedOnce = true;
     });
+    channel.join();
     this.channel = channel;
     return channel;
   }
 
-  private push<T>(event: string, payload: object): Promise<T> {
+  private push<T>(event: string, payload: object | (() => object | null)): Promise<T> {
+    if (this.gone) return Promise.reject(this.gone);
     const channel = this.ensureChannel();
-    return new Promise<T>((resolve, reject) => {
-      channel
-        .push(event, payload, this.opts.timeout ?? 15000)
-        .receive("ok", (resp: T) => resolve(resp))
-        .receive("error", (resp: unknown) => reject(EraspaceError.from(resp)))
-        .receive("timeout", () => reject(new EraspaceError("TimeoutError", `${event} timed out`)));
-    });
+    return channel.push<T>(event, payload, this.opts.timeout ?? 15000);
+  }
+
+  async call(fn: string, args: unknown[], kind: "query" | "action" = "query"): Promise<unknown> {
+    const key = this.requestKey();
+    try {
+      const resp = await this.push<{ value?: unknown }>("call", { fn, args, kind, key });
+      return resp?.value;
+    } catch (error) {
+      if (kind === "action" && error instanceof EraspaceError && ["TimeoutError", "OutcomeUnknownError"].includes(error.name)) {
+        throw new OutcomeUnknownError(key, "The action may have performed effects; it cannot be replayed safely");
+      }
+      throw error;
+    }
+  }
+
+  /** Request keys carry server time, so a skewed client clock cannot place them outside the retry window. */
+  private requestKey(): string {
+    return requestKey(Date.now() + this.clockOffset);
+  }
+
+  private async mutationRequest(fn: string, args: unknown[], key = this.requestKey(), retry = false): Promise<{ value: unknown; commitSeq?: number }> {
+    let rekeyed = false;
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return await this.push("call", { fn, args, kind: "mutation", key, retry });
+      } catch (error) {
+        // The server refused the key before running anything. The join reply has corrected the clock by now.
+        if (error instanceof EraspaceError && error.name === "RequestKeyError" && !retry && !rekeyed) {
+          rekeyed = true;
+          attempt--;
+          key = this.requestKey();
+          continue;
+        }
+        const uncertain = error instanceof EraspaceError && ["TimeoutError", "OutcomeUnknownError", "RetryExpiredError"].includes(error.name);
+        // A rejected recovery attempt cannot resolve the original request's unknown outcome.
+        if (!uncertain && !retry) throw error;
+        if (uncertain && attempt === 0 && error.name !== "RetryExpiredError") {
+          retry = true;
+          continue;
+        }
+        const message = error instanceof Error ? error.message : "Recovery failed";
+        throw new OutcomeUnknownError(key, `${message}. Recover this mutation only with the same request key.`);
+      }
+    }
   }
 
-  async call(fn: string, args: unknown[]): Promise<any> {
-    const resp = await this.push<{ value?: unknown }>("call", { fn, args });
-    return resp?.value;
+  async retryMutation(fn: string, args: unknown[], key: string): Promise<unknown> {
+    return (await this.mutationRequest(fn, args, key, true)).value;
   }
 
   close(): void {
-    for (const r of this.rooms.values()) r.channel.leave();
+    for (const sub of this.subs.values()) {
+      clearTimeout(sub.timer);
+      clearTimeout(sub.retryTimer);
+      sub.request++;
+    }
+    for (const r of this.rooms.values()) r.close();
     this.rooms.clear();
     this.channel?.leave();
     this.socket?.disconnect();
@@ -102,12 +168,38 @@ export class ClientImpl {
     this.socket = undefined;
     this.subs.clear();
     this.subsById.clear();
+    this.joinedOnce = false;
+    this.status.value = "closed";
+  }
+
+  private onGone(): void {
+    this.gone = new EraspaceError("AppGone", "This app is no longer serving");
+    for (const sub of this.subs.values()) {
+      clearTimeout(sub.retryTimer);
+      sub.retryTimer = undefined;
+      sub.request++;
+      sub.error.value = this.gone;
+    }
+    for (const r of this.rooms.values()) r.close();
+    this.channel?.leave();
+    this.socket?.disconnect();
     this.status.value = "closed";
   }
 
+  private retrySub(sub: Subscription): void {
+    if (this.gone || sub.retryTimer || this.subs.get(sub.key) !== sub) return;
+    sub.retryTimer = setTimeout(() => {
+      sub.retryTimer = undefined;
+      if (this.subs.get(sub.key) === sub) this.sendSub(sub);
+    }, retryDelay(++sub.retries));
+  }
+
   // -- subscriptions --------------------------------------------------------------------------------------------
 
   private sendSub(sub: Subscription): void {
+    if (this.gone) { sub.error.value = this.gone; return; }
+    clearTimeout(sub.retryTimer);
+    sub.retryTimer = undefined;
     const oldId = sub.id;
     const request = ++sub.request;
     if (request > 1) {
@@ -115,25 +207,42 @@ export class ClientImpl {
       sub.id = String(this.nextSub++);
       this.subsById.set(sub.id, sub);
       sub.revision = undefined;
-      this.push("unsub", { id: oldId }).catch(() => {});
+      this.unsubscribe(sub, oldId);
     }
-    this.push<FullResult>("sub", { id: sub.id, fn: sub.fn, args: sub.args,
-      minCommitSeq: Math.max(0, ...sub.layers.map(layer => layer.commitSeq ?? 0)),
+    const id = sub.id;
+    this.push<FullResult>("sub", () => {
+      // A newer request or a drop replaced this one before it was sent: withdraw it.
+      if (sub.request !== request) return null;
+      sub.sent = { id, join: this.joins };
+      return { id, fn: sub.fn, args: sub.args, minCommitSeq: Math.max(0, ...sub.layers.map(layer => layer.commitSeq ?? 0)) };
     }).then(
       (resp) => {
         if (this.subsById.get(sub.id) !== sub || sub.request !== request) return;
         this.setServer(sub, resp.value, resp.commitSeq, resp.revision);
       },
       (err: EraspaceError) => {
-        if (this.subsById.get(sub.id) === sub && sub.request === request) sub.error.value = err;
+        if (this.subsById.get(sub.id) === sub && sub.request === request) {
+          sub.error.value = err;
+          this.retrySub(sub);
+        }
       },
     );
   }
 
+  /** Tells the server to drop `id`, unless the server cannot have it: never sent, or sent before a reconnect. */
+  private unsubscribe(sub: Subscription, id: string): void {
+    if (sub.sent?.id !== id || sub.sent.join !== this.joins) return;
+    sub.sent = undefined;
+    this.push("unsub", { id }).catch(() => {});
+  }
+
   // Messages for one subscription id arrive in order, so only commit watermarks are compared. Revisions
   // belong to a server cache entry and may restart lower when an identity-dependent query splits.
   private setServer(sub: Subscription, value: unknown, commitSeq: number, revision: number): void {
     if (commitSeq < sub.commitSeq) return;
+    clearTimeout(sub.retryTimer);
+    sub.retryTimer = undefined;
+    sub.retries = 0;
     batch(() => {
       sub.server = value;
       sub.hasServer = true;
@@ -146,6 +255,7 @@ export class ClientImpl {
   }
 
   private onData(message: DataMessage): void {
+    if (this.gone) return;
     const sub = this.subsById.get(String(message.id));
     if (!sub || message.commitSeq < sub.commitSeq) return;
     if ("patch" in message) {
@@ -167,9 +277,9 @@ export class ClientImpl {
     for (const sub of this.subs.values()) this.sendSub(sub);
   }
 
+  // Subscriptions survive a deploy: the server re-runs them with the new code and pushes changed values.
   private onDeployed(version: number | undefined): void {
     if (typeof version === "number") this.version.value = version;
-    this.resubscribeAll();
     for (const cb of [...this.deployedCbs]) cb(this.version.value);
     if (this.opts.reloadOnDeploy && typeof location !== "undefined") location.reload();
   }
@@ -221,9 +331,12 @@ export class ClientImpl {
     sub.timer = setTimeout(() => {
       sub.timer = undefined;
       if (sub.refs > 0 || this.subs.get(sub.key) !== sub) return;
+      clearTimeout(sub.retryTimer);
+      sub.retryTimer = undefined;
+      sub.request++;
       this.subs.delete(sub.key);
       this.subsById.delete(sub.id);
-      this.push("unsub", { id: sub.id }).catch(() => {});
+      this.unsubscribe(sub, sub.id);
     }, ms);
   }
 
@@ -245,7 +358,7 @@ export class ClientImpl {
   // -- mutations ------------------------------------------------------------------------------------------------
 
   async mutate(fn: string, args: unknown[], optimistic?: Fn): Promise<any> {
-    if (!optimistic) return this.call(fn, args);
+    if (!optimistic) return (await this.mutationRequest(fn, args)).value;
     const mid = this.nextMutation++;
     const touched = new Set<Subscription>();
     const store = {
@@ -256,7 +369,7 @@ export class ClientImpl {
     };
     try {
       batch(() => optimistic(store, ...args));
-      const { value, commitSeq } = await this.push<{ value: unknown; commitSeq?: number }>("call", { fn, args });
+      const { value, commitSeq } = await this.mutationRequest(fn, args);
       const timeout = this.opts.optimisticTimeoutMs ?? 2000;
       for (const sub of touched) {
         // Only mutations report a commit. Without one, no watermark can cover the layer.
@@ -296,6 +409,10 @@ export class ClientImpl {
 
   // -- rooms ----------------------------------------------------------------------------------------------------
 
+  /**
+   * Get or create the room for `room`. Like a subscription, it is only held once retained: a render that never
+   * commits leaves an unretained room, which is dropped after a grace period.
+   */
   acquireRoom(room: string): RoomConn {
     const topic = `room:${this.app}:${room}`;
     let r = this.rooms.get(topic);
@@ -303,20 +420,31 @@ export class ClientImpl {
       r = new RoomConn(this.ensureSocket(), topic, this.self);
       this.rooms.set(topic, r);
     }
-    if (r.timer) clearTimeout(r.timer);
+    if (r.refs === 0) this.scheduleRoomDrop(r, 1000);
+    return r;
+  }
+
+  /** False when the room was dropped after it was acquired; acquire it again. */
+  retainRoom(r: RoomConn): boolean {
+    if (this.rooms.get(r.topic) !== r) return false;
+    clearTimeout(r.timer);
     r.timer = undefined;
     r.refs++;
-    return r;
+    return true;
   }
 
   releaseRoom(r: RoomConn): void {
     r.refs = Math.max(0, r.refs - 1);
-    if (r.refs > 0) return;
-    if (r.timer) clearTimeout(r.timer);
+    if (r.refs === 0) this.scheduleRoomDrop(r, this.opts.unsubscribeDelayMs ?? 50);
+  }
+
+  private scheduleRoomDrop(r: RoomConn, ms: number): void {
+    clearTimeout(r.timer);
     r.timer = setTimeout(() => {
+      r.timer = undefined;
       if (r.refs > 0 || this.rooms.get(r.topic) !== r) return;
       this.rooms.delete(r.topic);
-      r.channel.leave();
-    }, this.opts.unsubscribeDelayMs ?? 50);
+      r.close();
+    }, ms);
   }
 }

package/sdk/src/client/errors.ts

@@ -1,6 +1,6 @@
 /**
  * An error raised by a server handler (or the transport). `name` is the server error name, for example `Error`,
- * `TypeError`, or `TimeoutError` for a call that got no reply in time.
+ * `TypeError`, or `OutcomeUnknownError` when a mutation or action could have applied.
  */
 export class EraspaceError extends Error {
   readonly data?: unknown;
@@ -26,3 +26,12 @@ export class EraspaceError extends Error {
 export function isEraspaceError(e: unknown): e is EraspaceError {
   return e instanceof EraspaceError;
 }
+
+/** The mutation may have committed. Recover with `client.retryMutation(name, args, error.requestKey)`. */
+export class OutcomeUnknownError extends EraspaceError {
+  readonly requestKey: string;
+  constructor(requestKey: string, message = "The request's outcome is unknown") {
+    super("OutcomeUnknownError", message);
+    this.requestKey = requestKey;
+  }
+}