@honeybbq/teamspeak 0.0.1 → 1.0.0-beta.10

package/dist/client/client.js

@@ -0,0 +1,1634 @@
+import {} from "./types.js";
+import { ConnectPhase } from "./trace.js";
+import { callHook } from "./hooks.js";
+import { puzzleOf } from "./handshake/crypt-handshake.js";
+import { asChannelID, asClientID, AlreadyConnectedError, backoffDelay, ClientStatus, ErrorCode, Reason, TeamspeakError, noopLogger, } from "@honeybbq/teamspeak";
+import { HandshakeError, RemovedError } from "./errors.js";
+import { abortable, abortReason } from "./abort.js";
+import { Crypt } from "./crypto/index.js";
+import { RESOLVE_BUDGET_MS, Resolver } from "./discovery/resolver.js";
+import { PacketHandler } from "./transport/handler.js";
+import { PacketType } from "./transport/packet.js";
+import { CommandTracker, appendReturnCode } from "./commands.js";
+import { buildCommand, buildCommandChain, encodeRequest, parseServerError, resolveBackoffPolicy, } from "../core/internal.js";
+import { uploadFileData, downloadFileData } from "./transfer.js";
+import { buildSetConnectionInfo } from "./connection-info.js";
+import { buildEventChain } from "./events.js";
+import { processInit1 } from "./handshake/crypt-handshake.js";
+import { handleHandshakeInitIV, handleHandshakeExpand2, defaultClientVersion, handleInitServer, prepareClientPassword, } from "./handshake.js";
+import { handleNotification } from "../core/internal.js";
+import { parseCommand } from "../core/internal.js";
+import { CommandThrottle } from "./throttle.js";
+import { splitCommandRows, sleep } from "../core/internal.js";
+import { isAutoNicknameMatch } from "./helpers.js";
+import { CommandTimeoutError, NotConnectedError } from "@honeybbq/teamspeak";
+import { responseSpec } from "../core/internal.js";
+import { unknownServerCapabilities } from "./capabilities.js";
+import { joinHostPort, parseConnectAddress, splitHostPort } from "./address.js";
+import { commandChannel, incomingChannel } from "./diagnostics.js";
+import { defaultShouldRetry } from "./reconnect.js";
+/** The signature is Ed25519, 64 bytes; the server verifies it, so only its shape is checked. */
+function normalizeClientVersion(version) {
+    if (version === undefined)
+        return defaultClientVersion;
+    const { platform, version: text, sign } = version;
+    for (const [name, value] of [
+        ["platform", platform],
+        ["version", text],
+        ["sign", sign],
+    ]) {
+        if (typeof value !== "string" || value === "") {
+            throw new TypeError(`a client version's ${name} is a non-empty string`);
+        }
+    }
+    const raw = Buffer.from(sign, "base64");
+    if (raw.length !== 64 || raw.toString("base64") !== sign) {
+        throw new RangeError("a client version's sign is the base64 of a 64-byte signature");
+    }
+    return { platform, version: text, sign };
+}
+function normalizeClientInitOptions(options) {
+    return {
+        serverPasswordHash: prepareClientPassword(options.serverPassword ?? ""),
+        defaultChannel: options.defaultChannel ?? "",
+        defaultChannelPasswordHash: prepareClientPassword(options.defaultChannelPassword ?? ""),
+        privilegeKey: options.privilegeKey ?? "",
+        metaData: options.metaData ?? "",
+        version: normalizeClientVersion(options.version),
+    };
+}
+let internalsOf;
+let sentLineHook;
+/**
+ * Observe every command line the client sends, as encoded. A seam for the
+ * package's own tests; not exported from the package.
+ *
+ * @internal
+ */
+export function onSentLine(hook) {
+    sentLineHook = hook;
+}
+/** @internal The internals of `client`. */
+export function clientInternals(client) {
+    return internalsOf(client);
+}
+/** How long a command waits for its answer unless told otherwise. */
+const DEFAULT_COMMAND_TIMEOUT_MS = 10_000;
+/**
+ * How long `disconnect()` waits for the server to acknowledge its goodbye
+ * unless told otherwise: the acknowledgement is a courtesy, and a connection
+ * that has already died would otherwise hold it for a full command timeout.
+ */
+const DISCONNECT_TIMEOUT_MS = 1_000;
+/** How long each reconnection attempt may take. */
+const RECONNECT_ATTEMPT_TIMEOUT_MS = 30_000;
+/** The `initserver` parameters a trace never sees, because they could carry a secret. */
+const SECRET_INITSERVER_PARAMS = new Set([
+    "client_server_password",
+    "client_default_channel_password",
+    "client_default_token",
+    "client_key_offset",
+]);
+function newConnectAttempt() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    // The failure is reported to whoever awaits connect(); an attempt nobody
+    // awaits any more must not surface as an unhandled rejection.
+    promise.catch(() => { });
+    const controller = new AbortController();
+    const attempt = {
+        promise,
+        signal: controller.signal,
+        settled: false,
+        trace: undefined,
+        onFail: undefined,
+        resolve() {
+            if (attempt.settled)
+                return;
+            attempt.settled = true;
+            resolve();
+        },
+        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));
+        },
+    };
+    return attempt;
+}
+/**
+ * Voice deliveries are dropped while more than this many deliveries of any
+ * kind are waiting: audio is fifty packets a second per speaker, and a
+ * listener that cannot keep up would otherwise queue it without bound.
+ */
+const MAX_PENDING_DELIVERIES = 256;
+/** How often dropped voice is reported, at most. */
+const VOICE_DROP_WARN_INTERVAL_MS = 10_000;
+/** The only commands handled before crypto init completes. */
+const PRE_INIT_COMMANDS = new Set(["clientinitiv", "initivexpand2", "error"]);
+/**
+ * A TeamSpeak client over the voice protocol.
+ *
+ * Listeners run one at a time, in the order their events arrived, after the
+ * packet that carried them has been handled, so a listener may call the client
+ * and await an answer.
+ */
+export class Client {
+    static {
+        internalsOf = (client) => client.#internals;
+    }
+    #crypt;
+    #handler;
+    #logger;
+    #nickname;
+    #clid = 0;
+    /**
+     * What the server reported about itself in initserver, including the UID
+     * hash it uses: TS3 hashes the public key with SHA-1 and TS6 with SHA-256.
+     */
+    #capabilities = unknownServerCapabilities();
+    #internals;
+    #identity;
+    #addr;
+    #resolver;
+    #clientInitOptions;
+    #socketFactory;
+    #fileTransferSocketFactory;
+    /** A copy of the caller's trace, so changing theirs later changes nothing. */
+    #trace;
+    /** The session in progress, for its `sessionEnd`; cleared when that has been reported. */
+    #session;
+    /** Undefined when the client does not reconnect. */
+    #reconnectOptions;
+    /**
+     * Set while a reconnect attempt is in flight, so overlapping failures do not
+     * start competing loops.
+     */
+    #reconnecting = false;
+    /** The reconnect loop's latest attempt; 0 while it has made none. */
+    #loopAttempt = 0;
+    /** The last answer of `shouldRetry`, so that one failure asks it once. */
+    #retryAnswer;
+    /**
+     * Why the last established session dropped: a reconnect loop whose own
+     * attempt connected and then dropped before the loop resumed retries for it.
+     */
+    #lastDrop;
+    /** Set by an explicit disconnect(), which must never be undone by a retry. */
+    #stopped = false;
+    /**
+     * The goodbye of a disconnect() still in progress, which a connect() waits
+     * for: tearing the old session down after a new one has started would end
+     * the new one instead.
+     */
+    #leaving;
+    /** Ends a disconnect()'s wait for its goodbye to be answered, while it waits. */
+    #goodbyeAnswered;
+    /** How many times disconnect() was called, so a waiting connect() sees one. */
+    #disconnects = 0;
+    /**
+     * Settles once the last queued `disconnected` has been delivered. A
+     * connect() waits for it, so the end of one session is never heard during
+     * the next: not by a listener added for the new session, and not by an
+     * events() iterator started for it.
+     */
+    #disconnectedDelivered;
+    /** Cuts short the reconnect loop's wait, on disconnect(). */
+    #stopReconnecting;
+    #status = ClientStatus.Disconnected;
+    #throttle = new CommandThrottle();
+    #cmdTrack = new CommandTracker(() => this.#clid);
+    #clients = new Map();
+    #attempt = newConnectAttempt();
+    #listeners = new Map();
+    /** Deliveries waiting for their turn; see #emit. */
+    #queue = [];
+    #draining = false;
+    #voiceDropped = 0;
+    #voiceDropWarnedAt = -Infinity;
+    #eventMiddlewares;
+    #send;
+    #eventChain;
+    constructor(identity, addr, nickname, options = {}) {
+        this.#identity = identity;
+        this.#addr = addr;
+        this.#nickname = nickname;
+        this.#logger = options.logger ?? noopLogger;
+        this.#resolver = options.resolver ?? new Resolver({ nicknameLookup: options.nicknameLookup });
+        this.#clientInitOptions = normalizeClientInitOptions(options);
+        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();
+        // oxlint-disable-next-line no-this-alias -- accessors cannot be arrow functions
+        const self = this;
+        this.#internals = {
+            get crypt() {
+                return self.#crypt;
+            },
+            get handler() {
+                return self.#handler;
+            },
+            get logger() {
+                return self.#logger;
+            },
+            get initOptions() {
+                return self.#clientInitOptions;
+            },
+            get nickname() {
+                return self.#nickname;
+            },
+            set nickname(value) {
+                self.#nickname = value;
+            },
+            get clid() {
+                return self.#clid;
+            },
+            set clid(value) {
+                self.#clid = value;
+            },
+            get clients() {
+                return self.#clients;
+            },
+            get capabilities() {
+                return self.#capabilities;
+            },
+            set capabilities(value) {
+                self.#capabilities = value;
+            },
+            markConnected: (initServer) => this.#markConnected(initServer),
+            markHandshakeDone: (serverPublicKey) => this.#markHandshakeDone(serverPublicKey),
+            execNoWait: (command) => this.#execNoWait(command, undefined, true),
+            handlePacket: (packet) => this.#handlePacket(packet),
+        };
+        // Built once: the chains are read on every command and event, and
+        // changing them while those run would make the behaviour depend on timing.
+        const cmdMiddlewares = options.commandMiddleware ?? [];
+        this.#eventMiddlewares = options.eventMiddleware ?? [];
+        this.#send = buildCommandChain(cmdMiddlewares, (request, commandOptions = {}) => this.#exec(encodeRequest(request, prepareClientPassword), commandOptions, false));
+        this.#eventChain = buildEventChain([...this.#eventMiddlewares], (event) => this.#deliver(event.name, event.payload));
+    }
+    /** Where the client is in its connection's life. */
+    get status() {
+        return this.#status;
+    }
+    // ---- Connection -----------------------------------------------------------
+    /**
+     * Connect to the server. Resolves once the handshake completes.
+     *
+     * An address that cannot be one — no host, a port outside 1–65535 — rejects
+     * with an InvalidAddressError at once, before anything starts. A host name
+     * that does not resolve fails the attempt with a TeamspeakError whose
+     * `cause` is the lookup's error.
+     *
+     * A failed attempt rejects with its cause, such as the server's error for a
+     * rejected password. Aborting `signal` abandons the attempt and rejects with
+     * the signal's reason. The signal bounds only the connecting: once this
+     * resolves, the connection lasts until `disconnect()` or a drop.
+     * `connect()` does not retry; the `reconnect` option only retries a
+     * connection that drops after it was established.
+     *
+     * Called while a `disconnect()` is still saying goodbye, or while an earlier
+     * session's `disconnected` is still waiting to be delivered, this waits for
+     * that first, so the old session is closed, and its `disconnected`
+     * delivered, before the new one starts: no listener or `events()` iterator
+     * of the new session hears the old one end. A `disconnect()` called during
+     * that wait wins: this then rejects with a NotConnectedError.
+     *
+     * `connected` is delivered after this resolves, so a listener added right
+     * after `await client.connect()` still hears it.
+     */
+    async connect(options = {}) {
+        return this.#connect(options, 1, false);
+    }
+    async #connect(options, attemptNumber, reconnect) {
+        const { signal } = options;
+        signal?.throwIfAborted();
+        const disconnects = this.#disconnects;
+        if (this.#leaving !== undefined)
+            await abortable(this.#leaving, signal);
+        while (this.#disconnectedDelivered !== undefined) {
+            await abortable(this.#disconnectedDelivered, signal);
+        }
+        if (this.#disconnects !== disconnects)
+            throw new NotConnectedError();
+        if (this.#status !== ClientStatus.Disconnected)
+            throw new AlreadyConnectedError();
+        // Checked before anything changes: an address that can never work leaves
+        // the client as it was, with no attempt to announce the end of.
+        parseConnectAddress(this.#addr);
+        this.#stopped = false;
+        this.#resetForConnect();
+        this.#status = ClientStatus.Connecting;
+        const attempt = this.#attempt;
+        const trace = {
+            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
+        // connection it made rather than one it would believe had failed.
+        const onAbort = () => this.#failConnection(abortReason(signal));
+        signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+            try {
+                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()
+                // fails with AlreadyConnectedError.
+                this.#failConnection(error);
+            }
+            await attempt.promise;
+        }
+        finally {
+            signal?.removeEventListener("abort", onAbort);
+        }
+    }
+    /**
+     * Leave the server and close the connection.
+     *
+     * Says goodbye first, waiting for the server's acknowledgement for a second
+     * at most, or less if `signal` aborts sooner. The connection is closed
+     * either way. A `connect()` still waiting for its handshake rejects with a
+     * NotConnectedError, and so do the commands still waiting for an answer.
+     * Resolves once `disconnected` has been delivered to the listeners, so one
+     * added after `await client.disconnect()` does not hear it. Does nothing on
+     * a client that is not connected; called again while an earlier call is
+     * still saying goodbye, it waits for that one (and its message is the first
+     * call's).
+     *
+     * `reasonMessage` is what the server tells the other clients who see this
+     * one leave, in `clientLeave`'s `reasonMessage` (`reasonmsg` of
+     * `clientdisconnect`, sent with `reasonid=8`, `Reason.Disconnect`: measured
+     * on TeamSpeak 3 and 6, the server drops the message without it);
+     * default `"Shutdown"`.
+     */
+    async disconnect(options = {}) {
+        // Recorded before anything else: a dropped socket during the goodbye below
+        // must not be mistaken for an outage worth retrying.
+        this.#stopped = true;
+        this.#disconnects++;
+        this.#stopReconnecting?.abort();
+        if (this.#leaving !== undefined)
+            return this.#leaving;
+        // Already ended, by a drop or a failed attempt: its `disconnected` may
+        // still be on its way.
+        if (this.#status === ClientStatus.Disconnected)
+            return this.#disconnectedDelivered;
+        const wasConnected = this.#status === ClientStatus.Connected;
+        this.#status = ClientStatus.Disconnected;
+        let left;
+        this.#attempt.rejectAfter(new NotConnectedError(), new Promise((r) => (left = r)));
+        const leaving = this.#leave(wasConnected, options.signal, options.reasonMessage ?? "Shutdown").finally(left);
+        this.#leaving = leaving;
+        try {
+            await leaving;
+        }
+        finally {
+            this.#leaving = undefined;
+        }
+    }
+    async #leave(wasConnected, signal, reasonMessage) {
+        this.#logger.info("disconnecting from server");
+        if (wasConnected) {
+            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((resolve) => {
+                this.#goodbyeAnswered = () => resolve(true);
+            });
+            // On the internal path: the status already says Disconnected.
+            const answered = this.#exec(buildCommand("clientdisconnect", {
+                reasonid: String(Reason.Disconnect),
+                reasonmsg: reasonMessage,
+            }), { signal, timeoutMs: 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, false);
+    }
+    /** `await using client = …` disconnects when the scope ends. */
+    [Symbol.asyncDispose]() {
+        return this.disconnect();
+    }
+    // ---- Commands ------------------------------------------------------------
+    /**
+     * Send a raw command line and return the rows that answer it: the escape
+     * hatch for a command the typed functions do not cover. The line is sent as
+     * given, so its values must already be escaped and any channel password
+     * already hashed. `CommandName` lists the command names.
+     *
+     * Rejects with a NotConnectedError unless the client is connected: while it
+     * is still connecting, the session's keys may not exist yet.
+     */
+    // oxlint-disable-next-line typescript/array-type -- the public API report spells this `[]`; respelling it changes the report
+    exec(command, options = {}) {
+        return this.#exec(command, options, false);
+    }
+    /**
+     * Send a raw command line without waiting for an answer, for the few
+     * commands the server answers with nothing at all. `CommandName` lists
+     * the command names.
+     *
+     * Commands are paced by a flood throttle; aborting `signal` while this waits
+     * for its turn rejects with the signal's reason and sends nothing. Rejects
+     * with a NotConnectedError unless the client is connected.
+     */
+    execNoWait(command, options = {}) {
+        return this.#execNoWait(command, options.signal, false);
+    }
+    /**
+     * Whether a command may go out now. The handshake's own commands (`internal`)
+     * need only an open socket; everything else needs a connected session, so
+     * nothing a caller sends can go out under the public dummy key, or after
+     * disconnect() has begun saying goodbye.
+     */
+    #canSend(internal) {
+        return this.#handler.isOpen && (internal || this.#status === ClientStatus.Connected);
+    }
+    async #execNoWait(command, signal, internal) {
+        signal?.throwIfAborted();
+        if (!this.#canSend(internal))
+            throw new NotConnectedError();
+        await this.#throttle.wait(signal);
+        if (!this.#canSend(internal))
+            throw new NotConnectedError();
+        this.#sendLine(command);
+    }
+    /**
+     * Send a typed command; this is the CommandExecutor the typed commands run on.
+     *
+     * The request passes through the `commandMiddleware` first. Channel
+     * passwords are then hashed, because that is this protocol's rule: the voice
+     * protocol expects `base64(sha1(password))`, where ServerQuery takes the
+     * password itself.
+     */
+    // oxlint-disable-next-line typescript/array-type -- the public API report spells this `[]`; respelling it changes the report
+    send(request, options = {}) {
+        return this.#send(request, options);
+    }
+    #sendLine(line) {
+        const hook = sentLineHook;
+        if (hook)
+            hook(this, line);
+        this.#handler.sendPacket(PacketType.Command, Buffer.from(line), 0);
+    }
+    #exec(command, options, internal) {
+        if (!commandChannel.hasSubscribers)
+            return this.#execUntraced(command, options, internal);
+        const trace = { command: parseCommand(command)?.name ?? "", client: this };
+        return commandChannel.tracePromise(() => this.#execUntraced(command, options, internal), trace);
+    }
+    async #execUntraced(command, options, internal) {
+        const { signal, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS } = options;
+        signal?.throwIfAborted();
+        // A command sent on no socket used to vanish and surface 10 seconds later
+        // as a timeout, which reads like a slow server rather than a usage error.
+        if (!this.#canSend(internal))
+            throw new NotConnectedError();
+        // Which notifications answer this command, and — for answers that arrive
+        // after the `error` — the request field they echo back.
+        const parsed = parseCommand(command);
+        const spec = responseSpec(parsed?.name ?? "");
+        const key = spec?.correlated?.key;
+        const correlation = key === undefined ? undefined : parsed?.params[key];
+        const echo = spec?.echoKey === undefined ? undefined : parsed?.params[spec.echoKey];
+        const [rc, answered] = this.#cmdTrack.register(spec, correlation, echo);
+        let timer;
+        let onAbort;
+        // Started before the throttle: the timeout bounds the whole command, its
+        // wait for a turn included, and so does the signal.
+        const givenUp = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new CommandTimeoutError(parsed?.name ?? "")), timeoutMs);
+            onAbort = () => reject(abortReason(signal));
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+        givenUp.catch(() => { });
+        const throttleAbort = new AbortController();
+        try {
+            const withRc = appendReturnCode(command, rc);
+            await Promise.race([this.#throttle.wait(throttleAbort.signal), givenUp]);
+            if (!this.#canSend(internal))
+                throw new NotConnectedError();
+            this.#sendLine(withRc);
+            const result = await Promise.race([answered, givenUp]);
+            if (result.err)
+                throw result.err;
+            return result.data;
+        }
+        finally {
+            // A command given up while it waited for its turn gives the turn back.
+            throttleAbort.abort();
+            // Cleared, not left to fire: a pending timer keeps the process alive for
+            // the full timeout after the last command has long been answered.
+            clearTimeout(timer);
+            if (onAbort)
+                signal?.removeEventListener("abort", onAbort);
+            this.#cmdTrack.unregister(rc);
+        }
+    }
+    // ---- Events --------------------------------------------------------------
+    /**
+     * Listen for an event. Returns a function that removes the listener.
+     *
+     * The event is named by an {@link EventName} constant or by its string, and
+     * the listener's payload type follows from it:
+     *
+     * ```ts
+     * client.on(EventName.TextMessage, (message) => console.log(message.message));
+     * ```
+     *
+     * A listener that throws does not stop the others: the rest of the event's
+     * listeners, and the events after it, are still delivered, and the exception
+     * is rethrown on its own, from a microtask, so it surfaces as an
+     * `uncaughtException` just as an EventEmitter listener's would. An async
+     * listener's rejection is not caught, and surfaces as an unhandled
+     * rejection.
+     */
+    on(event, listener) {
+        const subscription = {
+            listener: listener,
+            removed: false,
+        };
+        // A new array rather than an edit in place: a delivery may be iterating
+        // over the old one.
+        this.#listeners.set(event, [...(this.#listeners.get(event) ?? []), subscription]);
+        const unsubscribe = () => {
+            if (subscription.removed)
+                return;
+            subscription.removed = true;
+            const list = this.#listeners.get(event) ?? [];
+            this.#listeners.set(event, list.filter((s) => s !== subscription));
+        };
+        return Object.assign(unsubscribe, { [Symbol.dispose]: unsubscribe });
+    }
+    /** Listen for the next occurrence of an event only. */
+    once(event, listener) {
+        const unsubscribe = this.on(event, ((payload) => {
+            unsubscribe();
+            listener(payload);
+        }));
+        return unsubscribe;
+    }
+    /**
+     * An event as an async iterator, for `for await`:
+     *
+     * ```ts
+     * for await (const message of client.events("textMessage", { signal })) { … }
+     * ```
+     *
+     * Events that arrive while the loop body runs are buffered, so none is
+     * 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(event, options = {}) {
+        const { signal } = options;
+        const buffered = [];
+        // The next() calls waiting for an event, oldest first.
+        const waiting = [];
+        let ended = false;
+        let aborted = false;
+        const finishWaiting = () => {
+            for (const waiter of waiting.splice(0)) {
+                waiter.resolve({ value: undefined, done: true });
+            }
+        };
+        const stopListening = this.on(event, ((payload) => {
+            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);
+        }));
+        // Ends after what is already buffered, which arrived before the disconnect.
+        const stopOnDisconnect = event === "disconnected"
+            ? undefined
+            : this.on("disconnected", () => {
+                cleanup();
+                finishWaiting();
+            });
+        const cleanup = () => {
+            ended = true;
+            stopListening();
+            stopOnDisconnect?.();
+            signal?.removeEventListener("abort", abort);
+        };
+        const abort = () => {
+            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 = {
+            next() {
+                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 });
+                }
+                return new Promise((resolve, reject) => waiting.push({ resolve, reject }));
+            },
+            return() {
+                buffered.length = 0;
+                cleanup();
+                finishWaiting();
+                return Promise.resolve({ value: undefined, done: true });
+            },
+            [Symbol.asyncIterator]() {
+                return iterator;
+            },
+        };
+        return iterator;
+    }
+    // ---- API shorthand -------------------------------------------------------
+    /** This client's id on the server, assigned in the handshake; 0 before it. */
+    get clientID() {
+        return asClientID(this.#clid);
+    }
+    /**
+     * What the connected server is: version, generation, and the uid hash it
+     * uses. Read from `initserver`; before connecting the family is `unknown`
+     * and the uid hash SHA-1.
+     */
+    get serverCapabilities() {
+        return this.#capabilities;
+    }
+    /**
+     * Our own `client_unique_identifier`, hashed with the algorithm the connected
+     * server uses.
+     *
+     * TS3 uses SHA-1 and TS6 SHA-256, so this reads the algorithm learned during
+     * initserver rather than assuming one. Comparing a hard-coded SHA-1 UID to a
+     * TS6 server silently never matches.
+     */
+    get uid() {
+        return this.#identity.uid(this.#capabilities.uidAlgorithm);
+    }
+    /**
+     * The host this client connects to, as it was given, without the port: where
+     * the file transfer port is, for `uploadFileData` and the avatar and icon
+     * helpers.
+     */
+    get host() {
+        return splitHostPort(this.#addr).host;
+    }
+    /** The channel this client is in, as it last learned; 0 before connecting. */
+    get channelID() {
+        return this.#clients.get(this.#clid)?.channelID ?? asChannelID(0n);
+    }
+    /**
+     * Send Opus voice directly to clients, to channels, or to both: the
+     * packet's direct form. Throws a NotConnectedError unless the client is
+     * connected, and a RangeError for no target at all, more than 32 clients,
+     * more than 255 channels, or an id the packet cannot hold. Whether a target
+     * hears it is the server's decision, from `i_client_whisper_power` against
+     * the target's `i_client_needed_whisper_power`.
+     */
+    sendWhisper(data, targets, codec) {
+        if (!this.#canSend(false))
+            throw new NotConnectedError();
+        this.#handler.sendWhisperPacket(data, [...(targets.clients ?? [])], codec, [
+            ...(targets.channels ?? []),
+        ]);
+    }
+    /**
+     * Send Opus voice to a group of clients: a server group, a channel group,
+     * the channel commanders or everyone, within the channels the target's
+     * `scope` picks. The packet's group form; `sendWhisper` is the direct one.
+     * Throws a NotConnectedError unless the client is connected, and a
+     * RangeError for a type, scope or group id the packet cannot hold. Whether
+     * a client hears it is the server's decision, as for `sendWhisper`.
+     */
+    sendGroupWhisper(data, target, codec) {
+        if (!this.#canSend(false))
+            throw new NotConnectedError();
+        const id = "group" in target ? target.group : 0n;
+        this.#handler.sendGroupWhisperPacket(data, target.type, target.scope, id, codec);
+    }
+    /**
+     * Send one encoded audio frame to the channel this client is in. Throws a
+     * NotConnectedError unless the client is connected.
+     */
+    sendVoice(data, codec, options) {
+        // Reserved: VoiceOptions has no fields to read yet.
+        void options;
+        if (!this.#canSend(false))
+            throw new NotConnectedError();
+        this.#handler.sendVoicePacket(data, codec);
+    }
+    // ---- File Transfer -------------------------------------------------------
+    /**
+     * Upload `data` over a negotiated transfer, through the client's
+     * `fileTransferSocketFactory` if it has one.
+     */
+    uploadFileData(host, info, data, options = {}) {
+        return uploadFileData(host, info, data, {
+            ...options,
+            socketFactory: this.#fileTransferSocketFactory,
+        });
+    }
+    /**
+     * Download a negotiated transfer into `dest`, through the client's
+     * `fileTransferSocketFactory` if it has one.
+     */
+    downloadFileData(host, info, dest, options = {}) {
+        return downloadFileData(host, info, dest, {
+            ...options,
+            socketFactory: this.#fileTransferSocketFactory,
+        });
+    }
+    // ---- Internal (package-visible) ------------------------------------------
+    #markConnected(initServer = {}) {
+        // 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;
+        // A privilege key is spent by the join that used it: a reconnection must
+        // not present it again.
+        if (this.#clientInitOptions.privilegeKey !== "") {
+            this.#clientInitOptions = { ...this.#clientInitOptions, privilegeKey: "" };
+        }
+        // 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 = {};
+                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", { reconnected: trace?.reconnect ?? false });
+    }
+    /** The socket is open: the attempt's handshake begins. */
+    #markConnectDone(socket) {
+        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 = "") {
+        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() {
+        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) {
+        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(hook, info) {
+        callHook(hook, this.#trace, info);
+    }
+    // ---- Private -------------------------------------------------------------
+    #newHandler() {
+        const handler = new PacketHandler(this.#crypt, this.#logger, this.#socketFactory);
+        // Each callback checks that its handler is still the current one: a
+        // packet or close reported late by one a later connect() already replaced
+        // must not reach, or tear down, the new connection.
+        handler.onPacket = (p) => {
+            if (handler === this.#handler)
+                this.#handlePacket(p);
+        };
+        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);
+        };
+        return handler;
+    }
+    #resetForConnect() {
+        this.#handler.close();
+        this.#crypt = new Crypt(this.#identity);
+        this.#handler = this.#newHandler();
+        this.#attempt = newConnectAttempt();
+        this.#cmdTrack.reset(new NotConnectedError());
+        this.#clients.clear();
+        this.#clid = 0;
+        this.#capabilities = unknownServerCapabilities();
+    }
+    async #resolveAddr(signal) {
+        // 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);
+        // Every resolver, a custom one too, gets the same budget: past it the
+        // address is used as given. A timer the tests can control, not
+        // AbortSignal.timeout().
+        const budget = new AbortController();
+        const timer = setTimeout(() => budget.abort(new TeamspeakError("address resolution took too long")), RESOLVE_BUDGET_MS);
+        const lookup = AbortSignal.any([signal, budget.signal]);
+        try {
+            // Raced against the signal: a resolver that ignores it must still not
+            // hold up an attempt that has been given up.
+            const resolved = await abortable(this.#resolver.resolve(this.#addr, { signal: lookup }), lookup);
+            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(reason),
+            });
+            return { target: fallback, source: "", candidates: [], error: reason };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * A datagram from the server could not be handled. During the handshake that
+     * 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) {
+        if (this.#status !== ClientStatus.Connected) {
+            this.#failConnection(error instanceof HandshakeError
+                ? error
+                : new HandshakeError("the handshake failed on a malformed packet", { cause: error }));
+            return;
+        }
+        this.#logger.debug("dropped a malformed packet", { error: String(error) });
+    }
+    #handlePacket(p) {
+        const pType = p.typeFlagged & 0x0f;
+        if (pType === 8 /* Init1 */) {
+            if (this.#crypt.cryptoInitComplete)
+                return;
+            const response = processInit1(this.#crypt, p.data);
+            if (response) {
+                this.#handler.sendPacket(PacketType.Init1, response, 0);
+            }
+            return;
+        }
+        if ((pType === 0 /* Voice */ || pType === 1) /* VoiceWhisper */ && p.data.length > 5) {
+            this.#handleVoicePacket(p.data);
+            return;
+        }
+        if ((pType === 2 /* Command */ || pType === 3) /* CommandLow */ && p.data.length > 0) {
+            this.#handleCommandLines(Buffer.from(p.data).toString("utf8"));
+        }
+    }
+    /**
+     * Parse an incoming S2C voice packet.
+     * Format: [VId: u16] [CId: u16] [Codec: u8] [Data: var]
+     */
+    #handleVoicePacket(payload) {
+        // Audio arrives fifty times a second per speaker; build no event nobody
+        // will see.
+        if (!this.#listeners.get("voiceData")?.length && this.#eventMiddlewares.length === 0)
+            return;
+        if (this.#queue.length > MAX_PENDING_DELIVERIES) {
+            this.#dropVoice();
+            return;
+        }
+        const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+        const clientId = view.getUint16(2, false);
+        if (clientId === this.#clid)
+            return;
+        // Copied: the packet's buffer is reused once this returns, and a listener
+        // runs later.
+        const data = payload.slice(5);
+        this.#emitServerEvent({
+            name: "voiceData",
+            payload: { clientID: asClientID(clientId), codec: payload[4], data },
+        });
+    }
+    #handleCommandLines(s) {
+        if (!s)
+            return;
+        const lines = s.split("\0").join("\n").split("\n");
+        for (const line of lines) {
+            const trimmed = line.replace(/\r$/, "");
+            if (!trimmed)
+                continue;
+            for (const row of splitCommandRows(trimmed)) {
+                this.#handleCommandStr(row);
+            }
+        }
+    }
+    #handleCommandStr(s) {
+        const cmd = parseCommand(s);
+        if (!cmd)
+            return;
+        // Before crypto init a packet needs only the public dummy key, so anyone
+        // on the path could have sent it: nothing but the handshake's own steps,
+        // and an error that may end the attempt, is taken then. A notification
+        // would be a forged event, a row a forged answer.
+        if (!this.#crypt.cryptoInitComplete && !PRE_INIT_COMMANDS.has(cmd.name)) {
+            this.#logger.debug("dropped a command that arrived before crypto init", {
+                command: cmd.name,
+            });
+            return;
+        }
+        if (incomingChannel.hasSubscribers)
+            incomingChannel.publish({ command: cmd.name, client: this });
+        // No name means a response row: the server sends data without echoing the
+        // command, so the row belongs to whichever command is awaiting a result.
+        if (cmd.name === "") {
+            if (Object.keys(cmd.params).length > 0)
+                this.#cmdTrack.buffer(cmd.params);
+            return;
+        }
+        // `channellistfinished` ends the server's welcome sequence. It carries no
+        // data of its own, so it is the only reliable marker: the guard used to
+        // trip on our own notifycliententerview, which the server sends *in the
+        // middle* of the sequence — the channellist rows after it were then
+        // buffered as if they were the response to the caller's first command,
+        // 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
+            // notification also arrives unprompted.
+            if (this.#cmdTrack.expects(cmd.name)) {
+                this.#cmdTrack.buffer(cmd.params, cmd.name);
+                this.#cmdTrack.offerCorrelated(cmd.name, cmd.params);
+            }
+            if (cmd.name === "notifyconnectioninforequest")
+                this.#answerConnectionInfoRequest();
+            const result = handleNotification(cmd, this.#clid, this.#clients);
+            this.#processNotificationResult(result);
+            if (this.#listeners.get("notification")?.length || this.#eventMiddlewares.length > 0) {
+                this.#emitServerEvent({
+                    name: "notification",
+                    payload: { name: cmd.name, params: { ...cmd.params } },
+                });
+            }
+            return;
+        }
+        switch (cmd.name) {
+            // The handshake's steps happen once: repeated after crypto init, they
+            // could only re-key or re-announce a session that is already set up.
+            case "clientinitiv":
+                if (!this.#crypt.cryptoInitComplete)
+                    handleHandshakeInitIV(this.#internals, cmd.params);
+                break;
+            case "initivexpand2":
+                if (!this.#crypt.cryptoInitComplete)
+                    handleHandshakeExpand2(this.#internals, cmd.params);
+                break;
+            case "initserver":
+                // Only on a session with its keys: before crypto init a packet needs
+                // nothing but the public dummy key, and an initserver taken then would
+                // report a connection whose next command — clientinit with its password
+                // hashes among them — goes out under that dummy key.
+                if (this.#status === ClientStatus.Connecting && this.#crypt.cryptoInitComplete) {
+                    handleInitServer(this.#internals, cmd.params);
+                }
+                break;
+            case "error":
+                this.#handleError(cmd.params);
+                break;
+            default:
+                // A named command the SDK does not model. Held under its own name, so
+                // it answers a command only if that command declared it — not merely by
+                // arriving while one is in flight.
+                this.#cmdTrack.buffer(cmd.params, cmd.name);
+                break;
+        }
+    }
+    /**
+     * Someone asked the server for this client's connection info, and it asks
+     * us for the figures: answer with what this connection has measured. A
+     * failure is only logged, as the request is not one a caller made.
+     */
+    #answerConnectionInfoRequest() {
+        const line = buildSetConnectionInfo(this.#handler.trafficSnapshot(), this.#handler.roundTrip);
+        this.#execNoWait(line, undefined, false).catch((error) => {
+            this.#logger.debug("could not answer a connection info request", { error: String(error) });
+        });
+    }
+    #handleError(params) {
+        const { err, rc } = parseServerError(params);
+        if (rc !== null) {
+            this.#cmdTrack.resolve(rc, err);
+        }
+        else {
+            // No return_code: server is acknowledging an unsolicited command
+            // (welcome-sequence channellist, no-RC commands like clientupdate, etc.).
+            // Discard any rows buffered since the last resolved command.
+            this.#cmdTrack.discardBuffer();
+        }
+        // A server error before the welcome sequence finished is the connection
+        // failure itself — a rejected password, or an invalid clientinit parameter.
+        // Report it as the cause instead of leaving the caller with a bare timeout.
+        if (err && this.#status !== ClientStatus.Connected) {
+            this.#failConnection(err);
+            return;
+        }
+        // Only a connected session gets here, so only after crypto init: an error
+        // under the public dummy key can fail an attempt, never stop the client.
+        if (err?.code === ErrorCode.ConnectFailedBanned) {
+            this.#logger.warn("banned by the server, closing the connection");
+            setImmediate(() => {
+                this.disconnect().catch(() => { });
+            });
+        }
+    }
+    #processNotificationResult(result) {
+        switch (result.kind) {
+            case "clientEnter": {
+                const info = result.info;
+                // Identify self by the clid initserver already assigned rather than by
+                // nickname: any other client whose nickname happens to be "<our
+                // nick><digits>" — which is how the server renames a client whose
+                // nickname was taken — would otherwise be mistaken for us, poisoning
+                // every outgoing packet header with a foreign clientID until the server
+                // drops the connection for command-resend timeout.
+                //
+                // This no longer marks the end of the welcome sequence: the server
+                // sends more welcome data after it, and `channellistfinished` is the
+                // real terminator.
+                if (info.id === this.#clid) {
+                    // Carries the rename the server applied if our nickname was taken.
+                    this.#nickname = info.nickname;
+                }
+                else if (this.#clid === 0 && isAutoNicknameMatch(this.#nickname, info.nickname)) {
+                    // initserver carried no aclid, so the welcome enter is the only way
+                    // to learn our clid. Gated on clid still being unknown so a later
+                    // lookalike can never hijack an established session.
+                    this.#clid = info.id;
+                    this.#handler.setClientID(info.id);
+                    this.#nickname = info.nickname;
+                }
+                this.#emitServerEvent({ name: "clientEnter", payload: info });
+                break;
+            }
+            case "clientLeave": {
+                const event = result.event;
+                this.#emitServerEvent({ name: "clientLeave", payload: event });
+                if (!result.isSelf)
+                    break;
+                if (event.reason === Reason.KickServer || event.reason === Reason.KickServerBan) {
+                    this.#emit("kicked", kickedEvent(event));
+                }
+                this.#removedByServer(new RemovedError(event.reason, event.reasonMessage, event.invokerName));
+                break;
+            }
+            case "clientMoved":
+                this.#emitServerEvent({ name: "clientMoved", payload: result.event });
+                // A channel kick moves the client to the default channel; it arrives
+                // as a move, not as leaving view, which is where it used to be looked
+                // for.
+                if (result.event.clientID === this.#clid && result.event.reason === Reason.KickChannel) {
+                    this.#emit("kicked", kickedEvent(result.event));
+                }
+                break;
+            case "textMessage":
+                this.#emitServerEvent({ name: "textMessage", payload: result.message });
+                break;
+            case "clientUpdated":
+                // The server may rename a client, this one included.
+                if (result.event.clientID === this.#clid && "nickname" in result.event.changes) {
+                    this.#nickname = result.event.changes.nickname ?? this.#nickname;
+                }
+                this.#emitServerEvent({ name: "clientUpdated", payload: result.event });
+                break;
+            case "clientServerGroupAdded":
+                this.#emitServerEvent({ name: "clientServerGroupAdded", payload: result.event });
+                break;
+            case "clientServerGroupRemoved":
+                this.#emitServerEvent({ name: "clientServerGroupRemoved", payload: result.event });
+                break;
+            case "clientChannelGroupChanged":
+                this.#emitServerEvent({ name: "clientChannelGroupChanged", payload: result.event });
+                break;
+            case "channelCreated":
+                this.#emitServerEvent({ name: "channelCreated", payload: result.event });
+                break;
+            case "channelEdited":
+                this.#emitServerEvent({ name: "channelEdited", payload: result.event });
+                break;
+            case "channelMoved":
+                this.#emitServerEvent({ name: "channelMoved", payload: result.event });
+                break;
+            case "channelDeleted":
+                this.#emitServerEvent({ name: "channelDeleted", payload: result.event });
+                break;
+            case "channelDescriptionChanged":
+                this.#emitServerEvent({ name: "channelDescriptionChanged", payload: result.event });
+                break;
+            case "channelPasswordChanged":
+                this.#emitServerEvent({ name: "channelPasswordChanged", payload: result.event });
+                break;
+            case "serverEdited":
+                this.#emitServerEvent({ name: "serverEdited", payload: result.event });
+                break;
+            case "channelSubscribed":
+                this.#emitServerEvent({ name: "channelSubscribed", payload: result.event });
+                break;
+            case "channelUnsubscribed":
+                this.#emitServerEvent({ name: "channelUnsubscribed", payload: result.event });
+                break;
+            case "pluginCommand":
+                this.#emitServerEvent({ name: "pluginCommand", payload: result.event });
+                break;
+            case "clientChatComposing":
+                this.#emitServerEvent({ name: "clientChatComposing", payload: result.event });
+                break;
+            case "poked":
+                this.#emitServerEvent({ name: "poked", payload: result.event });
+                break;
+            case "unknown":
+                break;
+        }
+    }
+    /**
+     * End a session the server has ended. The server stops answering a client it
+     * has removed, so waiting for the transport to notice reported the end a
+     * minute late, without its cause, and with the client claiming to be
+     * connected meanwhile.
+     */
+    #removedByServer(cause) {
+        this.#handleConnectionClosed(cause);
+        this.#handler.close();
+    }
+    /**
+     * Count a dropped voice delivery, and report the drops now and then: at most
+     * once every ten seconds, with how many were dropped since the last report.
+     */
+    #dropVoice() {
+        this.#voiceDropped++;
+        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.
+        this.#logger.warn("voice dropped: listeners are not keeping up", {
+            dropped: this.#voiceDropped,
+        });
+        this.#voiceDropped = 0;
+    }
+    /** Queue a server event, through the event middleware. */
+    #emitServerEvent(event) {
+        this.#enqueue(() => this.#eventChain(event));
+    }
+    /**
+     * Queue `disconnected`; the promise settles once it has been delivered, and
+     * a connect() waits for it until then.
+     */
+    #announceDisconnected(cause, willReconnect) {
+        const delivered = new Promise((resolve) => this.#enqueue(() => {
+            try {
+                this.#deliver("disconnected", { error: cause, willReconnect });
+            }
+            finally {
+                resolve();
+            }
+        }));
+        this.#disconnectedDelivered = delivered;
+        void delivered.then(() => {
+            if (this.#disconnectedDelivered === delivered)
+                this.#disconnectedDelivered = undefined;
+        });
+        return delivered;
+    }
+    /** Queue a lifecycle event, which middleware does not see. */
+    #emit(event, payload) {
+        this.#enqueue(() => this.#deliver(event, payload));
+    }
+    #deliver(event, payload) {
+        for (const subscription of this.#listeners.get(event) ?? []) {
+            // Checked at delivery: a listener removed while its event was queued
+            // does not get it.
+            if (subscription.removed)
+                continue;
+            try {
+                subscription.listener(payload);
+            }
+            catch (error) {
+                // Rethrown on its own, as an uncaught exception, so it surfaces as one
+                // from an EventEmitter listener would, and the listeners after it
+                // still get the event.
+                queueMicrotask(() => {
+                    throw error;
+                });
+            }
+        }
+    }
+    /**
+     * Run deliveries one at a time, in order, once the packet being handled is
+     * done with. A listener that throws does so as an uncaught exception, as it
+     * would from an EventEmitter, and the listeners and deliveries behind it
+     * still run.
+     */
+    #enqueue(delivery) {
+        this.#queue.push(delivery);
+        if (this.#draining)
+            return;
+        this.#draining = true;
+        setImmediate(this.#drain);
+    }
+    #drain = () => {
+        try {
+            while (this.#queue.length > 0)
+                this.#queue.shift()();
+        }
+        finally {
+            if (this.#queue.length > 0)
+                setImmediate(this.#drain);
+            else
+                this.#draining = false;
+        }
+    };
+    #handleConnectionClosed(err) {
+        if (this.#status === ClientStatus.Disconnected)
+            return;
+        // Nothing in flight can be answered any more; failing it now, with the
+        // reason, beats every caller timing out one by one.
+        this.#cmdTrack.reset(new NotConnectedError(err ? { cause: err } : undefined));
+        if (this.#status !== ClientStatus.Connected) {
+            // The socket closed before the handshake finished, so this is a failed
+            // connection attempt rather than a disconnect of a live session.
+            this.#failConnection(err ?? new TeamspeakError("connection closed before the TeamSpeak handshake completed"));
+            return;
+        }
+        this.#status = ClientStatus.Disconnected;
+        // 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
+        // a silent recovery hides an outage.
+        void this.#announceDisconnected(cause, this.#willReconnect(cause, this.#loopAttempt + 1));
+        this.#scheduleReconnect(cause).catch((error) => {
+            this.#logger.error("reconnecting failed", { error: String(error) });
+        });
+    }
+    /**
+     * Whether the reconnect loop will make attempt number `attempt` after `err`.
+     * `disconnected` reports it, and the loop acts on the same answer: the
+     * caller's `shouldRetry` is asked once per failure, not once to announce it
+     * and again to act on it.
+     */
+    #willReconnect(err, attempt) {
+        const options = this.#reconnectOptions;
+        if (options === undefined || this.#stopped)
+            return false;
+        const { maxAttempts } = resolveBackoffPolicy(options);
+        if (maxAttempts !== 0 && attempt > maxAttempts)
+            return false;
+        const asked = this.#retryAnswer;
+        if (asked?.err === err && asked.attempt === attempt)
+            return asked.retry;
+        let retry;
+        let threw = false;
+        try {
+            retry = (options.shouldRetry ?? defaultShouldRetry)(err, attempt);
+        }
+        catch (error) {
+            this.#logger.error("shouldRetry threw; not reconnecting", { error: String(error) });
+            retry = false;
+            threw = true;
+        }
+        this.#retryAnswer = { err, attempt, retry, threw };
+        return retry;
+    }
+    /**
+     * Retry a dropped connection according to the reconnect policy.
+     *
+     * Never runs after an explicit disconnect, and never more than one at a time:
+     * two failures in quick succession would otherwise start competing loops, and
+     * a loop shorter than the server's antiflood window bans the IP rather than
+     * reconnecting it. A drop while the loop runs is the loop's to retry: it
+     * ends only once its attempt is still connected when it resumes.
+     */
+    async #scheduleReconnect(err) {
+        const options = this.#reconnectOptions;
+        if (options === undefined || this.#stopped || this.#reconnecting)
+            return;
+        const policy = resolveBackoffPolicy(options);
+        this.#reconnecting = true;
+        const stop = new AbortController();
+        this.#stopReconnecting = stop;
+        // The attempts the loop has made, and why it stopped, for `reconnectStopped`.
+        let made = 0;
+        let stoppedBy;
+        try {
+            for (let attempt = 1; policy.maxAttempts === 0 || attempt <= policy.maxAttempts; attempt++) {
+                if (this.#stopped) {
+                    stoppedBy = { cause: undefined };
+                    return;
+                }
+                if (!this.#willReconnect(err, attempt)) {
+                    if (!this.#retryAnswer?.threw) {
+                        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) {
+                    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) {
+                    this.#logger.info("reconnect loop ended: connected by other means", { attempt });
+                    return;
+                }
+                try {
+                    made++;
+                    this.#loopAttempt = attempt;
+                    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 });
+                        return;
+                    }
+                    // The new session dropped before this loop resumed — initserver and
+                    // the server's goodbye in one datagram, say. That drop found this
+                    // loop running and left the retrying to it.
+                    err = this.#lastDrop ?? new TeamspeakError("connection closed");
+                }
+                catch (retryErr) {
+                    if (retryErr instanceof AlreadyConnectedError)
+                        return;
+                    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;
+            this.#loopAttempt = 0;
+            if (this.#stopReconnecting === stop)
+                this.#stopReconnecting = undefined;
+        }
+    }
+    /**
+     * A connection attempt has failed for good: settle it with the cause, and
+     * tear the connection down. Does nothing once the handshake has completed,
+     * so it cannot end a live session.
+     *
+     * Without this, a handshake the server rejects (a wrong password, say, which
+     * the server answers with an error instead of closing the socket) surfaces
+     * only as the caller's own timeout, and the client stays in `Connecting`
+     * forever without ever emitting `disconnected`.
+     */
+    #failConnection(error) {
+        if (this.#status === ClientStatus.Connected)
+            return;
+        this.#attempt.reject(error);
+        if (this.#status === ClientStatus.Disconnected)
+            return;
+        this.#status = ClientStatus.Disconnected;
+        this.#handler.close();
+        const cause = error instanceof Error ? error : new TeamspeakError(String(error), { cause: error });
+        // Only an attempt of the reconnect loop can be followed by another; a
+        // connect() that fails is the caller's to retry.
+        void this.#announceDisconnected(cause, this.#reconnecting && this.#willReconnect(cause, this.#loopAttempt + 1));
+    }
+}
+function kickedEvent(event) {
+    return {
+        reason: event.reason,
+        reasonMessage: event.reasonMessage,
+        invokerName: event.invokerName,
+        invokerUID: event.invokerUID,
+        invokerID: event.invokerID,
+    };
+}
+//# sourceMappingURL=client.js.map