@rxferrix/client 0.12.0 → 0.13.0

package/src/client.ts

@@ -7,6 +7,7 @@ import type {
 } from "./api.js";
 import { normalizeArgs, queryToken, type QueryToken } from "./canonical.js";
 import { CLIENT_CLOSED, RxFerrixError } from "./errors.js";
+import { MAX_QUERY_ARGS_BYTES, tooLarge, tooMuchWatched } from "./limits.js";
 import { LocalQuerySet } from "./local_query_set.js";
 import { createLogger, type Logger } from "./logging.js";
 import {
@@ -166,15 +167,19 @@ const MAX_TIMEOUT_MS = 2_147_483_647;
 /** The server's limit of live queries per socket; past it, a `ModifyQuerySet` is a fatal error (docs/PROTOCOL.md). */
 export const MAX_LIVE_QUERIES = 1024;
 
-/** The error for function args that can't be encoded as JSON (a cycle, a BigInt, ...), or null. */
-function unserializable(args: Record<string, unknown>): RxFerrixError | null {
+/**
+ * The error for function args that can't be sent: not encodable as JSON (a cycle, a BigInt, ...), or too large for
+ * one message. Null if they can.
+ */
+function unsendable(udfPath: string, args: Record<string, unknown>): RxFerrixError | null {
+  let json: string;
   try {
-    JSON.stringify(args);
-    return null;
+    json = JSON.stringify(args);
   } catch (e) {
     const detail = e instanceof Error ? e.message : String(e);
     return new RxFerrixError(`Arguments can't be serialized as JSON: ${detail}`, { code: "invalid_args", cause: e });
   }
+  return tooLarge(udfPath, json);
 }
 
 interface AuthState {
@@ -218,6 +223,8 @@ export class RxFerrixClient {
    * still shows results from the old socket, so it is not "at" the new socket's ts; mutation completion waits.
    */
   private resyncQuerySetVersion: number | null = null;
+  /** A new socket opened and its first query-set flush hasn't gone out yet ({@link flushQuerySet}). */
+  private awaitingFirstFlush = false;
 
   // Auth
   private auth: AuthState | null = null;
@@ -360,6 +367,14 @@ export class RxFerrixClient {
         { code: "too_many_queries" },
       );
     }
+    const cost = this.localQueries.costOf(token);
+    if (cost > 0) {
+      // The same goes for a query whose arguments no message can carry (the token holds their canonical JSON), and
+      // for the one that takes the set past what the server lets a socket watch.
+      const large = tooLarge(udfPath, token);
+      if (large) throw large;
+      if (this.localQueries.argsBytes + cost > MAX_QUERY_ARGS_BYTES) throw tooMuchWatched(udfPath);
+    }
     let set = this.listeners.get(token);
     if (!set) {
       set = new Set();
@@ -393,12 +408,26 @@ export class RxFerrixClient {
   }
 
   private flushQuerySet(): void {
-    const { message, removed } = this.localQueries.flush(this.ws.canSend());
+    const canSend = this.ws.canSend();
+    const { messages, removed } = this.localQueries.flush(canSend);
     if (removed.length > 0) {
       for (const queryId of removed) this.remoteQueries.remove(queryId);
       this.recomputeAndNotify();
     }
-    if (message) this.ws.send(message);
+    for (const message of messages) this.ws.send(message);
+    if (canSend && this.awaitingFirstFlush) {
+      // The first flush a new socket lets through re-adds every query. Until their results arrive from this socket
+      // the view still shows the previous socket's: a mutation that completed there must not settle against them.
+      // (Decided here, not when the socket opens: its sends may be held back then, for a fresh token.)
+      this.awaitingFirstFlush = false;
+      const resent = this.localQueries.sentQuerySetVersion;
+      this.resyncQuerySetVersion = resent > 0 ? resent : null;
+      if (resent === 0) {
+        // Nothing is watched, so there is no view a mutation could be ahead of, and nothing on this socket will
+        // bring a Transition for the ones that completed on the last: they are done.
+        this.finishMutations(this.requests.removeCompleted(Number.MAX_SAFE_INTEGER));
+      }
+    }
   }
 
   // ---------------------------------------------------------------------------------------------------------------
@@ -415,9 +444,9 @@ export class RxFerrixClient {
     if (this.closed) return Promise.reject(new RxFerrixError("Client is closed", { code: CLIENT_CLOSED }));
     const args = normalizeArgs(argsAndOptions[0]);
     const options = argsAndOptions[1] as MutationOptions<ArgsOf<M>> | undefined;
-    // Checked before it is queued: a message that can't be encoded would otherwise be retried on every socket and
-    // block every later request behind it.
-    const invalid = unserializable(args);
+    // Checked before it is queued: a message that can't be encoded, or that the server refuses for its size, would
+    // otherwise be retried on every socket and block every later request behind it.
+    const invalid = unsendable(ref._path, args);
     if (invalid) return Promise.reject(invalid);
     const requestId = this.requests.allocateRequestId();
     const message: MutationMessage = { type: "Mutation", requestId, udfPath: ref._path, args };
@@ -437,7 +466,7 @@ export class RxFerrixClient {
   action<A extends FunctionReference<"action">>(ref: A, ...args: OptionalArgs<A>): Promise<OutputOf<A>> {
     if (this.closed) return Promise.reject(new RxFerrixError("Client is closed", { code: CLIENT_CLOSED }));
     const normalized = normalizeArgs(args[0]);
-    const invalid = unserializable(normalized);
+    const invalid = unsendable(ref._path, normalized);
     if (invalid) return Promise.reject(invalid);
     const requestId = this.requests.allocateRequestId();
     const message: ActionMessage = { type: "Action", requestId, udfPath: ref._path, args: normalized };
@@ -619,10 +648,11 @@ export class RxFerrixClient {
     this.identityVersion = 0;
     this.serverToken = null;
     this.awaitingAuthConfirmation = null;
+    // The view still shows the previous socket's results until the re-added queries report from this socket
+    // (`flushQuerySet` says from which query set version on).
+    this.awaitingFirstFlush = true;
+    this.resyncQuerySetVersion = null;
     this.syncToServer();
-    // The view still shows the previous socket's results until the re-added queries report from this socket.
-    const resent = this.localQueries.sentQuerySetVersion;
-    this.resyncQuerySetVersion = resent > 0 ? resent : null;
   }
 
   /** Sends everything the server does not know yet, in protocol order: Authenticate, ModifyQuerySet, requests. */
@@ -663,7 +693,7 @@ export class RxFerrixClient {
       }
       case "FatalError":
         this.logger.error(`server reported a fatal error: ${message.error}`);
-        this.ws.reconnect(`FatalError: ${message.error}`);
+        this.ws.reconnectAfterFatal(`FatalError: ${message.error}`);
         return;
       case "AuthError":
         this.onAuthError(message);
@@ -677,7 +707,7 @@ export class RxFerrixClient {
 
   /** The ts the local view is consistent with, or null while resyncing after a reconnect. */
   private observedTs(): number | null {
-    return this.resyncQuerySetVersion === null ? this.remoteQueries.version.ts : null;
+    return this.resyncQuerySetVersion === null && !this.awaitingFirstFlush ? this.remoteQueries.version.ts : null;
   }
 
   private onTransition(message: TransitionMessage): void {

package/src/limits.ts

@@ -0,0 +1,62 @@
+import { RxFerrixError } from "./errors.js";
+
+/**
+ * The server's limit on one message, in UTF-8 bytes (docs/PROTOCOL.md, Limits). A larger one is answered with a
+ * `FatalError` and the socket is closed, and since the client sends again what the server never answered, the same
+ * message would end every socket after it. So nothing that large is ever queued.
+ */
+export const MAX_MESSAGE_BYTES = 2 * 1024 * 1024;
+/**
+ * The server's limit on the arguments of all the queries one socket watches, as JSON (docs/PROTOCOL.md, Limits). The
+ * query that crosses it is answered with a `FatalError`, and every new socket would re-add the same set and get the
+ * same answer: the query is refused here instead.
+ */
+export const MAX_QUERY_ARGS_BYTES = 8 * 1024 * 1024;
+/** Room kept in a message for what goes around the arguments: its type, ids and the function's path. */
+const ENVELOPE_BYTES = 1024;
+/**
+ * How much of a `ModifyQuerySet` its queries' paths and arguments may take, in characters of their canonical JSON.
+ * A query set is re-sent whole on every new socket; this splits it into messages well under the limit (a character
+ * is at most three bytes, and escaping can add a little).
+ */
+export const MODIFY_QUERY_SET_CHARS = 400_000;
+
+/** The length of `s` as UTF-8. */
+export function utf8Length(s: string): number {
+  let bytes = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c < 0x80) bytes += 1;
+    else if (c < 0x800) bytes += 2;
+    else if (c >= 0xd800 && c <= 0xdbff && i + 1 < s.length) {
+      // A surrogate pair: four bytes for the two code units.
+      bytes += 4;
+      i++;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+
+/** About what a `Remove` takes in a `ModifyQuerySet`, in characters. */
+export const REMOVE_CHARS = 40;
+
+/** The error for one query too many, by the size of their arguments ({@link MAX_QUERY_ARGS_BYTES}). */
+export function tooMuchWatched(udfPath: string): RxFerrixError {
+  return new RxFerrixError(
+    `Can't watch "${udfPath}" as well: the queries watched at once may hold at most ` +
+      `${MAX_QUERY_ARGS_BYTES >> 20} MiB of arguments`,
+    { code: "args_too_large" },
+  );
+}
+
+/** The error for a call whose arguments (`json`: their JSON) don't fit in one message, or null. */
+export function tooLarge(udfPath: string, json: string): RxFerrixError | null {
+  const room = MAX_MESSAGE_BYTES - ENVELOPE_BYTES - udfPath.length;
+  // Each character is one to three bytes: only what is in between needs counting.
+  if (json.length * 3 <= room) return null;
+  if (json.length <= room && utf8Length(json) <= room) return null;
+  return new RxFerrixError(
+    `The arguments of "${udfPath}" are too large: a message to the server holds at most ${MAX_MESSAGE_BYTES >> 20} MiB`,
+    { code: "args_too_large" },
+  );
+}

package/src/local_query_set.ts

@@ -1,4 +1,5 @@
 import { queryToken, type QueryToken } from "./canonical.js";
+import { MODIFY_QUERY_SET_CHARS, REMOVE_CHARS, utf8Length } from "./limits.js";
 import type { ModifyQuerySetMessage, QueryId, QuerySetModification } from "./protocol.js";
 
 export interface LocalQuery {
@@ -9,11 +10,17 @@ export interface LocalQuery {
   refCount: number;
   /** Whether an `Add` for this query is part of the server's query set on the current socket. */
   onServer: boolean;
+  /** About what its arguments count for on the server ({@link LocalQuerySet.argsBytes}). */
+  readonly bytes: number;
 }
 
 export interface FlushResult {
-  /** The message to send, or null when nothing changed (or nothing can be sent right now). */
-  message: ModifyQuerySetMessage | null;
+  /**
+   * The messages to send, in order; none when nothing changed (or nothing can be sent right now). Usually one. A
+   * query set too large for one message (it is sent whole on every new socket) is split into several, each one
+   * version after the last.
+   */
+  messages: ModifyQuerySetMessage[];
   /** Queries dropped locally by this flush (their last watcher left). Their results should be discarded. */
   removed: QueryId[];
 }
@@ -34,12 +41,31 @@ export class LocalQuerySet {
   private readonly pendingRemoves = new Set<QueryId>();
   /** The `newVersion` of the last ModifyQuerySet sent on this socket. */
   private querySetVersion = 0;
+  /** The sum of {@link LocalQuery.bytes} over the queries that have watchers. */
+  private bytes = 0;
+
+  /**
+   * About what the server counts for the arguments of the watched queries (it caps their JSON at 8 MiB a socket).
+   * An upper bound: each query counts with its token, which holds its path as well. A query whose last watcher
+   * left no longer counts, though it is tracked until the next flush: that flush removes it before it adds anything.
+   */
+  get argsBytes(): number {
+    return this.bytes;
+  }
+
+  /** What watching the query `token` would add to {@link argsBytes}; nothing if it has watchers already. */
+  costOf(token: QueryToken): number {
+    const tracked = this.byToken.get(token);
+    if (!tracked) return utf8Length(token);
+    return tracked.refCount > 0 ? 0 : tracked.bytes;
+  }
 
   /** Adds a watcher; returns the query (created if needed) and whether a flush is needed. */
   addRef(udfPath: string, args: Record<string, unknown>): { query: LocalQuery; needsFlush: boolean } {
     const token = queryToken(udfPath, args);
     const existing = this.byToken.get(token);
     if (existing) {
+      if (existing.refCount === 0) this.bytes += existing.bytes;
       existing.refCount += 1;
       // refCount went 0 -> 1 before the flush: the query is revived without any server traffic.
       return { query: existing, needsFlush: false };
@@ -51,7 +77,9 @@ export class LocalQuerySet {
       args,
       refCount: 1,
       onServer: false,
+      bytes: utf8Length(token),
     };
+    this.bytes += query.bytes;
     this.byToken.set(token, query);
     this.byId.set(query.queryId, query);
     return { query, needsFlush: true };
@@ -61,6 +89,7 @@ export class LocalQuerySet {
   removeRef(token: QueryToken): boolean {
     const query = this.byToken.get(token);
     if (!query) return false;
+    if (query.refCount === 1) this.bytes -= query.bytes;
     query.refCount = Math.max(0, query.refCount - 1);
     return query.refCount === 0;
   }
@@ -83,8 +112,8 @@ export class LocalQuerySet {
   }
 
   /**
-   * Drops queries without watchers and, if `canSend`, builds the ModifyQuerySet that brings the server's query set
-   * in line with the local one (bumping the query set version).
+   * Drops queries without watchers and, if `canSend`, builds the ModifyQuerySets that bring the server's query set
+   * in line with the local one (bumping the query set version once per message).
    */
   flush(canSend: boolean): FlushResult {
     const removed: QueryId[] = [];
@@ -95,25 +124,46 @@ export class LocalQuerySet {
       removed.push(query.queryId);
       if (query.onServer) this.pendingRemoves.add(query.queryId);
     }
-    if (!canSend) return { message: null, removed };
+    if (!canSend) return { messages: [], removed };
 
-    const modifications: QuerySetModification[] = [];
-    for (const query of this.byToken.values()) {
-      if (!query.onServer) {
-        modifications.push({ type: "Add", queryId: query.queryId, udfPath: query.udfPath, args: query.args });
-        query.onServer = true;
+    // Split so that no message outgrows the server's limit. The removes go first: the server applies a message in
+    // order and caps what is live after each step, so a set near the cap is swapped by making room before using it.
+    const batches: QuerySetModification[][] = [[]];
+    let chars = 0;
+    for (const queryId of this.pendingRemoves) {
+      let batch = batches[batches.length - 1]!;
+      if (chars + REMOVE_CHARS > MODIFY_QUERY_SET_CHARS) {
+        batch = [];
+        batches.push(batch);
+        chars = 0;
       }
+      batch.push({ type: "Remove", queryId });
+      chars += REMOVE_CHARS;
     }
-    for (const queryId of this.pendingRemoves) modifications.push({ type: "Remove", queryId });
     this.pendingRemoves.clear();
-    if (modifications.length === 0) return { message: null, removed };
+    for (const query of this.byToken.values()) {
+      if (query.onServer) continue;
+      // The token is the path and the canonical JSON of the arguments: about what the Add takes on the wire.
+      const size = query.token.length;
+      let batch = batches[batches.length - 1]!;
+      if (batch.length > 0 && chars + size > MODIFY_QUERY_SET_CHARS) {
+        batch = [];
+        batches.push(batch);
+        chars = 0;
+      }
+      batch.push({ type: "Add", queryId: query.queryId, udfPath: query.udfPath, args: query.args });
+      chars += size;
+      query.onServer = true;
+    }
 
-    const baseVersion = this.querySetVersion;
-    this.querySetVersion += 1;
-    return {
-      message: { type: "ModifyQuerySet", baseVersion, newVersion: this.querySetVersion, modifications },
-      removed,
-    };
+    const messages: ModifyQuerySetMessage[] = [];
+    for (const modifications of batches) {
+      if (modifications.length === 0) continue;
+      const baseVersion = this.querySetVersion;
+      this.querySetVersion += 1;
+      messages.push({ type: "ModifyQuerySet", baseVersion, newVersion: this.querySetVersion, modifications });
+    }
+    return { messages, removed };
   }
 
   /** The server state is fresh on a new socket: nothing is subscribed and the query set version is 0. */

package/src/protocol.ts

@@ -6,7 +6,7 @@ export type QueryId = number;
 export type RequestId = number;
 export type JSONValue = null | boolean | number | string | JSONValue[] | { [key: string]: JSONValue };
 
-export const CLIENT_VERSION = "0.12.0";
+export const CLIENT_VERSION = "0.13.0";
 
 export interface StateVersion {
   querySet: number;

package/src/web_socket_manager.ts

@@ -5,6 +5,8 @@ import type { Logger } from "./logging.js";
 export const SERVER_INACTIVITY_TIMEOUT_MS = 30_000;
 const INITIAL_BACKOFF_MS = 250;
 const MAX_BACKOFF_MS = 16_000;
+/** `FatalError`s closer together than this are one streak ({@link WebSocketManager.reconnectAfterFatal}). */
+const FATAL_STREAK_MS = 60_000;
 /**
  * A socket that hasn't opened after this long is dropped and retried (a black-holed connect would otherwise hang
  * forever). As long as the silence threshold: a server that takes longer than that to accept is as good as down.
@@ -65,6 +67,9 @@ export class WebSocketManager {
   private _hasEverConnected = false;
   private lastCloseReason: string | null = null;
   private retries = 0;
+  /** `FatalError`s in the current streak, and when the last one came. */
+  private fatalErrors = 0;
+  private lastFatalAt = 0;
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
   private watchdogTimer: ReturnType<typeof setTimeout> | null = null;
   private connectTimer: ReturnType<typeof setTimeout> | null = null;
@@ -148,6 +153,22 @@ export class WebSocketManager {
     this.scheduleReconnect(reason);
   }
 
+  /**
+   * The server refused something this client sent and ended the socket (`FatalError`). The client will send it
+   * again, or something like it, on the next socket, so each refusal that follows the last within a minute waits
+   * longer than the one before: nothing a healthy-looking socket says in between (its first Transition arrives
+   * before the refusal) starts the delays over.
+   */
+  reconnectAfterFatal(reason: string): void {
+    if (this._state === "stopped") return;
+    const now = Date.now();
+    if (now - this.lastFatalAt > FATAL_STREAK_MS) this.fatalErrors = 0;
+    this.lastFatalAt = now;
+    this.retries = Math.max(this.retries, this.fatalErrors);
+    this.fatalErrors += 1;
+    this.reconnect(reason);
+  }
+
   /** Permanently closes the socket. */
   stop(): void {
     if (this._state === "stopped") return;