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

package/src/client/api/files.ts

@@ -22,6 +22,7 @@ import type {
 } from "@honeybbq/teamspeak";
 import { FileTransferError } from "../errors.js";
 import { downloadFileData, uploadFileData } from "../transfer.js";
+import { verifyStored, withDialCleanup } from "./upload-checks.js";
 import type { FileTransferOptions } from "../transfer.js";
 
 /**
@@ -173,8 +174,15 @@ function skipBytes(count: number): Transform {
  *
  * `data` is the bytes, or a `Readable` with `options.size` the number of bytes
  * it will give. It resolves once the server has closed the transfer
- * connection, which it does when it has the file; a stream that gives fewer or
- * more bytes than `size` fails the call, and the connection is closed.
+ * connection and, by `ftgetfileinfo` (one more command), holds a file of
+ * exactly that size: the server does not say whether it stored a file, so a
+ * close alone could be a transfer someone stopped. A size that differs, or a
+ * file that is not there, fails the call with a {@link FileTransferError}; a
+ * client with no browse power cannot ask (2568) and resolves on the close. A
+ * stream that gives fewer or more bytes than `size` fails the call, and the
+ * connection is closed. When the connection to the file transfer port is
+ * refused or times out, the negotiated transfer is stopped on the server (else
+ * it lingers in `ftlist` for about 10 seconds), as it is for `downloadFile`.
  *
  * With `resume`, `data` is still the whole file: the server says how much it
  * already holds from an interrupted upload (a file that is not there is
@@ -213,7 +221,10 @@ export async function uploadFile(
   if (data instanceof Uint8Array) source = Readable.from([data.subarray(skip)]);
   else if (skip === 0) source = data;
   else source = pipeline(data, skipBytes(skip), () => {});
-  await route.upload(info, source, transferOptions(options));
+  await withDialCleanup(client, info.serverFileTransferID, () =>
+    route.upload(info, source, transferOptions(options)),
+  );
+  await verifyStored(client, channelID, path, size, options);
 }
 
 /**
@@ -266,7 +277,10 @@ export async function downloadFile(
     timeoutMs: options.timeoutMs,
   });
   if (options.dest !== undefined) {
-    await route.download(info, options.dest, transferOptions(options));
+    const dest = options.dest;
+    await withDialCleanup(client, info.serverFileTransferID, () =>
+      route.download(info, dest, transferOptions(options)),
+    );
     return;
   }
   const wanted = info.size - info.seekPosition;
@@ -286,7 +300,9 @@ export async function downloadFile(
       done();
     },
   });
-  await route.download(info, sink, transferOptions(options));
+  await withDialCleanup(client, info.serverFileTransferID, () =>
+    route.download(info, sink, transferOptions(options)),
+  );
   return Buffer.concat(chunks);
 }
 

package/src/client/api/upload-checks.ts

@@ -0,0 +1,96 @@
+/**
+ * What an upload does around its data phase: stop a transfer whose connection
+ * was never made, and check what the server stored once it closed the
+ * connection. Shared by the file and avatar helpers; not exported from the
+ * package.
+ */
+
+import { ErrorCode, ServerError, getFileInfo, stopFileTransfer } from "@honeybbq/teamspeak";
+import type { ChannelID, CommandExecutor, FileUploadInfo } from "@honeybbq/teamspeak";
+import { FileTransferError } from "../errors.js";
+import { failedToConnect } from "../transfer.js";
+
+/**
+ * The server drops a transfer nobody dialled after about 10 seconds (measured
+ * on TeamSpeak 3 3.13.8 and TeamSpeak 6 6.0.0: it is gone from `ftlist` at
+ * 10.05 s, and the voice client hears 2059). `ftstop` of a transfer the server
+ * no longer has crashes TeamSpeak 6, so a stop is only sent well inside that.
+ */
+const STOP_WITHIN_MS = 5_000;
+
+/**
+ * Runs the data phase of a transfer the server has negotiated. When it fails
+ * because the connection to the file transfer port was refused or timed out,
+ * nothing has reached the server, and the transfer would sit in its list until
+ * it expires: stop it, as a refused `maxSize` download does. The stop is best
+ * effort and never replaces the dial's error. Not sent once the connection
+ * opened (the key may be written and the server may have dropped the transfer),
+ * nor after `STOP_WITHIN_MS`.
+ */
+export async function withDialCleanup(
+  client: CommandExecutor,
+  serverFileTransferID: FileUploadInfo["serverFileTransferID"],
+  move: () => Promise<void>,
+): Promise<void> {
+  const negotiatedAt = performance.now();
+  try {
+    await move();
+  } catch (error) {
+    if (failedToConnect(error) && performance.now() - negotiatedAt < STOP_WITHIN_MS) {
+      await stopFileTransfer(client, serverFileTransferID).catch(() => {});
+    }
+    throw error;
+  }
+}
+
+/**
+ * Checks that the server holds the whole file after an upload's connection
+ * closed. Measured on TeamSpeak 3 3.13.8 and TeamSpeak 6 6.0.0: a completed
+ * upload gets no status from the server, so a close after the last byte looks
+ * the same whether the file was stored or the transfer was stopped (the voice
+ * protocol reports that, 2066, only after the close), and `ftgetfileinfo`
+ * already answers the final size 6 to 45 ms after the close, in every case.
+ * Permissions are checked at the negotiation only, so no refusal comes later.
+ *
+ * A client without browse power gets 2568 for `ftgetfileinfo`: the file cannot
+ * be checked, and the upload resolves on the close. Any other failure of the
+ * command is thrown as it is.
+ */
+export async function verifyStored(
+  client: CommandExecutor,
+  channelID: ChannelID,
+  path: string,
+  size: bigint,
+  options: {
+    readonly password?: string | undefined;
+    readonly signal?: AbortSignal | undefined;
+    readonly timeoutMs?: number | undefined;
+  },
+): Promise<void> {
+  let stored: bigint;
+  try {
+    stored = (
+      await getFileInfo(client, channelID, path, {
+        password: options.password,
+        signal: options.signal,
+        timeoutMs: options.timeoutMs,
+      })
+    ).size;
+  } catch (error) {
+    if (error instanceof ServerError) {
+      if (error.code === ErrorCode.PermissionsClientInsufficient) return;
+      // 2051 on TeamSpeak 6, 2052 on TeamSpeak 3 for a file that is not there.
+      if (error.code === ErrorCode.FileNotFound || error.code === ErrorCode.FileIOError) {
+        throw new FileTransferError(`the server closed the upload but has no file ${path}`, {
+          cause: error,
+        });
+      }
+    }
+    throw error;
+  }
+  if (stored !== size) {
+    throw new FileTransferError(
+      `the server closed the upload but holds ${stored} of the ${size} bytes of ${path}`,
+    );
+  }
+}

