@honeybbq/teamspeak-client 1.0.0-beta.2 → 1.0.0-beta.4

package/src/client.ts

@@ -1,20 +1,25 @@
 import {
   type EventMap,
   type ClientOptions,
+  type DatagramSocket,
+  type ResolvedAddr,
   type EventMiddleware,
   type AddrResolver,
-  type ClientEnterEvent,
-  type KickedEvent,
   type Listener,
   type ServerEvent,
   type ServerEventName,
   type Unsubscribe,
   ClientStatus,
 } from "./types.js";
+import { ConnectPhase, type ClientTrace } from "./trace.js";
+import { callHook } from "./hooks.js";
+import { puzzleOf } from "./handshake/crypt-handshake.js";
 import {
   type ChannelID,
+  type ClientEnterEvent,
   type ClientID,
   type Codec,
+  type KickedEvent,
   type CommandMiddleware,
   type CommandOptions,
   type UID,
@@ -26,7 +31,7 @@ import {
   TeamspeakError,
   noopLogger,
 } from "@honeybbq/teamspeak-core";
-import { AlreadyConnectedError, CryptoInitError, RemovedError } from "./errors.js";
+import { AlreadyConnectedError, HandshakeError, RemovedError } from "./errors.js";
 import { abortable, abortReason } from "./abort.js";
 import { Identity, Crypt } from "./crypto/index.js";
 import { RESOLVE_BUDGET_MS, Resolver } from "./discovery/resolver.js";
@@ -35,7 +40,7 @@ import { PacketType } from "./transport/packet.js";
 import type { Packet } from "./transport/packet.js";
 import { CommandTracker, appendReturnCode } from "./commands.js";
 import { encodeRequest, parseServerError } from "@honeybbq/teamspeak-core/internal";
-import { uploadFileData, downloadFileData } from "./transfer.js";
+import { uploadFileData, downloadFileData, type FileTransferOptions } from "./transfer.js";
 import { buildCommandChain, buildEventChain } from "./events.js";
 import { processInit1 } from "./handshake/crypt-handshake.js";
 import {
@@ -103,7 +108,12 @@ export interface ClientInternals {
   clid: number;
   capabilities: ServerCapabilities;
   /** Mark the attempt in progress connected. */
-  markConnected(): void;
+  markConnected(initServer?: Readonly<Record<string, string>>): void;
+  /**
+   * The shared secret exists: the attempt moves from its handshake to joining.
+   * `serverPublicKey` is the server's `omega`, as it sent it.
+   */
+  markHandshakeDone(serverPublicKey?: string): void;
   /**
    * Send a command line without waiting for an answer, on the handshake's
    * own path: it needs an open socket, not a connected session.
@@ -145,7 +155,47 @@ const DISCONNECT_TIMEOUT_MS = 1_000;
 /** How long each reconnection attempt may take. */
 const RECONNECT_ATTEMPT_TIMEOUT_MS = 30_000;
 
-/** One connection attempt, settled once by the handshake or its failure. */
+/** What the trace hooks need to know about one attempt, from its first milestone on. */
+interface AttemptTrace {
+  readonly attempt: number;
+  readonly reconnect: boolean;
+  /** When the address was about to be resolved. */
+  readonly startedAt: number;
+  /** When the socket was about to be opened. */
+  connectStartedAt: number;
+  phase: ConnectPhase;
+  /** The `host:port` being dialled; empty until the address is resolved. */
+  target: string;
+  sessionStarted: boolean;
+  welcomeDone: boolean;
+  /** The channel rows the welcome sequence has delivered so far. */
+  channels: number;
+}
+
+/** A session that began with `sessionStart`, until its `sessionEnd`. */
+interface TracedSession {
+  readonly clientID: ClientID;
+  readonly startedAt: number;
+  readonly attempt: number;
+  readonly reconnect: boolean;
+}
+
+/** The `initserver` parameters a trace never sees, because they could carry a secret. */
+const SECRET_INITSERVER_PARAMS: ReadonlySet<string> = new Set([
+  "client_server_password",
+  "client_default_channel_password",
+  "client_default_token",
+  "client_key_offset",
+]);
+
+/**
+ * One connection attempt, settled once by the handshake or its failure.
+ *
+ * The settling is also what makes the trace's promise true: `sessionStart`
+ * is fired by whoever settles it as connected and `attemptFailed` by `reject`
+ * and `rejectAfter`, all behind the one `settled` flag, so an attempt gets
+ * exactly one of them.
+ */
 interface ConnectAttempt {
   readonly promise: Promise<void>;
   /**
@@ -155,6 +205,10 @@ interface ConnectAttempt {
    */
   readonly signal: AbortSignal;
   settled: boolean;
+  /** The trace state, once the attempt has started. */
+  trace: AttemptTrace | undefined;
+  /** Called once, if the attempt settles as failed. */
+  onFail: ((error: unknown) => void) | undefined;
   resolve(): void;
   reject(error: unknown): void;
   /**
@@ -181,6 +235,8 @@ function newConnectAttempt(): ConnectAttempt {
     promise,
     signal: controller.signal,
     settled: false,
+    trace: undefined,
+    onFail: undefined,
     resolve() {
       if (attempt.settled) return;
       attempt.settled = true;
@@ -189,12 +245,14 @@ function newConnectAttempt(): ConnectAttempt {
     reject(error) {
       if (attempt.settled) return;
       attempt.settled = true;
+      attempt.onFail?.(error);
       controller.abort(error);
       reject(error);
     },
     rejectAfter(error, until) {
       if (attempt.settled) return;
       attempt.settled = true;
+      attempt.onFail?.(error);
       controller.abort(error);
       void until.finally(() => reject(error));
     },
@@ -250,6 +308,10 @@ export class Client implements CommandExecutor, AsyncDisposable {
   #clientInitOptions: ClientInitOptions;
   #socketFactory: SocketFactory | undefined;
   #fileTransferSocketFactory: FileTransferSocketFactory | undefined;
+  /** A copy of the caller's trace, so changing theirs later changes nothing. */
+  #trace: ClientTrace | undefined;
+  /** The session in progress, for its `sessionEnd`; cleared when that has been reported. */
+  #session: TracedSession | undefined;
   /** Undefined when the client does not reconnect. */
   #reconnectOptions: ReconnectOptions | undefined;
   /**
@@ -270,6 +332,8 @@ export class Client implements CommandExecutor, AsyncDisposable {
    * the new one instead.
    */
   #leaving: Promise<void> | undefined;
+  /** Ends a disconnect()'s wait for its goodbye to be answered, while it waits. */
+  #goodbyeAnswered: (() => void) | undefined;
   /** How many times disconnect() was called, so a waiting connect() sees one. */
   #disconnects = 0;
   /**
@@ -309,6 +373,7 @@ export class Client implements CommandExecutor, AsyncDisposable {
     this.#socketFactory = options.socketFactory;
     this.#fileTransferSocketFactory = options.fileTransferSocketFactory;
     this.#reconnectOptions = options.reconnect;
+    this.#trace = options.trace === undefined ? undefined : { ...options.trace };
 
     this.#crypt = new Crypt(identity);
     this.#handler = this.#newHandler();
@@ -346,7 +411,8 @@ export class Client implements CommandExecutor, AsyncDisposable {
       set capabilities(value) {
         self.#capabilities = value;
       },
-      markConnected: () => this.#markConnected(),
+      markConnected: (initServer) => this.#markConnected(initServer),
+      markHandshakeDone: (serverPublicKey) => this.#markHandshakeDone(serverPublicKey),
       execNoWait: (command) => this.#execNoWait(command, undefined, true),
       handlePacket: (packet) => this.#handlePacket(packet),
     };
@@ -396,6 +462,14 @@ export class Client implements CommandExecutor, AsyncDisposable {
    * after `await client.connect()` still hears it.
    */
   async connect(options: { readonly signal?: AbortSignal | undefined } = {}): Promise<void> {
+    return this.#connect(options, 1, false);
+  }
+
+  async #connect(
+    options: { readonly signal?: AbortSignal | undefined },
+    attemptNumber: number,
+    reconnect: boolean,
+  ): Promise<void> {
     const { signal } = options;
     signal?.throwIfAborted();
     const disconnects = this.#disconnects;
@@ -413,6 +487,27 @@ export class Client implements CommandExecutor, AsyncDisposable {
     this.#resetForConnect();
     this.#status = ClientStatus.Connecting;
     const attempt = this.#attempt;
+    const trace: AttemptTrace = {
+      attempt: attemptNumber,
+      reconnect,
+      startedAt: performance.now(),
+      connectStartedAt: 0,
+      phase: ConnectPhase.Open,
+      target: "",
+      sessionStarted: false,
+      welcomeDone: false,
+      channels: 0,
+    };
+    attempt.trace = trace;
+    attempt.onFail = (error) =>
+      this.#callHook(this.#trace?.attemptFailed, () => ({
+        attempt: trace.attempt,
+        reconnect: trace.reconnect,
+        phase: trace.phase,
+        error,
+        target: trace.target,
+        durationMs: performance.now() - trace.startedAt,
+      }));
 
     // The handshake may complete just as the signal fires, in which case
     // #failConnection leaves the session alone and the caller gets the
@@ -421,10 +516,41 @@ export class Client implements CommandExecutor, AsyncDisposable {
     signal?.addEventListener("abort", onAbort, { once: true });
     try {
       try {
-        const targetAddr = await this.#resolveAddr(attempt.signal);
+        this.#callHook(this.#trace?.resolveStart, () => ({
+          attempt: trace.attempt,
+          reconnect: trace.reconnect,
+          addr: this.#addr,
+        }));
+        const resolveStarted = performance.now();
+        const resolution = await this.#resolveAddr(attempt.signal);
+        const targetAddr = resolution.target;
+        trace.target = targetAddr;
+        if (!attempt.settled) {
+          this.#callHook(this.#trace?.resolveDone, () => ({
+            attempt: trace.attempt,
+            reconnect: trace.reconnect,
+            addr: this.#addr,
+            target: targetAddr,
+            source: resolution.source,
+            candidates: resolution.candidates,
+            error: resolution.error,
+            durationMs: performance.now() - resolveStarted,
+          }));
+        }
         if (!attempt.settled) {
           this.#logger.info("connecting to server", { address: targetAddr });
+          trace.connectStartedAt = performance.now();
+          this.#callHook(this.#trace?.connectStart, () => ({
+            attempt: trace.attempt,
+            reconnect: trace.reconnect,
+            target: targetAddr,
+          }));
+        }
+        if (!attempt.settled) {
           await this.#handler.connect(targetAddr, attempt.signal);
+          // The socket is open and the first packet is out: a failure from
+          // here to the shared secret is the handshake's.
+          if (trace.phase === ConnectPhase.Open) trace.phase = ConnectPhase.Handshake;
         }
       } catch (error) {
         // Without this the client stays Connecting and every later connect()
@@ -479,20 +605,35 @@ export class Client implements CommandExecutor, AsyncDisposable {
     this.#logger.info("disconnecting from server");
 
     if (wasConnected) {
-      try {
-        // On the internal path: the status already says Disconnected.
-        await this.#exec(
-          "clientdisconnect reasonmsg=Shutdown",
-          { signal, timeout: DISCONNECT_TIMEOUT_MS },
-          true,
-        );
-      } catch {
-        // A courtesy; the connection closes regardless.
-      }
+      this.#callHook(this.#trace?.disconnectStart, () => ({}));
+      const goodbyeStarted = performance.now();
+      // The server answers clientdisconnect with a notifyclientleftview about
+      // this client, and no error line; either one ends the wait. A goodbye
+      // that is not answered in time is a courtesy lost: the connection
+      // closes regardless.
+      const left = new Promise<boolean>((resolve) => {
+        this.#goodbyeAnswered = () => resolve(true);
+      });
+      // On the internal path: the status already says Disconnected.
+      const answered = this.#exec(
+        "clientdisconnect reasonmsg=Shutdown",
+        { signal, timeout: DISCONNECT_TIMEOUT_MS },
+        true,
+      ).then(
+        () => true,
+        () => false,
+      );
+      const acknowledged = await Promise.race([answered, left]);
+      this.#goodbyeAnswered = undefined;
+      this.#callHook(this.#trace?.disconnectDone, () => ({
+        acknowledged,
+        durationMs: performance.now() - goodbyeStarted,
+      }));
     }
 
     this.#handler.close();
     this.#cmdTrack.reset(new NotConnectedError());
