@honeybbq/teamspeak 1.0.0-beta.19 → 1.0.0-beta.21

package/src/core/reconnect.ts

@@ -15,20 +15,20 @@
 
 /** How long to wait before each attempt. */
 export interface BackoffPolicy {
-  /** Delay before the first retry, in milliseconds. */
+  /** Delay before the first retry, in milliseconds; above 0. */
   readonly initialDelayMs: number;
-  /** Ceiling for the delay; it never grows past this. */
+  /** Ceiling for the delay; it never grows past this. Above 0, and not below `initialDelayMs`. */
   readonly maxDelayMs: number;
-  /** Multiplier applied after each failed attempt. */
+  /** Multiplier applied after each failed attempt; 1 or more. */
   readonly factor: number;
   /**
-   * Fraction of the delay to randomise, 0 to 1.
+   * Fraction of the delay to randomise, up to 1; 0 or below turns it off.
    *
    * A fleet of bots that drop together would otherwise retry in lockstep and
    * hit the server in a burst. Jitter spreads them out.
    */
   readonly jitter: number;
-  /** Give up after this many consecutive failures. 0 means never give up. */
+  /** Give up after this many consecutive failures. 0 means never give up; a whole number. */
   readonly maxAttempts: number;
 }
 
@@ -88,11 +88,63 @@ export function jitteredDelay(
   return Math.round(Math.max(0, Math.min(delay, policy.maxDelayMs)));
 }
 