package/src/client/client.ts

@@ -50,6 +50,8 @@ import {
   buildCommand,
   buildCommandChain,
   encodeRequest,
+  floodHoldMs,
+  FLOOD_RETRIES,
   floodRetryDelayMs,
   parseServerError,
   resolveBackoffPolicy,
@@ -193,15 +195,6 @@ export function clientInternals(client: Client): ClientInternals {
   return internalsOf(client);
 }
 
-/**
- * How many times a command refused as flooding is sent again after the pause
- * the server asked for. The first resend is usually refused once more with a
- * shorter wait, and the second goes through (measured on TeamSpeak 3 and 6).
- */
-const FLOOD_RETRIES = 3;
-/** Added to the server's wait, which counts down to the millisecond. */
-const FLOOD_HOLD_MARGIN_MS = 10;
-
 /** How long a command waits for its answer unless told otherwise. */
 const DEFAULT_COMMAND_TIMEOUT_MS = 10_000;
 
@@ -965,17 +958,18 @@ export class Client implements CommandExecutor, AsyncDisposable {
         // afford: nothing is sent until then, and the command, which the
         // server did not run, goes out again.
         const wait = result.err ? floodRetryDelayMs(result.err) : undefined;
+        const hold = wait === undefined ? undefined : floodHoldMs(wait);
         if (
-          wait !== undefined &&
+          hold !== undefined &&
           !goodbye &&
           refused < FLOOD_RETRIES &&
-          wait < deadline - performance.now()
+          hold < deadline - performance.now()
         ) {
           this.#logger.debug("the server asked for a pause", {
             command: parsed?.name,
             waitMs: wait,
           });
-          this.#throttle.hold(wait + FLOOD_HOLD_MARGIN_MS);
+          this.#throttle.hold(hold);
           this.#cmdTrack.unregister(rc);
           [rc, answered] = this.#cmdTrack.register(spec, correlation, echo);
           continue;

package/src/client/transfer.ts

@@ -28,6 +28,22 @@ const PROGRESS_STEP_BYTES = 64 * 1024;
 /** The file transfer ports a connection can be made to. */
 const MAX_PORT = 65535;
 
+/**
+ * The errors of dials that failed before the connection opened. Nothing has
+ * reached the server then: not the key, and no byte of the file.
+ */
+const failedBeforeConnect = new WeakSet();
+
+/**
+ * Whether `error` is a dial that never got a connection: refused, unreachable,
+ * or timed out while connecting. Not one the caller's signal or the idle limit
+ * ended, nor one after the connection opened, where the key may have been
+ * written and the server may hold or have dropped the transfer.
+ */
+export function failedToConnect(error: unknown): boolean {
+  return typeof error === "object" && error !== null && failedBeforeConnect.has(error);
+}
+
 /** Where a failed transfer failed. */
 export type FileTransferStage = "dial" | "transfer";
 
@@ -239,8 +255,10 @@ async function dial(
   // report: a stream's unhandled `error` event takes the process down.
   const swallow = (): void => {};
   socket.on("error", swallow);
+  let open = false;
   try {
     await abortable(connected(socket), dialSignal);
+    open = true;
     idle.touch();
     await abortable(
       new Promise<void>((resolve, reject) => {
@@ -260,7 +278,11 @@ async function dial(
   } catch (error) {
     socket.destroy();
     if (timeout.aborted && error === timeout.reason) {
-      throw new FileTransferError("file transfer connection timed out", { cause: error });
+      const timedOut = new FileTransferError("file transfer connection timed out", {
+        cause: error,
+      });
+      if (!open) failedBeforeConnect.add(timedOut);
+      throw timedOut;
     }
     throw error;
   } finally {
@@ -393,12 +415,13 @@ function connected(socket: Duplex): Promise<void> {
       else reject(error);
     };
     const onConnect = (): void => done();
-    const onError = (error: Error): void =>
-      done(
-        new FileTransferError(`file transfer connection failed: ${error.message}`, {
-          cause: error,
-        }),
-      );
+    const onError = (error: Error): void => {
+      const failure = new FileTransferError(`file transfer connection failed: ${error.message}`, {
+        cause: error,
+      });
+      failedBeforeConnect.add(failure);
+      done(failure);
+    };
     socket.once("connect", onConnect);
     socket.once("ready", onConnect);
     socket.once("error", onError);
@@ -444,13 +467,19 @@ function intoStream(dest: Writable): Writable {
  * server says so, not when the last byte has left.
  */
 function intoSocket(socket: Duplex): Writable {
+  // A write after the server closed the connection fails with the socket's own
+  // error (EPIPE, or "ended by the other party"): the transfer's failure.
+  const failure = (error: Error): FileTransferError =>
+    new FileTransferError(`file transfer connection failed: ${error.message}`, {
+      cause: error,
+    });
   const sink = new Writable({
     write(chunk: Buffer, _encoding, callback) {
-      socket.write(chunk, callback);
+      socket.write(chunk, (error) => callback(error ? failure(error) : null));
     },
   });
   socket.on("error", (error: Error) => {
-    sink.destroy(error);
+    sink.destroy(failure(error));
   });
   return sink;
 }
@@ -487,6 +516,13 @@ function serverClosed(socket: Duplex, signal: AbortSignal): Promise<void> {
  * and at once after the declared size when more is sent. A connection that
  * closes before every byte is written, or that stays open for the idle limit,
  * fails the transfer.
+ *
+ * A close after the last byte is not proof that the file is stored: the server
+ * sends nothing on the transfer connection, and over the voice protocol its
+ * `notifystatusfiletransfer` comes only for a failure (2066 canceled, 2063
+ * lost connection, 2052 more than declared), after the close, never for
+ * success; over ServerQuery nothing comes. `uploadFile` therefore asks the
+ * server for the file's size with `ftgetfileinfo` before it resolves.
  */
 export async function uploadFileData(
   host: string,

package/src/core/api/files.ts

@@ -296,7 +296,11 @@ export interface FileTransferStopOptions extends CommandOptions {
  * Stop only your own transfers: TeamSpeak 6 6.0.0-beta13.1 crashes on a
  * ServerQuery `ftstop` for a transfer that is not the connection's own (one
  * that does not exist, or another client's), and nothing here guards against
- * it. See "Server behaviour the SDK works around" in `docs/serverquery-responses.md`.
+ * it. A transfer of your own is gone once it has finished, or when nobody
+ * connected to it within about 10 seconds of its being negotiated (measured on
+ * TeamSpeak 3 3.13.8 and TeamSpeak 6 6.0.0), so stopping it then crashes
+ * TeamSpeak 6 too. See "Server behaviour the SDK works around" in
+ * `docs/serverquery-responses.md`.
  */
 export async function stopFileTransfer(
   client: CommandExecutor,

package/src/core/errors.ts

@@ -251,9 +251,29 @@ export function parseErrorCode(raw: string | undefined): number {
 }
 
 /**
- * How long the server asks a client it refused as flooding to wait: the
- * `retry in 1985ms` of the extra message of error 524, in milliseconds. Undefined
- * for any other error, or one that names no wait.
+ * How many times a command refused as flooding is sent again after the pause
+ * the server asked for. On the voice protocol the first resend is usually
+ * refused once more with a shorter wait, and the second goes through (measured
+ * on TeamSpeak 3 and 6); on ServerQuery a refusal can be answered with a
+ * longer wait, which the caller's timeout then decides whether to sit out.
+ */
+export const FLOOD_RETRIES = 3;
+/**
+ * How long to pause for a refusal that asked for `waitMs`. The wait is a floor:
+ * on the voice protocol a resend after exactly the wait is refused again, and
+ * one after half as long again goes through; on ServerQuery a resend after
+ * exactly 1 second was refused 2 times in 5, and one after 2.2 seconds went
+ * through 5 times in 5 (TeamSpeak 3 3.13.8 and TeamSpeak 6 6.0.0). Every
+ * refusal costs a retry and lengthens the server's pause, so the pause is
+ * twice the wait.
+ */
+export function floodHoldMs(waitMs: number): number {
+  return waitMs * 2;
+}
+
+/**
+ * How long the server asks a client it refused as flooding to wait, in
+ * milliseconds. Undefined for any other error, or one that names no wait.
  *
  * Measured on TeamSpeak 3 3.13.8 and TeamSpeak 6 6.0.0: a voice client whose
  * antiflood points pass `virtualserver_antiflood_points_needed_command_block`
@@ -261,12 +281,28 @@ export function parseErrorCode(raw: string | undefined): number {
  * for each command, and the command is not run. The wait is a floor, not a
  * promise: a command sent as the wait ends is refused again with a shorter one,
  * and the second try went through in every measurement.
+ *
+ * A ServerQuery client (raw TCP and SSH; over WebQuery the server closes the
+ * connection and says nothing) that sends faster than
+ * `serverinstance_serverquery_flood_commands` per `_flood_time` gets the same
+ * error with the wait in whole seconds,
+ * `extra_msg=please\swait\s1\sseconds`, and the command is not run. The first
+ * refusals say 1; later ones say the instance's
+ * `serverinstance_serverquery_ban_time`, as the address is banned for that long
+ * (new connections are dropped meanwhile). Asking again every half second kept
+ * the ban going for as long as it was kept up (9 seconds against a ban time of
+ * 4), while waiting out the pause and asking once got through. The wait is a
+ * floor here too: about one resend in three after exactly the wait was refused
+ * again, with the ban time.
  */
 export function floodRetryDelayMs(error: Error): number | undefined {
   if (!(error instanceof ServerError) || error.code !== ErrorCode.ClientIsFlooding)
     return undefined;
-  const match = /^retry in (\d{1,9})ms$/.exec(error.extraMessage ?? "");
-  return match === null ? undefined : Number(match[1]);
+  const extra = error.extraMessage ?? "";
+  const millis = /^retry in (\d{1,9})ms$/.exec(extra);
+  if (millis !== null) return Number(millis[1]);
+  const seconds = /^please wait (\d{1,9}) seconds$/.exec(extra);
+  return seconds === null ? undefined : Number(seconds[1]) * 1000;
 }
 
 /**

package/src/core/internal.ts

@@ -20,6 +20,12 @@ export type { NotificationResult } from "./notifications.js";
 export { parseIconID } from "./command/ids.js";
 export { responseSpec } from "./command/responses.js";
 export type { ResponseSpec } from "./command/responses.js";
-export { floodRetryDelayMs, parseErrorCode, parseServerError } from "./errors.js";
+export {
+  floodHoldMs,
+  FLOOD_RETRIES,
+  floodRetryDelayMs,
+  parseErrorCode,
+  parseServerError,
+} from "./errors.js";
 export { splitCommandRows, parseUint64, parseUint16, parseInt10, sleep } from "./helpers.js";
 export { jitteredDelay, resolveBackoffPolicy } from "./reconnect.js";

package/src/query/client.ts

@@ -29,6 +29,9 @@ import {
   buildCommandChain,
   buildCommandOrdered,
   encodeRequest,
+  floodHoldMs,
+  FLOOD_RETRIES,
+  floodRetryDelayMs,
   handleNotification,
   parseCommand,
   parseServerError,
@@ -159,6 +162,8 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
   #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
@@ -422,7 +427,7 @@ 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 }).catch((error: unknown) => {
@@ -442,19 +447,35 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
     // 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`),
@@ -613,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.
@@ -626,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. */
@@ -939,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();
@@ -1427,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/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`). */