+    this.#endSession(undefined);
     // Announced here; #handleConnectionClosed stays quiet once the status is
     // already Disconnected, so listeners hear about it once.
     await this.#announceDisconnected(undefined);
@@ -684,11 +825,20 @@ export class Client implements CommandExecutor, AsyncDisposable {
    * ```
    *
    * Events that arrive while the loop body runs are buffered, so none is
-   * missed — except voice, of which at most 256 frames are buffered; the rest
-   * are dropped, as for a listener that falls behind. Iteration ends when
-   * `signal` aborts, when the loop exits early (`break`, `return`, a throw),
-   * and — for every event but `disconnected` — when the client disconnects.
-   * An abort stops listening at once and discards whatever is buffered.
+   * missed. The buffer is unbounded: an iterator that is not consumed as fast
+   * as events arrive holds every one of them in memory until it is read, so
+   * stop iterating (or abort `signal`) when you stop reading. Voice is the
+   * exception: at most 256 `voiceData` frames are buffered, and the rest are
+   * dropped, as for a listener that falls behind.
+   *
+   * Iteration ends when the loop exits early (`break`, `return`, a throw), and
+   * — for every event but `disconnected` — when the client disconnects. When
+   * `signal` aborts, listening stops at once, whatever is buffered is
+   * discarded, and the pending and every later `next()` reject with the
+   * signal's reason, as `events.on` in Node does.
+   *
+   * `next()` may be called again before an earlier call has settled; the calls
+   * are answered in order.
    */
   events<K extends keyof EventMap>(
     event: K,
@@ -696,55 +846,72 @@ export class Client implements CommandExecutor, AsyncDisposable {
   ): AsyncIterableIterator<EventMap[K]> {
     const { signal } = options;
     const buffered: Array<EventMap[K]> = [];
-    let wake: (() => void) | undefined;
+    // The next() calls waiting for an event, oldest first.
+    const waiting: Array<{
+      resolve: (result: IteratorResult<EventMap[K]>) => void;
+      reject: (reason: unknown) => void;
+    }> = [];
     let ended = false;
+    let aborted = false;
+
+    const finishWaiting = (): void => {
+      for (const waiter of waiting.splice(0)) {
+        waiter.resolve({ value: undefined, done: true });
+      }
+    };
 
     const stopListening = this.on(event, ((payload: EventMap[K]) => {
       if (ended) return;
+      const waiter = waiting.shift();
+      if (waiter) {
+        waiter.resolve({ value: payload, done: false });
+        return;
+      }
       if (event === "voiceData" && buffered.length >= MAX_PENDING_DELIVERIES) {
         this.#dropVoice();
         return;
       }
       buffered.push(payload);
-      wake?.();
     }) as Listener<K>);
     // Ends after what is already buffered, which arrived before the disconnect.
     const stopOnDisconnect =
       event === "disconnected"
         ? undefined
         : this.on("disconnected", () => {
-            ended = true;
-            stopListening();
-            wake?.();
+            cleanup();
+            finishWaiting();
           });
     const cleanup = (): void => {
       ended = true;
       stopListening();
       stopOnDisconnect?.();
       signal?.removeEventListener("abort", abort);
-      wake?.();
     };
     const abort = (): void => {
+      aborted = true;
       buffered.length = 0;
       cleanup();
+      const reason = abortReason(signal!);
+      for (const waiter of waiting.splice(0)) waiter.reject(reason);
     };
     if (signal?.aborted) abort();
     else signal?.addEventListener("abort", abort, { once: true });
 
     const iterator: AsyncIterableIterator<EventMap[K]> = {
-      async next(): Promise<IteratorResult<EventMap[K]>> {
-        while (buffered.length === 0 && !ended) {
-          await new Promise<void>((resolve) => (wake = resolve));
-          wake = undefined;
+      next(): Promise<IteratorResult<EventMap[K]>> {
+        if (aborted) return Promise.reject(abortReason(signal!));
+        if (buffered.length > 0) return Promise.resolve({ value: buffered.shift()!, done: false });
+        if (ended) {
+          cleanup();
+          return Promise.resolve({ value: undefined, done: true });
         }
-        if (buffered.length > 0) return { value: buffered.shift()!, done: false };
-        cleanup();
-        return { value: undefined, done: true };
+        return new Promise((resolve, reject) => waiting.push({ resolve, reject }));
       },
-      async return(): Promise<IteratorResult<EventMap[K]>> {
+      return(): Promise<IteratorResult<EventMap[K]>> {
         buffered.length = 0;
         cleanup();
-        return { value: undefined, done: true };
+        finishWaiting();
+        return Promise.resolve({ value: undefined, done: true });
       },
       [Symbol.asyncIterator]() {
         return iterator;
@@ -814,7 +981,7 @@ export class Client implements CommandExecutor, AsyncDisposable {
     host: string,
     info: FileUploadInfo,
     data: Readable,
-    options: { readonly signal?: AbortSignal | undefined } = {},
+    options: Pick<FileTransferOptions, "signal" | "trace"> = {},
   ): Promise<void> {
     return uploadFileData(host, info, data, {
       ...options,
@@ -830,7 +997,7 @@ export class Client implements CommandExecutor, AsyncDisposable {
     host: string,
     info: FileDownloadInfo,
     dest: Writable,
-    options: { readonly signal?: AbortSignal | undefined } = {},
+    options: Pick<FileTransferOptions, "signal" | "trace"> = {},
   ): Promise<void> {
     return downloadFileData(host, info, dest, {
       ...options,
@@ -840,15 +1007,125 @@ export class Client implements CommandExecutor, AsyncDisposable {
 
   // ---- Internal (package-visible) ------------------------------------------
 
-  #markConnected(): void {
+  #markConnected(initServer: Readonly<Record<string, string>> = {}): void {
     // Only the attempt in progress can complete: never one that disconnect()
     // or a failure has already ended.
     if (this.#status !== ClientStatus.Connecting || this.#attempt.settled) return;
     this.#status = ClientStatus.Connected;
+    // Settled before the hook runs, so that nothing it does can turn this
+    // attempt into a failed one; connect() resumes only after the hook returns.
     this.#attempt.resolve();
+    const trace = this.#attempt.trace;
+    if (trace !== undefined) {
+      trace.sessionStarted = true;
+      this.#session = {
+        clientID: asClientID(this.#clid),
+        startedAt: performance.now(),
+        attempt: trace.attempt,
+        reconnect: trace.reconnect,
+      };
+      this.#callHook(this.#trace?.sessionStart, () => {
+        const safe: Record<string, string> = {};
+        for (const [key, value] of Object.entries(initServer)) {
+          if (!SECRET_INITSERVER_PARAMS.has(key)) safe[key] = value;
+        }
+        const talkPower = Number.parseInt(initServer["client_talk_power"] ?? "", 10);
+        return {
+          attempt: trace.attempt,
+          reconnect: trace.reconnect,
+          clientID: asClientID(this.#clid),
+          nickname: initServer["acn"] ?? this.#nickname,
+          talkPower: Number.isNaN(talkPower) ? 0 : talkPower,
+          initServer: Object.freeze(safe),
+          capabilities: this.#capabilities,
+          durationMs: performance.now() - trace.connectStartedAt,
+        };
+      });
+    }
     this.#emit("connected", undefined);
   }
 
+  /** The socket is open: the attempt's handshake begins. */
+  #markConnectDone(socket: DatagramSocket): void {
+    const trace = this.#attempt.trace;
+    if (trace === undefined || this.#attempt.settled || trace.phase !== ConnectPhase.Open) return;
+    trace.phase = ConnectPhase.Handshake;
+    this.#callHook(this.#trace?.connectDone, () => {
+      let localAddr = "";
+      try {
+        const local = socket.address?.();
+        if (local !== undefined) localAddr = joinHostPort(local.address, String(local.port));
+      } catch {
+        // A socket that cannot say where it is bound has no local address to report.
+      }
+      return {
+        attempt: trace.attempt,
+        reconnect: trace.reconnect,
+        target: trace.target,
+        localAddr,
+        durationMs: performance.now() - trace.connectStartedAt,
+      };
+    });
+  }
+
+  #markHandshakeDone(serverPublicKey = ""): void {
+    const trace = this.#attempt.trace;
+    if (trace === undefined || this.#attempt.settled || trace.phase !== ConnectPhase.Handshake) {
+      return;
+    }
+    trace.phase = ConnectPhase.Join;
+    this.#callHook(this.#trace?.handshakeDone, () => {
+      const puzzle = puzzleOf(this.#crypt);
+      return {
+        attempt: trace.attempt,
+        reconnect: trace.reconnect,
+        durationMs: performance.now() - trace.connectStartedAt,
+        puzzleLevel: puzzle.level,
+        puzzleDurationMs: puzzle.durationMs,
+        // The handler is this attempt's own, so its count starts at the socket.
+        resends: this.#handler.resends,
+        serverPublicKey,
+      };
+    });
+  }
+
+  #markWelcomeDone(): void {
+    const trace = this.#attempt.trace;
+    if (trace === undefined || !trace.sessionStarted || trace.welcomeDone) return;
+    if (this.#status !== ClientStatus.Connected) return;
+    trace.welcomeDone = true;
+    this.#callHook(this.#trace?.welcomeDone, () => ({
+      attempt: trace.attempt,
+      reconnect: trace.reconnect,
+      channelID: this.channelID,
+      channels: trace.channels,
+      clients: this.#clients.size,
+      durationMs: performance.now() - trace.connectStartedAt,
+    }));
+  }
+
+  /** Report the end of the session in progress, once. */
+  #endSession(error: unknown): void {
+    const session = this.#session;
+    if (session === undefined) return;
+    this.#session = undefined;
+    this.#callHook(this.#trace?.sessionEnd, () => ({
+      clientID: session.clientID,
+      error,
+      durationMs: performance.now() - session.startedAt,
+      attempt: session.attempt,
+      reconnect: session.reconnect,
+    }));
+  }
+
+  /**
+   * Call a trace hook, if there is one, and never let it touch the
+   * connection: see callHook. The info is built only when there is a hook.
+   */
+  #callHook<I>(hook: ((info: I) => unknown) | undefined, info: () => I): void {
+    callHook(hook, this.#trace, info);
+  }
+
   // ---- Private -------------------------------------------------------------
 
   #newHandler(): PacketHandler {
@@ -862,6 +1139,9 @@ export class Client implements CommandExecutor, AsyncDisposable {
     handler.onClosed = (err) => {
       if (handler === this.#handler) this.#handleConnectionClosed(err);
     };
+    handler.onOpen = (socket) => {
+      if (handler === this.#handler) this.#markConnectDone(socket);
+    };
     handler.onReceiveError = (error) => {
       if (handler === this.#handler) this.#handleReceiveError(error);
     };
@@ -879,7 +1159,12 @@ export class Client implements CommandExecutor, AsyncDisposable {
     this.#capabilities = unknownServerCapabilities();
   }
 
-  async #resolveAddr(signal: AbortSignal): Promise<string> {
+  async #resolveAddr(signal: AbortSignal): Promise<{
+    target: string;
+    source: string;
+    candidates: readonly ResolvedAddr[];
+    error: unknown;
+  }> {
     // Parsed, not tested for a colon: an IPv6 literal has colons and no port.
     const { host, port } = splitHostPort(this.#addr);
     const fallback = joinHostPort(host, port);
@@ -899,13 +1184,20 @@ export class Client implements CommandExecutor, AsyncDisposable {
         this.#resolver.resolve(this.#addr, { signal: lookup }),
         lookup,
       );
-      return resolved[0]?.addr ?? fallback;
+      const first = resolved[0];
+      return {
+        target: first?.addr ?? fallback,
+        source: first?.source ?? "",
+        candidates: resolved,
+        error: undefined,
+      };
     } catch (error) {
       signal.throwIfAborted();
+      const reason = budget.signal.aborted ? budget.signal.reason : error;
       this.#logger.warn("address resolution failed, falling back to direct", {
-        error: String(budget.signal.aborted ? budget.signal.reason : error),
+        error: String(reason),
       });
-      return fallback;
+      return { target: fallback, source: "", candidates: [], error: reason };
     } finally {
       clearTimeout(timer);
     }
@@ -913,15 +1205,15 @@ export class Client implements CommandExecutor, AsyncDisposable {
 
   /**
    * A datagram from the server could not be handled. During the handshake that
-   * is the connection failing, reported as a CryptoInitError with the cause;
+   * is the connection failing, reported as a HandshakeError with the cause;
    * once connected, one bad packet is not worth the session, so it is dropped.
    */
   #handleReceiveError(error: unknown): void {
     if (this.#status !== ClientStatus.Connected) {
       this.#failConnection(
-        error instanceof CryptoInitError
+        error instanceof HandshakeError
           ? error
-          : new CryptoInitError("the handshake failed on a malformed packet", { cause: error }),
+          : new HandshakeError("the handshake failed on a malformed packet", { cause: error }),
       );
       return;
     }
@@ -1017,9 +1309,25 @@ export class Client implements CommandExecutor, AsyncDisposable {
     // which is how a channellist could come back with duplicate and empty rows.
     if (cmd.name === "channellistfinished") {
       this.#cmdTrack.signalWelcomeComplete();
+      this.#markWelcomeDone();
       return;
     }
 
+    if (cmd.name === "channellist") {
+      const trace = this.#attempt.trace;
+      if (trace !== undefined && !trace.welcomeDone) trace.channels++;
+    }
+
+    // The server answers our goodbye by announcing that we left, not with an
+    // error line; that announcement is what disconnect() waits for.
+    if (
+      cmd.name === "notifyclientleftview" &&
+      this.#goodbyeAnswered !== undefined &&
+      cmd.params["clid"] === String(this.#clid)
+    ) {
+      this.#goodbyeAnswered();
+    }
+
     if (cmd.name.startsWith("notify")) {
       // Some commands are answered by a notification instead of data rows;
       // it still goes on to be dispatched as an event, since the same
@@ -1174,7 +1482,7 @@ export class Client implements CommandExecutor, AsyncDisposable {
    */
   #dropVoice(): void {
     this.#voiceDropped++;
-    const now = Date.now();
+    const now = performance.now();
     if (now - this.#voiceDropWarnedAt < VOICE_DROP_WARN_INTERVAL_MS) return;
     this.#voiceDropWarnedAt = now;
     // The count since the last warning, so each one says how bad it is now.
@@ -1272,6 +1580,7 @@ export class Client implements CommandExecutor, AsyncDisposable {
     // Never undefined for a drop: undefined means disconnect() only.
     const cause = err ?? new TeamspeakError("connection closed");
     this.#lastDrop = cause;
+    this.#endSession(cause);
 
     // Announced first, then retried: a caller watching `disconnected` should
     // hear about the drop even when a reconnect is already on its way, because
@@ -1302,27 +1611,43 @@ export class Client implements CommandExecutor, AsyncDisposable {
 
     const stop = new AbortController();
     this.#stopReconnecting = stop;
+    // The attempts the loop has made, and why it stopped, for `reconnectStopped`.
+    let made = 0;
+    let stoppedBy: { readonly cause: unknown } | undefined;
     try {
       for (let attempt = 1; policy.maxAttempts === 0 || attempt <= policy.maxAttempts; attempt++) {
-        if (this.#stopped) return;
+        if (this.#stopped) {
+          stoppedBy = { cause: undefined };
+          return;
+        }
         let retry: boolean;
         try {
           retry = shouldRetry(err, attempt);
         } catch (error) {
           this.#logger.error("shouldRetry threw; not reconnecting", { error: String(error) });
+          stoppedBy = { cause: err };
           return;
         }
         if (!retry) {
           this.#logger.info("not retrying", { attempt, reason: err.message });
+          stoppedBy = { cause: err };
           return;
         }
 
         const delay = backoffDelay(policy, attempt);
         this.#logger.info("reconnecting", { attempt, delayMs: delay });
+        this.#callHook(this.#trace?.reconnectScheduled, () => ({
+          attempt,
+          delayMs: delay,
+          cause: err,
+        }));
         // A timer that keeps the process alive: an application that does
         // nothing but stay connected would otherwise exit during the wait.
         await sleep(delay, stop.signal);
-        if (this.#stopped) return;
+        if (this.#stopped) {
+          stoppedBy = { cause: undefined };
+          return;
+        }
         // Connected, or connecting, by hand during the wait: nothing is left to
         // retry, and an attempt now would only fail with AlreadyConnectedError.
         if (this.#status !== ClientStatus.Disconnected) {
@@ -1331,7 +1656,12 @@ export class Client implements CommandExecutor, AsyncDisposable {
         }
 
         try {
-          await this.connect({ signal: AbortSignal.timeout(RECONNECT_ATTEMPT_TIMEOUT_MS) });
+          made++;
+          await this.#connect(
+            { signal: AbortSignal.timeout(RECONNECT_ATTEMPT_TIMEOUT_MS) },
+            attempt,
+            true,
+          );
           // Read afresh: the status may have changed while connect() resolved.
           if (this.status === ClientStatus.Connected) {
             this.#logger.info("reconnected", { attempt });
@@ -1343,11 +1673,19 @@ export class Client implements CommandExecutor, AsyncDisposable {
           err = this.#lastDrop ?? new TeamspeakError("connection closed");
         } catch (retryErr) {
           if (retryErr instanceof AlreadyConnectedError) return;
-          err = retryErr instanceof Error ? retryErr : new TeamspeakError(String(retryErr));
+          err =
+            retryErr instanceof Error
+              ? retryErr
+              : new TeamspeakError(String(retryErr), { cause: retryErr });
         }
       }
       this.#logger.warn("reconnect attempts exhausted", { attempts: policy.maxAttempts });
+      stoppedBy = { cause: err };
     } finally {
+      if (stoppedBy !== undefined) {
+        const { cause } = stoppedBy;
+        this.#callHook(this.#trace?.reconnectStopped, () => ({ attempts: made, cause }));
+      }
       this.#reconnecting = false;
       if (this.#stopReconnecting === stop) this.#stopReconnecting = undefined;
     }
@@ -1371,7 +1709,7 @@ export class Client implements CommandExecutor, AsyncDisposable {
     this.#status = ClientStatus.Disconnected;
     this.#handler.close();
     void this.#announceDisconnected(
-      error instanceof Error ? error : new TeamspeakError(String(error)),
+      error instanceof Error ? error : new TeamspeakError(String(error), { cause: error }),
     );
   }
 }