+/**
+ * The policy `options` asks for, with the defaults filled in. A value the
+ * caller gave that cannot work is a RangeError, thrown when the client is made
+ * rather than when the loop first runs: a delay of 0 or a NaN factor would
+ * retry in a tight loop, and the flood ban that follows outlasts the outage.
+ *
+ * Accepted: delays above 0 (an unset `maxDelayMs` is raised to `initialDelayMs`
+ * when that is larger than the default; one given below `initialDelayMs` is
+ * refused), a factor of at least 1, a jitter of at most 1 (0 or below turns it
+ * off), and a whole `maxAttempts` of 0 or more.
+ */
 export function resolveBackoffPolicy(options: ReconnectOptions): BackoffPolicy {
   const policy: Record<string, number> = { ...defaultBackoffPolicy };
   // An explicit undefined keeps the default, as an unset field does.
-  for (const [key, value] of Object.entries(options.backoff ?? {})) {
-    if (value !== undefined) policy[key] = value;
+  const given = Object.entries(options.backoff ?? {}).filter(([, value]) => value !== undefined);
+  for (const [key, value] of given) policy[key] = value as number;
+  const resolved = policy as unknown as BackoffPolicy;
+  const set = (key: keyof BackoffPolicy): boolean => given.some(([k]) => k === key);
+
+  requireNumber(
+    "initialDelayMs",
+    resolved.initialDelayMs,
+    "a number of milliseconds above 0",
+    (v) => v > 0,
+  );
+  requireNumber(
+    "maxDelayMs",
+    resolved.maxDelayMs,
+    "a number of milliseconds above 0",
+    (v) => v > 0,
+  );
+  requireNumber("factor", resolved.factor, "a number from 1 up", (v) => v >= 1);
+  requireNumber("jitter", resolved.jitter, "a number up to 1", (v) => v <= 1);
+  requireNumber(
+    "maxAttempts",
+    resolved.maxAttempts,
+    "a whole number, 0 or more",
+    (v) => Number.isInteger(v) && v >= 0,
+  );
+  if (resolved.maxDelayMs < resolved.initialDelayMs) {
+    if (set("maxDelayMs")) {
+      throw new RangeError(
+        `maxDelayMs (${resolved.maxDelayMs}) is below initialDelayMs (${resolved.initialDelayMs})`,
+      );
+    }
+    return { ...resolved, maxDelayMs: resolved.initialDelayMs };
+  }
+  return resolved;
+}
+
+function requireNumber(
+  name: string,
+  value: unknown,
+  expected: string,
+  ok: (value: number) => boolean,
+): void {
+  if (typeof value !== "number" || !Number.isFinite(value) || !ok(value)) {
+    throw new RangeError(`the backoff's ${name} is ${expected}, not ${String(value)}`);
   }
-  return policy as unknown as BackoffPolicy;
 }

package/src/core/types.ts

@@ -77,40 +77,39 @@ export const consoleLogger: Logger = Object.freeze({
 export interface FileUploadInfo {
   /** The key that identifies the transfer on the file transfer connection. */
   readonly fileTransferKey: string;
-  /** Where to resume from, in bytes; 0 for a fresh upload. */
+  /** The file's whole size in bytes, as the negotiation declared it. */
+  readonly size: bigint;
+  /**
+   * Where the upload continues from, in bytes: 0 for a fresh upload, and with
+   * `resume` the size of the partial file the server holds. The data to send
+   * is the file from here on.
+   */
   readonly seekPosition: bigint;
   /** The client's id for the transfer. */
   readonly clientFileTransferID: ClientFileTransferID;
   /** The server's id for the transfer. */
   readonly serverFileTransferID: ServerFileTransferID;
-  /** The file transfer port to dial. */
+  /** The file transfer port to dial, on the host the connection uses. */
   readonly port: number;
-  /**
-   * The address to dial instead of the one the connection uses (`ip`): the
-   * server sends it when it finds the file transfer unreachable at the address
-   * of the command connection, such as behind NAT. Undefined when it sends
-   * none, which is every answer measured on TS3 and TS6.
-   */
-  readonly ip?: string | undefined;
 }
 
 /** A negotiated download, as `initFileDownload` returns it: what to dial and receive. */
 export interface FileDownloadInfo {
   /** The key that identifies the transfer on the file transfer connection. */
   readonly fileTransferKey: string;
-  /** How many bytes the server will send. */
+  /** The file's whole size in bytes, whatever `seekPosition` is. */
   readonly size: bigint;
+  /**
+   * Where the download starts from, in bytes, as it was asked for: the server
+   * sends the file from here to its end, `size` less this many bytes.
+   */
+  readonly seekPosition: bigint;
   /** The client's id for the transfer. */
   readonly clientFileTransferID: ClientFileTransferID;
   /** The server's id for the transfer. */
   readonly serverFileTransferID: ServerFileTransferID;
-  /** The file transfer port to dial. */
+  /** The file transfer port to dial, on the host the connection uses. */
   readonly port: number;
-  /**
-   * The address to dial instead of the one the connection uses (`ip`); see
-   * {@link FileUploadInfo.ip}.
-   */
-  readonly ip?: string | undefined;
 }
 
 /** Removes a listener; calling it again does nothing. Also a `Disposable`, for `using`. */

package/src/query/client.ts

@@ -29,6 +29,9 @@ import {
   buildCommandChain,
   buildCommandOrdered,
   encodeRequest,
+  floodHoldMs,
+  FLOOD_RETRIES,
+  floodRetryDelayMs,
   handleNotification,
   parseCommand,
   parseServerError,
@@ -47,7 +50,7 @@ import {
   type QueryEventCategory,
 } from "./options.js";
 import type { ResolvedQueryOptions, ResolvedTransport } from "./options.js";
-import { defaultShouldRetry } from "./reconnect.js";
+import { defaultShouldRetry, noteConnectFailure } from "./reconnect.js";
 
 export type {
   QueryClientOptions,
@@ -155,7 +158,12 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
    * rather than taken for the next command's.
    */
   #abandoned = 0;
+  /** When a command was last sent, which is what the server counts idleness from. */
+  #lastSent = 0;
+  #keepAlive: ReturnType<typeof setTimeout> | undefined;
   #queue: Promise<unknown> = Promise.resolve();
+  /** Connected with no `server`, so the `events` are registered by the first `use()`. */
+  #eventsPending = false;
   #closed = true;
   /**
    * Bumped by `disconnect()`. A connection attempt that was in flight compares
@@ -217,6 +225,8 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
     this.#options = normalizeQueryOptions(options);
     this.#logger = this.#options.logger ?? noopLogger;
     this.#notifications = this.#options.notificationsSupported;
+    // Refused here, not when the loop first runs: a bad policy would flood.
+    if (this.#options.reconnect !== undefined) resolveBackoffPolicy(this.#options.reconnect);
     this.#reconnectOptions = this.#options.reconnect;
     const middlewares: readonly CommandMiddleware[] = this.#options.commandMiddleware ?? [];
     // Built once: the chain is read on every command, and changing it while
@@ -417,26 +427,83 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
     transport.onLine = (line) => this.#handleLine(line);
     transport.onClose = (error) => this.#handleClose(error);
 
-    const { transport: resolvedTransport, server, nickname, eventCategories } = this.#options;
+    const { transport: resolvedTransport, server, nickname } = this.#options;
     const login = resolvedTransport.kind === "tcp" ? resolvedTransport.login : undefined;
-    if (login !== undefined) await this.login(login.name, login.password, { signal });
+    if (login !== undefined) {
+      await this.login(login.name, login.password, { signal }).catch((error: unknown) => {
+        noteConnectFailure("login", error);
+        throw error;
+      });
+    }
     // Not `use()`: this session learns who it is, and who is there, once, below.
-    if (server !== undefined) await this.#select(server, { nickname, signal });
+    if (server !== undefined) {
+      await this.#select(server, { nickname, signal }).catch((error: unknown) => {
+        noteConnectFailure("use", error);
+        throw error;
+      });
+    }
     this.#version = await this.#getVersion(signal);
     this.#serverFamily = serverFamilyForVersion(this.#version);
     // Like the version, a failure here fails the connect: a client that cannot
     // tell which one it is would miss its own kick without saying so.
     await this.#learnSelf(signal);
+    // Notifications and the roster belong to a selected server. Measured on
+    // TeamSpeak 3 3.13.8 and TeamSpeak 6 6.0.0 (raw TCP and SSH): with none
+    // selected `version`, `whoami`, `instanceinfo` and `serverlist` answer,
+    // while `servernotifyregister`, `clientlist` and `clientupdate` are refused
+    // with 1024 (invalid serverID). So a client with no `server` connects for
+    // the instance-level commands, and does this on its first `use()`.
+    this.#eventsPending = false;
     if (this.#notifications) {
-      for (const category of eventCategories) {
-        // The channel category takes the channel to watch, or 0 for all of them;
-        // the others take none, and the server refuses one they do not know.
-        await this.#register(category, category === "channel" ? 0 : undefined, { signal });
-      }
-      // Only worth listing when there is something to fill: the groups and the
-      // invoker of a message this client would otherwise not know.
-      if (eventCategories.length > 0) await this.#learnClients(signal);
+      if (server === undefined) this.#eventsPending = true;
+      else await this.#registerEvents(signal);
     }
+    this.#startKeepAlive(transport);
+  }
+
+  /**
+   * Register the configured categories and list the clients, once a server is
+   * selected.
+   */
+  async #registerEvents(signal: AbortSignal | undefined): Promise<void> {
+    for (const category of this.#options.eventCategories) {
+      // The channel category takes the channel to watch, or 0 for all of them;
+      // the others take none, and the server refuses one they do not know.
+      await this.#register(category, category === "channel" ? 0 : undefined, { signal });
+    }
+    // Only worth listing when there is something to fill: the groups and the
+    // invoker of a message this client would otherwise not know.
+    if (this.#options.eventCategories.length > 0) await this.#learnClients(signal);
+  }
+
+  /**
+   * Keep a raw TCP or SSH session from idling out: the server closes one that
+   * has sent no command for 300 seconds (see `QueryClientOptions.keepAliveMs`),
+   * so `version` goes out once none has for that long. Only commands count, as
+   * the server counts them; what the server sends does not.
+   */
+  #startKeepAlive(transport: QueryTransport): void {
+    const every = this.#options.keepAliveMs;
+    const kind = this.#options.transport.kind;
+    if (every === 0 || (kind !== "tcp" && kind !== "ssh")) return;
+    const tick = (): void => {
+      if (this.#transport !== transport || this.#closed) return;
+      const idle = Date.now() - this.#lastSent;
+      if (idle >= every) {
+        this.#logger.debug("keeping the idle session open", { idleMs: idle });
+        // A failure is the connection dropping, which its own close reports.
+        this.exec("version").catch(() => {});
+        this.#keepAlive = setTimeout(tick, every);
+      } else {
+        this.#keepAlive = setTimeout(tick, every - idle);
+      }
+      // The socket keeps the process alive; this timer must not.
+      this.#keepAlive.unref();
+    };
+    clearTimeout(this.#keepAlive);
+    this.#lastSent = Date.now();
+    this.#keepAlive = setTimeout(tick, every);
+    this.#keepAlive.unref();
   }
 
   /**
@@ -473,6 +540,7 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
     this.#logger.info("disconnecting from query server");
     const transport = this.#transport;
     this.#transport = null;
+    clearTimeout(this.#keepAlive);
     // Set before the transport is closed, so the close it reports is not read
     // as the connection dropping.
     this.#closed = true;
@@ -566,6 +634,10 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
    * and the notifications registered are gone, so `use` again and
    * {@link QueryClient.registerNotifications} again.
    *
+   * A client connected with no `server` has registered no `events` yet, as
+   * the server refuses that with none selected: the first successful `use`
+   * registers them.
+   *
    * A reconnect starts over from the options the client was made with: it logs
    * in, selects `server` and registers `events` again, and does not repeat a
    * `use` made by hand.
@@ -579,7 +651,10 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
     // none has no use for.
     if (!this.#notifications) return;
     await this.#learnSelf(options.signal);
-    if (this.#options.eventCategories.length > 0) await this.#learnClients(options.signal);
+    if (this.#eventsPending) {
+      await this.#registerEvents(options.signal);
+      this.#eventsPending = false;
+    } else if (this.#options.eventCategories.length > 0) await this.#learnClients(options.signal);
   }
 
   /** The `use` command, and what it does to what the client knows. */
@@ -870,8 +945,8 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
   }
 
   /**
-   * List the clients once, so that `invokerGroups` and the invoker fields of a
-   * self-move can be filled: an enter notification is only seen for clients
+   * List the clients once, so that `invokerGroups` and the `fromChannelID` of
+   * a move can be filled: an enter notification is only seen for clients
    * that arrive after registering, and the ones already there arrive as none.
    * `-away` and `-voice` make the records carry away and mute state as well,
    * in the same one command. The groups are as of this listing: a ServerQuery
@@ -892,7 +967,49 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
     }
   }
 
+  /**
+   * Run a command, and run it again when the server refuses it as flooding
+   * with a time to wait that the command can afford. The server did not run a
+   * refused command, and the next command waits behind this one in the queue,
+   * so nothing is sent while the pause lasts.
+   *
+   * Measured on TeamSpeak 3 3.13.8 (raw TCP) and TeamSpeak 6 6.0.0 (SSH): the
+   * refusal is `error id=524 ... extra_msg=please\swait\s1\sseconds`, the
+   * connection stays open, and sending again before the pause is over only
+   * prolongs it. WebQuery has no such answer; see {@link floodRetryDelayMs}.
+   */
   async #execNow(line: string, options: CommandOptions): Promise<Array<Record<string, string>>> {
+    const { signal, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS } = options;
+    const deadline = performance.now() + timeoutMs;
+    for (let refused = 0; ; refused++) {
+      try {
+        return await this.#execOnce(line, {
+          ...options,
+          timeoutMs: Math.max(deadline - performance.now(), 0),
+        });
+      } catch (error) {
+        const wait = error instanceof Error ? floodRetryDelayMs(error) : undefined;
+        const hold = wait === undefined ? undefined : floodHoldMs(wait);
+        if (
+          wait === undefined ||
+          hold === undefined ||
+          refused >= FLOOD_RETRIES ||
+          hold >= deadline - performance.now() ||
+          this.#closed
+        ) {
+          throw error;
+        }
+        this.#logger.debug("the server asked for a pause", {
+          command: parseCommand(line)?.name,
+          waitMs: wait,
+        });
+        await sleep(hold, signal);
+        signal?.throwIfAborted();
+      }
+    }
+  }
+
+  async #execOnce(line: string, options: CommandOptions): Promise<Array<Record<string, string>>> {
     const { signal, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS } = options;
     signal?.throwIfAborted();
     if (this.#closed || this.#transport === null) throw new NotConnectedError();
@@ -917,8 +1034,12 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
     const sending = { failed: false };
     let abandonedByUs = false;
     const transport = this.#transport;
+    this.#lastSent = Date.now();
     const nudges = this.#options.transport.kind === "ssh";
-    const send = transport.send(line).then(
+    // Ended with the command, so that a request nobody waits for any more is
+    // not left running to answer the next command; see `QueryTransport.send`.
+    const sendAbort = new AbortController();
+    const send = transport.send(line, { signal: sendAbort.signal }).then(
       () => {
         // On TeamSpeak 6 over SSH the server may hold back the last line of a
         // reply, usually `error id=0 msg=ok`, until the client writes again;
@@ -950,6 +1071,7 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
       return await answered;
     } finally {
       clearTimeout(timer);
+      sendAbort.abort();
       nudgerStopped = true;
       clearTimeout(nudger);
       if (onAbort) signal?.removeEventListener("abort", onAbort);
@@ -1166,6 +1288,7 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
   #handleClose(error: Error | undefined): void {
     if (this.#status === ClientStatus.Disconnected) return;
     this.#transport = null;
+    clearTimeout(this.#keepAlive);
     this.#closed = true;
     this.#fail(new NotConnectedError(error ? { cause: error } : undefined));
     const wasConnected = this.#status === ClientStatus.Connected;
@@ -1208,6 +1331,7 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
     this.#fail(error);
     const transport = this.#transport;
     this.#transport = null;
+    clearTimeout(this.#keepAlive);
     void transport?.close().catch(() => {});
     if (!this.#reconnecting) return;
     const cause =
@@ -1373,16 +1497,16 @@ function serverIDOf(server: ResolvedQueryOptions["server"]): ServerID | number |
 }
 
 /** Sleep, or wake early once `signal` aborts. Resolves either way, never rejects. */
-function sleep(ms: number, signal: AbortSignal): Promise<void> {
-  if (ms <= 0 || signal.aborted) return Promise.resolve();
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  if (ms <= 0 || signal?.aborted) return Promise.resolve();
   return new Promise((resolve) => {
     const done = (): void => {
       clearTimeout(timer);
-      signal.removeEventListener("abort", done);
+      signal?.removeEventListener("abort", done);
       resolve();
     };
     const timer = setTimeout(done, ms);
-    signal.addEventListener("abort", done, { once: true });
+    signal?.addEventListener("abort", done, { once: true });
   });
 }
 

package/src/query/errors.ts

@@ -143,3 +143,37 @@ export class GuestAccessError extends TeamspeakError {
     this.code = code;
   }
 }
+
+/**
+ * A line longer than 256 MiB came from the server, which ends
+ * the connection.
+ *
+ * ServerQuery writes an answer's rows on one line, so the limit is the largest
+ * answer: a client database listing is about 240 bytes a client, so 256 MiB
+ * holds about a million of them, and the longest answer measured on TeamSpeak 3
+ * and 6, the permission list, is under 50 KiB. A server that sends more is not
+ * speaking ServerQuery, and reading on would only fill memory.
+ *
+ * @experimental Part of the `@honeybbq/teamspeak/query` entry, which may
+ * change in a minor release.
+ */
+export class LineTooLongError extends TeamspeakError {
+  /** {@inheritDoc @honeybbq/teamspeak!TeamspeakError.kind} */
+  static override readonly kind: string = "LineTooLongError";
+  static {
+    Object.defineProperty(this.prototype, "name", {
+      value: "LineTooLongError",
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
+  }
+
+  /** The longest line read, in bytes. */
+  readonly limit: number;
+
+  constructor(limit: number) {
+    super(`the server sent a line longer than the limit of ${limit} bytes`);
+    this.limit = limit;
+  }
+}

package/src/query/index.ts

@@ -39,6 +39,7 @@ export { defaultShouldRetry } from "./reconnect.js";
 // Errors unique to ServerQuery.
 export {
   GuestAccessError,
+  LineTooLongError,
   MissingDependencyError,
   QueryAuthError,
   SshHostKeyError,

package/src/query/lines.ts

@@ -1,5 +1,14 @@
+import { LineTooLongError } from "./errors.js";
 import { trimCarriageReturns } from "./trim.js";
 
+/**
+ * The longest line a connection reads, in bytes: 256 MiB. A line is a whole
+ * answer, and a client database listing is about 240 bytes a client, so this
+ * holds about a million of them; the permission list, the longest answer
+ * measured on TeamSpeak 3 and 6, is under 50 KiB. See {@link LineTooLongError}.
+ */
+export const MAX_LINE_BYTES: number = 256 * 1024 * 1024;
+
 /**
  * Splits a byte stream into the lines ServerQuery speaks.
  *
@@ -7,21 +16,44 @@ import { trimCarriageReturns } from "./trim.js";
  * start of the next line rather than the end of this one; both ends are
  * trimmed. Bytes are decoded as UTF-8 only once a whole line is in, so a
  * character split across two chunks arrives whole.
+ *
+ * Each byte is looked at once, however many chunks a line arrives in. A line
+ * past the limit throws {@link LineTooLongError}.
  */
 export class LineReader {
-  #pending = Buffer.alloc(0);
+  /** The chunks of the line still being read; none holds a newline. */
+  #parts: Uint8Array[] = [];
+  #length = 0;
+  readonly #limit: number;
+
+  constructor(limit: number = MAX_LINE_BYTES) {
+    this.#limit = limit;
+  }
 
   /** Add a chunk and return the lines it completed, without their terminators. */
   push(chunk: Uint8Array): string[] {
-    this.#pending = Buffer.concat([this.#pending, chunk]);
     const lines: string[] = [];
+    let start = 0;
     for (;;) {
-      const end = this.#pending.indexOf(0x0a);
+      const end = Buffer.prototype.indexOf.call(chunk, 0x0a, start) as number;
       if (end < 0) break;
-      const line = trimCarriageReturns(this.#pending.subarray(0, end).toString("utf8"));
-      this.#pending = this.#pending.subarray(end + 1);
-      lines.push(line);
+      this.#add(chunk.subarray(start, end));
+      lines.push(trimCarriageReturns(Buffer.concat(this.#parts, this.#length).toString("utf8")));
+      this.#parts = [];
+      this.#length = 0;
+      start = end + 1;
     }
+    this.#add(chunk.subarray(start));
     return lines;
   }
+
+  #add(part: Uint8Array): void {
+    this.#length += part.byteLength;
+    if (this.#length > this.#limit) {
+      this.#parts = [];
+      this.#length = 0;
+      throw new LineTooLongError(this.#limit);
+    }
+    if (part.byteLength > 0) this.#parts.push(part);
+  }
 }

package/src/query/options.ts

@@ -126,6 +126,10 @@ export interface QueryClientOptions {
    * WebQuery the transport answers `use` itself, by addressing that server in
    * its requests. Unset leaves the instance selected on raw TCP, where the
    * server's own default applies.
+   *
+   * Without it the client connects with no server selected, which serves the
+   * instance-level commands (`instanceinfo`, `serverlist`, `use`). The events
+   * need a server, so they are registered by the first {@link QueryClient.use}.
    */
   readonly server?: { readonly id: ServerID | number } | { readonly port: number } | undefined;
   /** The query client's nickname on the server (`client_nickname` of `use`). */
@@ -138,6 +142,14 @@ export interface QueryClientOptions {
    * Registering for anything on a transport that cannot deliver notifications
    * throws a `TypeError`, at construction when the `transport` kind says so
    * and when connecting for a `custom` transport.
+   *
+   * The client keeps a roster of who is on the server, to fill the fields a
+   * notification leaves out, such as a sender's groups: a snapshot taken on
+   * connecting (`clientlist -uid -groups -away -voice`), kept up to date by the
+   * enter, leave and move notifications. A ServerQuery connection is not sent
+   * `clientupdated`, so a client's groups, away flag and mute state are as of
+   * the listing, or of the moment it entered view, and do not follow later
+   * changes.
    */
   readonly events?: QueryEventsOption | undefined;
   /**
@@ -146,6 +158,21 @@ export interface QueryClientOptions {
    * decision is {@link defaultShouldRetry}.
    */
   readonly reconnect?: ReconnectOptions | undefined;
+  /**
+   * How long a raw TCP or SSH session may sit idle before the client sends
+   * `version` to keep it open, in milliseconds. 120000 (two minutes) by default;
+   * `0` turns it off.
+   *
+   * Measured on TeamSpeak 3 3.13.8 (raw TCP and SSH) and TeamSpeak 6
+   * 6.0.0-beta13.1 (SSH): the server closes a query session that has sent no
+   * command for 300 seconds, and a session that sends one every 200 seconds
+   * stays open. Notifications arriving do not count: a raw TCP session on
+   * TeamSpeak 3 that received nine and sent nothing was closed at 300 seconds
+   * all the same. The command is sent only when none has been
+   * for this long, so a busy client sends nothing extra. WebQuery has no session
+   * to keep, and a `custom` transport is left to its own owner.
+   */
+  readonly keepAliveMs?: number | undefined;
   /**
    * Wraps every typed command, outermost first; see `CommandMiddleware`. Raw
    * lines sent with `exec` do not pass through it. Fixed for the client's life.
@@ -218,9 +245,13 @@ export interface ResolvedQueryOptions {
   readonly eventsRequested: boolean;
   readonly reconnect: ReconnectOptions | undefined;
   readonly commandMiddleware: readonly CommandMiddleware[] | undefined;
+  readonly keepAliveMs: number;
   readonly logger: Logger | undefined;
 }
 
+/** How long a session may be idle before the client keeps it open; the server drops one at 300 s. */
+export const DEFAULT_KEEP_ALIVE_MS = 120_000;
+
 function nonEmpty(value: unknown, name: string): string {
   if (typeof value !== "string" || value === "") {
     throw new TypeError(`${name} is a non-empty string`);
@@ -449,6 +480,10 @@ export function normalizeQueryOptions(options: QueryClientOptions): ResolvedQuer
       throw new RangeError("server.port is an integer from 1 to 65535");
     }
   }
+  const keepAliveMs = options.keepAliveMs ?? DEFAULT_KEEP_ALIVE_MS;
+  if (!Number.isInteger(keepAliveMs) || keepAliveMs < 0) {
+    throw new RangeError("keepAliveMs is a non-negative integer, 0 to turn it off");
+  }
   const nickname = options.nickname;
   if (nickname !== undefined) nonEmpty(nickname, "nickname");
   const commandMiddleware = options.commandMiddleware;
@@ -465,6 +500,7 @@ export function normalizeQueryOptions(options: QueryClientOptions): ResolvedQuer
     eventsRequested: options.events !== undefined,
     reconnect: options.reconnect,
     commandMiddleware,
+    keepAliveMs,
     logger: options.logger,
   };
   assertEventsSupported(resolved);

package/src/query/reconnect.ts

@@ -12,15 +12,33 @@ import { MissingDependencyError, QueryAuthError, SshHostKeyError } from "./error
  * reconnect loop is most likely to meet right after a drop.
  */
 const PERMANENT_SERVER_ERRORS: ReadonlySet<number> = new Set([
-  ErrorCode.ClientInvalidPassword,
-  ErrorCode.ClientNotLoggedIn,
-  ErrorCode.ClientLoginNotPermitted,
-  ErrorCode.ServerInvalidID,
-  ErrorCode.ConnectFailedBanned,
-  ErrorCode.BanFlooding,
-  ErrorCode.PermissionsClientInsufficient,
+  ErrorCode.ClientInvalidPassword, // login: wrong name or password
+  ErrorCode.ClientNotLoggedIn, // use: this session has no login, and none is configured
+  ErrorCode.ClientLoginNotPermitted, // login: this account may not log in
+  ErrorCode.ServerInvalidID, // use: no such server
+  ErrorCode.ServerIsNotRunning, // use: that server is down
+  ErrorCode.ConnectFailedBanned, // retrying while banned extends the ban
+  ErrorCode.BanFlooding, // retrying while flood-banned extends the ban
+  ErrorCode.PermissionsClientInsufficient, // the account lacks the permission it needs
 ]);
 
+/**
+ * Errors of a `login` or `use` that {@link isPermanentCommandError} found
+ * permanent. The error is the same object `shouldRetry` is later given, so
+ * the mark travels with it without changing its type.
+ */
+const connectRefusals = new WeakSet();
+
+/**
+ * Record why a command of `connect()` failed, so that the default
+ * `shouldRetry` can tell a refused `login` or `use` from any other failure.
+ */
+export function noteConnectFailure(command: string, error: unknown): void {
+  if (typeof error === "object" && error !== null && isPermanentCommandError(command, error)) {
+    connectRefusals.add(error);
+  }
+}
+
 /** Commands whose refusal is the credentials or the target, not the network. */
 const CONNECT_COMMANDS: ReadonlySet<string> = new Set(["login", "use"]);
 
@@ -47,6 +65,8 @@ const TRANSIENT_SERVER_ERRORS: ReadonlySet<number> = new Set([ErrorCode.ClientIs
  * A custom `shouldRetry` replaces this; see `ReconnectOptions`.
  */
 export function defaultShouldRetry(error: Error | undefined): boolean {
+  // A refused `login` or `use`, whatever its code; see `noteConnectFailure`.
+  if (error !== undefined && connectRefusals.has(error)) return false;
   // The client is connected, or connecting, already: nothing is left to retry.
   if (error instanceof AlreadyConnectedError) return false;
   // An account the server refused, or a transport that is on the wrong side