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

package/dist/index.js

@@ -1,11 +1,12 @@
-import { CommandTimeoutError, ErrorCode, NotConnectedError, Reason, ServerError, TeamspeakError, asChannelID, asClientID, asUID, noopLogger } from "@honeybbq/teamspeak-core";
+import { CommandTimeoutError, ErrorCode, NotConnectedError, Reason, ServerError, TeamspeakError, asChannelID, asClientID, asServerID, asUID, noopLogger } from "@honeybbq/teamspeak-core";
 import { createCipheriv, createECDH, createHash, createPrivateKey, createPublicKey, createSign, createVerify, generateKeyPairSync, randomBytes, timingSafeEqual } from "node:crypto";
+import { buildCommand, buildCommandOrdered, encodeRequest, parseClient, parseCommand, parseErrorCode, parseIconID, parseInt10, parseServerError, parseUint16, parseUint64, responseSpec, sleep, splitCommandRows } from "@honeybbq/teamspeak-core/internal";
 import { ed25519 } from "@noble/curves/ed25519.js";
 import { lookup, resolveSrv } from "node:dns/promises";
 import { connect, createConnection, isIP } from "node:net";
 import { createSocket } from "node:dgram";
-import { buildCommand, buildCommandOrdered, encodeRequest, parseClient, parseCommand, parseErrorCode, parseIconID, parseInt10, parseServerError, parseUint16, parseUint64, responseSpec, sleep, splitCommandRows } from "@honeybbq/teamspeak-core/internal";
 import { pipeline } from "node:stream/promises";
+import { Transform } from "node:stream";
 import { channel, tracingChannel } from "node:diagnostics_channel";
 export * from "@honeybbq/teamspeak-core";
 /** Where a client is in its connection's life. */
@@ -17,15 +18,56 @@ var ClientStatus = /* @__PURE__ */ Object.freeze({
 	/** Connected: the handshake completed and commands can be sent. */
 	Connected: "connected"
 });
+/** Where a connection attempt can fail; see {@link AttemptFailedInfo}. */
+var ConnectPhase = /* @__PURE__ */ Object.freeze({
+	/** Opening the socket, or the address was not usable once resolved. */
+	Open: "open",
+	/** The handshake, from the first packet until the shared secret exists. */
+	Handshake: "handshake",
+	/** After the handshake, waiting for the server to accept the client: a wrong password, a ban or an invalid nickname end here. */
+	Join: "join"
+});
+//#endregion
+//#region src/hooks.ts
+/**
+* Report an error from a trace hook the way a throwing event listener's is
+* reported: rethrown on its own, as an uncaught exception.
+*/
+function reportHookError(error) {
+	queueMicrotask(() => {
+		throw error;
+	});
+}
+/**
+* Call a trace hook, if there is one, and never let it touch what called it:
+* a throw, or the rejection of a promise it returns, is reported as a
+* throwing listener's is. The info is built only when there is a hook.
+*/
+function callHook(hook, owner, info) {
+	if (hook === void 0) return;
+	try {
+		const result = hook.call(owner, info());
+		if (result !== null && typeof result === "object" && "then" in result) Promise.resolve(result).then(void 0, reportHookError);
+	} catch (error) {
+		reportHookError(error);
+	}
+}
 //#endregion
 //#region src/errors.ts
 /** `connect()` was called on a client that is connecting or connected. */
 var AlreadyConnectedError = class extends TeamspeakError {
 	/** {@inheritDoc TeamspeakError.kind} */
 	static kind = "AlreadyConnectedError";
+	static {
+		Object.defineProperty(this.prototype, "name", {
+			value: "AlreadyConnectedError",
+			writable: true,
+			configurable: true,
+			enumerable: false
+		});
+	}
 	constructor() {
 		super("already connecting or connected");
-		this.name = "AlreadyConnectedError";
 	}
 };
 /**
@@ -39,11 +81,18 @@ var AlreadyConnectedError = class extends TeamspeakError {
 var InvalidAddressError = class extends TeamspeakError {
 	/** {@inheritDoc TeamspeakError.kind} */
 	static kind = "InvalidAddressError";
+	static {
+		Object.defineProperty(this.prototype, "name", {
+			value: "InvalidAddressError",
+			writable: true,
+			configurable: true,
+			enumerable: false
+		});
+	}
 	/** The address as given. */
 	address;
 	constructor(address, reason) {
 		super(`invalid address ${JSON.stringify(address)}: ${reason}`);
-		this.name = "InvalidAddressError";
 		this.address = address;
 	}
 };
@@ -54,9 +103,16 @@ var InvalidAddressError = class extends TeamspeakError {
 var EAXTagMismatchError = class extends TeamspeakError {
 	/** {@inheritDoc TeamspeakError.kind} */
 	static kind = "EAXTagMismatchError";
+	static {
+		Object.defineProperty(this.prototype, "name", {
+			value: "EAXTagMismatchError",
+			writable: true,
+			configurable: true,
+			enumerable: false
+		});
+	}
 	constructor() {
 		super("EAX tag mismatch");
-		this.name = "EAXTagMismatchError";
 	}
 };
 /**
@@ -66,18 +122,32 @@ var EAXTagMismatchError = class extends TeamspeakError {
 var FakeSignatureMismatchError = class extends TeamspeakError {
 	/** {@inheritDoc TeamspeakError.kind} */
 	static kind = "FakeSignatureMismatchError";
+	static {
+		Object.defineProperty(this.prototype, "name", {
+			value: "FakeSignatureMismatchError",
+			writable: true,
+			configurable: true,
+			enumerable: false
+		});
+	}
 	constructor() {
 		super("fake signature mismatch");
-		this.name = "FakeSignatureMismatchError";
 	}
 };
 /** A file transfer connection failed: it could not be opened, or broke during the transfer. */
 var FileTransferError = class extends TeamspeakError {
 	/** {@inheritDoc TeamspeakError.kind} */
 	static kind = "FileTransferError";
+	static {
+		Object.defineProperty(this.prototype, "name", {
+			value: "FileTransferError",
+			writable: true,
+			configurable: true,
+			enumerable: false
+		});
+	}
 	constructor(message, options) {
 		super(message, options);
-		this.name = "FileTransferError";
 	}
 };
 /**
@@ -85,21 +155,35 @@ var FileTransferError = class extends TeamspeakError {
 * Init1 step, public key, license or proof. `connect()` rejects with it, the
 * underlying failure as its `cause`.
 */
-var CryptoInitError = class extends TeamspeakError {
+var HandshakeError = class extends TeamspeakError {
 	/** {@inheritDoc TeamspeakError.kind} */
-	static kind = "CryptoInitError";
+	static kind = "HandshakeError";
+	static {
+		Object.defineProperty(this.prototype, "name", {
+			value: "HandshakeError",
+			writable: true,
+			configurable: true,
+			enumerable: false
+		});
+	}
 	constructor(message, options) {
 		super(message, options);
-		this.name = "CryptoInitError";
 	}
 };
 /** An identity string `parseIdentity()` cannot read. */
 var InvalidIdentityError = class extends TeamspeakError {
 	/** {@inheritDoc TeamspeakError.kind} */
 	static kind = "InvalidIdentityError";
+	static {
+		Object.defineProperty(this.prototype, "name", {
+			value: "InvalidIdentityError",
+			writable: true,
+			configurable: true,
+			enumerable: false
+		});
+	}
 	constructor(message = "invalid identity format", options) {
 		super(message, options);
-		this.name = "InvalidIdentityError";
 	}
 };
 /**
@@ -109,9 +193,16 @@ var InvalidIdentityError = class extends TeamspeakError {
 var ConnectionTimeoutError = class extends TeamspeakError {
 	/** {@inheritDoc TeamspeakError.kind} */
 	static kind = "ConnectionTimeoutError";
+	static {
+		Object.defineProperty(this.prototype, "name", {
+			value: "ConnectionTimeoutError",
+			writable: true,
+			configurable: true,
+			enumerable: false
+		});
+	}
 	constructor() {
 		super("connection timed out: the server stopped answering");
-		this.name = "ConnectionTimeoutError";
 	}
 };
 /**
@@ -122,6 +213,14 @@ var ConnectionTimeoutError = class extends TeamspeakError {
 var RemovedError = class extends TeamspeakError {
 	/** {@inheritDoc TeamspeakError.kind} */
 	static kind = "RemovedError";
+	static {
+		Object.defineProperty(this.prototype, "name", {
+			value: "RemovedError",
+			writable: true,
+			configurable: true,
+			enumerable: false
+		});
+	}
 	/** Why: `Reason.KickServer`, `KickServerBan`, `ServerStop` or `ServerShutdown`. */
 	reason;
 	/** The reason the server or the invoker gave, if any. */
@@ -133,7 +232,6 @@ var RemovedError = class extends TeamspeakError {
 		if (invokerName) message += ` by ${invokerName}`;
 		if (reasonMessage) message += `: ${reasonMessage}`;
 		super(message);
-		this.name = "RemovedError";
 		this.reason = reason;
 		this.reasonMessage = reasonMessage;
 		this.invokerName = invokerName;
@@ -149,6 +247,107 @@ function reasonName(reason) {
 	}
 }
 //#endregion
+//#region src/handshake/crypt-handshake.ts
+var INIT_VERSION = 1566914096;
+var INIT_STEP_LEN = 21;
+/** The RSA challenge each connection attempt, by its Crypt, has answered. */
+var answeredChallenges = /* @__PURE__ */ new WeakMap();
+/**
+* The RSA puzzle `crypt`'s attempt solved: the level the server demanded and
+* the milliseconds spent on it. Level 0 and no time when the server sent none.
+*/
+function puzzleOf(crypt) {
+	const answered = answeredChallenges.get(crypt);
+	return {
+		level: answered?.level ?? 0,
+		durationMs: answered?.durationMs ?? 0
+	};
+}
+/**
+* Handle the TS3INIT1 handshake steps.
+* Returns the response bytes to send, or null if nothing should be sent.
+* Throws a HandshakeError for a step that cannot be answered.
+*/
+function processInit1(crypt, data) {
+	if (data === null || data.length >= 1 && data[0] === 127) return buildInit1StartPacket();
+	if (data.length === 0) throw new HandshakeError("empty Init1 packet");
+	switch (data[0]) {
+		case 0: return buildInit1Step1Packet(data);
+		case 1: return buildInit1Step2Packet(data);
+		case 2: return buildInit1Step3Packet(data);
+		case 3: return buildInit1Step4Packet(crypt, data);
+		default: return null;
+	}
+}
+function buildInit1StartPacket() {
+	const sendData = /* @__PURE__ */ new Uint8Array(21);
+	const view = new DataView(sendData.buffer);
+	view.setUint32(0, INIT_VERSION, false);
+	sendData[4] = 0;
+	const nowSec = Math.floor(Date.now() / 1e3);
+	const clampedNow = Math.max(0, Math.min(nowSec, 4294967295));
+	view.setUint32(5, clampedNow, false);
+	const rng = randomBytes(4);
+	sendData.set(rng, 9);
+	return sendData;
+}
+function buildInit1Step1Packet(data) {
+	if (data.length !== INIT_STEP_LEN) return null;
+	const sendData = /* @__PURE__ */ new Uint8Array(21);
+	sendData[0] = 1;
+	const tsRand = data[9] | data[10] << 8 | data[11] << 16 | data[12] << 24;
+	new DataView(sendData.buffer).setUint32(17, tsRand >>> 0, false);
+	return sendData;
+}
+function buildInit1Step2Packet(data) {
+	if (data.length !== INIT_STEP_LEN) return null;
+	const sendData = /* @__PURE__ */ new Uint8Array(25);
+	new DataView(sendData.buffer).setUint32(0, INIT_VERSION, false);
+	sendData[4] = 2;
+	sendData.set(data.slice(1, 21), 5);
+	return sendData;
+}
+function buildInit1Step3Packet(data) {
+	if (data.length !== 25) return null;
+	const sendData = /* @__PURE__ */ new Uint8Array(233);
+	sendData[0] = 3;
+	sendData[64] = 1;
+	sendData[128] = 1;
+	new DataView(sendData.buffer).setUint32(129, 1, false);
+	return sendData;
+}
+function buildInit1Step4Packet(crypt, data) {
+	if (data.length !== 233) return null;
+	const answered = answeredChallenges.get(crypt);
+	if (answered !== void 0) return Buffer.from(answered.challenge).equals(Buffer.from(data)) ? answered.answer : null;
+	const level = new DataView(data.buffer, data.byteOffset).getUint32(129, false);
+	const solveStarted = performance.now();
+	const y = crypt.solveRsaChallenge(data, 1, level);
+	const durationMs = performance.now() - solveStarted;
+	const alphaB64 = Buffer.from(crypt.newAlpha()).toString("base64");
+	const omegaB64 = crypt.identity.publicKey();
+	const cmd = buildCommandOrdered("clientinitiv", [
+		["alpha", alphaB64],
+		["omega", omegaB64],
+		["ot", "1"],
+		["ip", ""]
+	]);
+	const cmdBytes = Buffer.from(cmd);
+	const sendData = new Uint8Array(301 + cmdBytes.length);
+	new DataView(sendData.buffer).setUint32(0, INIT_VERSION, false);
+	sendData[4] = 4;
+	sendData.set(data.slice(1, 233), 5);
+	sendData.set(y.slice(0, 64), 237);
+	sendData.set(cmdBytes, 301);
+	answeredChallenges.set(crypt, {
+		challenge: Uint8Array.from(data),
+		answer: sendData,
+		level,
+		durationMs
+	});
+	return sendData;
+}
+//#endregion
 //#region src/abort.ts
 /** The reason an aborted signal gives, as an error. */
 function abortReason(signal) {
@@ -665,12 +864,12 @@ var Crypt = class {
 		return this.#alpha;
 	}
 	solveRsaChallenge(data, offset, level) {
-		if (!Number.isInteger(level) || level < 0 || level > 1e5) throw new CryptoInitError(`RSA challenge level ${level} out of range`);
+		if (!Number.isInteger(level) || level < 0 || level > 1e5) throw new HandshakeError(`RSA challenge level ${level} out of range`);
 		const xBytes = data.slice(offset, offset + 64);
 		const nBytes = data.slice(offset + 64, offset + 128);
 		let y = bytesToBigInt(xBytes);
 		const n = bytesToBigInt(nBytes);
-		if (n === 0n) throw new CryptoInitError("RSA challenge modulus is zero");
+		if (n === 0n) throw new HandshakeError("RSA challenge modulus is zero");
 		for (let i = 0; i < level; i++) y = y * y % n;
 		return bigIntToBytes(y, 64);
 	}
@@ -682,7 +881,7 @@ var Crypt = class {
 		try {
 			sharedSecret = this.#getSharedSecret(importPublicKey(omegaBytes));
 		} catch (error) {
-			throw new CryptoInitError("the server's public key is invalid", { cause: error });
+			throw new HandshakeError("the server's public key is invalid", { cause: error });
 		}
 		this.setSharedSecret(alphaBytes, betaBytes, sharedSecret);
 	}
@@ -705,7 +904,7 @@ var Crypt = class {
 	}
 	getKeyNonce(fromServer, packetID, generationID, packetType, dummy) {
 		if (dummy) return [Uint8Array.from(DUMMY_KEY), Uint8Array.from(DUMMY_NONCE)];
-		if (!this.#cryptoInitComplete) throw new CryptoInitError("no session key before crypto init completes");
+		if (!this.#cryptoInitComplete) throw new HandshakeError("no session key before crypto init completes");
 		const cacheKey = makeCacheKey(fromServer, packetType, generationID);
 		let kn = this.#cachedKeys.get(cacheKey);
 		if (kn === void 0) {
@@ -971,7 +1170,7 @@ var Resolver = class {
 	* address as given is the answer.
 	*/
 	async resolve(inputAddr, options = {}) {
-		if (!inputAddr) throw new Error("empty address");
+		if (!inputAddr) throw new InvalidAddressError(inputAddr, "empty address");
 		const budget = AbortSignal.timeout(RESOLVE_BUDGET_MS);
 		const signal = options.signal ? AbortSignal.any([options.signal, budget]) : budget;
 		try {
@@ -1039,7 +1238,7 @@ var Resolver = class {
 		try {
 			const srvs = await abortable(resolveSrv(`_ts3._udp.${host}`), signal);
 			if (!srvs || srvs.length === 0) return null;
-			return srvs.map((srv) => ({
+			return orderSrvRecords(srvs).map((srv) => ({
 				addr: joinHostPort(srv.name.replace(/\.$/, ""), String(srv.port)),
 				source: "SRV"
 			}));
@@ -1051,7 +1250,7 @@ var Resolver = class {
 		for (const domain of domains) try {
 			const srvs = await abortable(resolveSrv(`_tsdns._tcp.${domain}`), signal);
 			if (!srvs || srvs.length === 0) continue;
-			for (const srv of srvs) {
+			for (const srv of orderSrvRecords(srvs)) {
 				const result = await queryTSDNS(joinHostPort(srv.name.replace(/\.$/, ""), String(srv.port)), queryHost, signal);
 				if (result) return result;
 			}
@@ -1064,6 +1263,48 @@ var Resolver = class {
 		return (await Promise.all(domains.map((domain) => queryTSDNS(joinHostPort(domain, String(TS_DNS_DEFAULT_PORT)), queryHost, signal)))).find((answer) => answer !== null) ?? null;
 	}
 };
+/**
+* Put SRV records in the order RFC 2782 has a client try them: by priority,
+* lowest first, and within a priority by weighted random selection, so a
+* record of weight 2 is first twice as often as one of weight 1. Records of
+* weight 0 follow the others of their priority, in the order given. Node's
+* `resolveSrv` returns the records unsorted.
+*
+* @param random Returns a number in [0, 1); injected to make the order testable.
+* @internal
+*/
+function orderSrvRecords(records, random = Math.random) {
+	const byPriority = /* @__PURE__ */ new Map();
+	for (const record of records) {
+		const group = byPriority.get(record.priority);
+		if (group) group.push(record);
+		else byPriority.set(record.priority, [record]);
+	}
+	const ordered = [];
+	for (const priority of [...byPriority.keys()].sort((a, b) => a - b)) {
+		const group = byPriority.get(priority);
+		const weighted = group.filter((r) => r.weight > 0);
+		const unweighted = group.filter((r) => r.weight <= 0);
+		let sum = weighted.reduce((total, r) => total + r.weight, 0);
+		while (weighted.length > 0) {
+			const target = random() * sum;
+			let running = 0;
+			let pick = weighted.length - 1;
+			for (let i = 0; i < weighted.length; i++) {
+				running += weighted[i].weight;
+				if (running > target) {
+					pick = i;
+					break;
+				}
+			}
+			const [chosen] = weighted.splice(pick, 1);
+			ordered.push(chosen);
+			sum -= chosen.weight;
+		}
+		ordered.push(...unweighted);
+	}
+	return ordered;
+}
 /** @internal Ask the nickname service for `nickname`'s address. */
 async function resolveNickname(nickname, signal) {
 	try {
@@ -1406,92 +1647,6 @@ function parseQlzHeader(data) {
 	};
 }
 //#endregion
-//#region src/handshake/crypt-handshake.ts
-var INIT_VERSION = 1566914096;
-var INIT_STEP_LEN = 21;
-/** The RSA challenge each connection attempt, by its Crypt, has answered. */
-var answeredChallenges = /* @__PURE__ */ new WeakMap();
-/**
-* Handle the TS3INIT1 handshake steps.
-* Returns the response bytes to send, or null if nothing should be sent.
-* Throws a CryptoInitError for a step that cannot be answered.
-*/
-function processInit1(crypt, data) {
-	if (data === null || data.length >= 1 && data[0] === 127) return buildInit1StartPacket();
-	if (data.length === 0) throw new CryptoInitError("empty Init1 packet");
-	switch (data[0]) {
-		case 0: return buildInit1Step1Packet(data);
-		case 1: return buildInit1Step2Packet(data);
-		case 2: return buildInit1Step3Packet(data);
-		case 3: return buildInit1Step4Packet(crypt, data);
-		default: return null;
-	}
-}
-function buildInit1StartPacket() {
-	const sendData = /* @__PURE__ */ new Uint8Array(21);
-	const view = new DataView(sendData.buffer);
-	view.setUint32(0, INIT_VERSION, false);
-	sendData[4] = 0;
-	const nowSec = Math.floor(Date.now() / 1e3);
-	const clampedNow = Math.max(0, Math.min(nowSec, 4294967295));
-	view.setUint32(5, clampedNow, false);
-	const rng = randomBytes(4);
-	sendData.set(rng, 9);
-	return sendData;
-}
-function buildInit1Step1Packet(data) {
-	if (data.length !== INIT_STEP_LEN) return null;
-	const sendData = /* @__PURE__ */ new Uint8Array(21);
-	sendData[0] = 1;
-	const tsRand = data[9] | data[10] << 8 | data[11] << 16 | data[12] << 24;
-	new DataView(sendData.buffer).setUint32(17, tsRand >>> 0, false);
-	return sendData;
-}
-function buildInit1Step2Packet(data) {
-	if (data.length !== INIT_STEP_LEN) return null;
-	const sendData = /* @__PURE__ */ new Uint8Array(25);
-	new DataView(sendData.buffer).setUint32(0, INIT_VERSION, false);
-	sendData[4] = 2;
-	sendData.set(data.slice(1, 21), 5);
-	return sendData;
-}
-function buildInit1Step3Packet(data) {
-	if (data.length !== 25) return null;
-	const sendData = /* @__PURE__ */ new Uint8Array(233);
-	sendData[0] = 3;
-	sendData[64] = 1;
-	sendData[128] = 1;
-	new DataView(sendData.buffer).setUint32(129, 1, false);
-	return sendData;
-}
-function buildInit1Step4Packet(crypt, data) {
-	if (data.length !== 233) return null;
-	const answered = answeredChallenges.get(crypt);
-	if (answered !== void 0) return Buffer.from(answered.challenge).equals(Buffer.from(data)) ? answered.answer : null;
-	const level = new DataView(data.buffer, data.byteOffset).getUint32(129, false);
-	const y = crypt.solveRsaChallenge(data, 1, level);
-	const alphaB64 = Buffer.from(crypt.newAlpha()).toString("base64");
-	const omegaB64 = crypt.identity.publicKey();
-	const cmd = buildCommandOrdered("clientinitiv", [
-		["alpha", alphaB64],
-		["omega", omegaB64],
-		["ot", "1"],
-		["ip", ""]
-	]);
-	const cmdBytes = Buffer.from(cmd);
-	const sendData = new Uint8Array(301 + cmdBytes.length);
-	new DataView(sendData.buffer).setUint32(0, INIT_VERSION, false);
-	sendData[4] = 4;
-	sendData.set(data.slice(1, 233), 5);
-	sendData.set(y.slice(0, 64), 237);
-	sendData.set(cmdBytes, 301);
-	answeredChallenges.set(crypt, {
-		challenge: Uint8Array.from(data),
-		answer: sendData
-	});
-	return sendData;
-}
-//#endregion
 //#region src/transport/handler.ts
 var RECEIVE_PACKET_WINDOW_SIZE = 1024;
 var PING_INTERVAL_MS = 5e3;
@@ -1535,6 +1690,8 @@ var PacketHandler = class {
 	* ends the connection. Without an owner the error is logged.
 	*/
 	onReceiveError = null;
+	/** Called with the socket once it is open, before the handshake's first packet is sent. */
+	onOpen = null;
 	#crypt;
 	#logger;
 	#socketFactory;
@@ -1543,7 +1700,7 @@ var PacketHandler = class {
 	#closed = false;
 	#stopPing = null;
 	#stopResend = null;
-	#lastMessageReceived = Date.now();
+	#lastMessageReceived = performance.now();
 	#packetCounter = /* @__PURE__ */ new Uint16Array(9);
 	#generationCounter = /* @__PURE__ */ new Uint32Array(9);
 	#recvWindowCommand = new GenerationWindow(65536, RECEIVE_PACKET_WINDOW_SIZE);
@@ -1623,6 +1780,7 @@ var PacketHandler = class {
 				done = true;
 				socket.off("error", onError);
 				signal?.removeEventListener("abort", onAbort);
+				this.onOpen?.(socket);
 				this.start(socket);
 				resolve();
 			});
@@ -1639,7 +1797,7 @@ var PacketHandler = class {
 			return;
 		}
 		this.#conn = conn;
-		this.#lastMessageReceived = Date.now();
+		this.#lastMessageReceived = performance.now();
 		conn.on("message", (msg) => {
 			if (this.#closed) return;
 			try {
@@ -1797,8 +1955,8 @@ var PacketHandler = class {
 		if (dummy && pType === PacketType.Command) this.#dummyCommandIDs.add(pID);
 		const rp = {
 			packet: p,
-			firstSend: Date.now(),
-			lastSend: Date.now(),
+			firstSend: performance.now(),
+			lastSend: performance.now(),
 			retryCount: 0,
 			nextInterval: RESEND_BASE_INTERVAL_MS
 		};
@@ -1811,7 +1969,7 @@ var PacketHandler = class {
 				if (err) this.#logger.warn("udp send error", err);
 			});
 		} catch (error) {
-			const normalized = error instanceof Error ? error : new Error(String(error));
+			const normalized = error instanceof Error ? error : new Error(String(error), { cause: error });
 			this.#logger.error("udp send failed", normalized);
 			this.#triggerClose(normalized);
 		}
@@ -1832,12 +1990,12 @@ var PacketHandler = class {
 			clientID: 0,
 			generationID: this.#resolveGeneration(parsed.id, parsed.typeFlagged & 15),
 			data: /* @__PURE__ */ new Uint8Array(0),
-			receivedAt: Date.now()
+			receivedAt: performance.now()
 		};
 		const decrypted = this.#decryptPacketData(p, header, ciphertext, tag);
 		if (decrypted === null) return;
 		p.data = decrypted.plaintext;
-		this.#lastMessageReceived = Date.now();
+		this.#lastMessageReceived = performance.now();
 		if (packetType(p) === PacketType.Ping) {
 			this.#sendPong(p.id, decrypted.dummyUsed);
 			return;
@@ -2053,7 +2211,7 @@ var PacketHandler = class {
 		}
 	}
 	#checkResends() {
-		const now = Date.now();
+		const now = performance.now();
 		if (now - this.#lastMessageReceived > PACKET_TIMEOUT_MS) {
 			this.#logger.warn("idle timeout");
 			this.#triggerClose(new ConnectionTimeoutError());
@@ -2103,7 +2261,7 @@ function applyProtocolFlags(pType, flags) {
 	return flags;
 }
 function hasOldNewerPacket(queue, nextID) {
-	const now = Date.now();
+	const now = performance.now();
 	for (const [id, pkg] of queue) if ((id - nextID + 65536 & 65535) < 32768 && now - pkg.receivedAt > 5e3) return true;
 	return false;
 }
@@ -2285,12 +2443,75 @@ function appendReturnCode(cmd, rc) {
 */
 /** How long dialing may take before it fails, unless a signal says otherwise. */
 var DIAL_TIMEOUT_MS = 1e4;
+/** How long a transfer may go without moving a byte, unless `idleTimeoutMs` says otherwise. */
+var DEFAULT_IDLE_TIMEOUT_MS = 3e4;
+/** How many bytes move between two calls of the `progress` hook, at least. */
+var PROGRESS_STEP_BYTES = 65536;
+function newIdleGuard(options) {
+	const limitMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+	if (!Number.isFinite(limitMs) || limitMs < 0) throw new RangeError("idleTimeoutMs must be a finite number of milliseconds, 0 or more");
+	const controller = new AbortController();
+	if (limitMs === 0) return {
+		signal: controller.signal,
+		limitMs,
+		touch() {},
+		stop() {}
+	};
+	const timer = setTimeout(() => controller.abort(new DOMException(`no data moved for ${limitMs} ms`, "TimeoutError")), limitMs);
+	return {
+		signal: controller.signal,
+		limitMs,
+		touch: () => timer.refresh(),
+		stop: () => clearTimeout(timer)
+	};
+}
+/** The error a transfer fails with when `idle` expired, else `error` as it is. */
+function idleOr(idle, error) {
+	if (!idle.signal.aborted) return error;
+	return new FileTransferError(`file transfer stalled: no data moved for ${idle.limitMs} ms`, { cause: idle.signal.reason });
+}
+function newTransferTrace(options) {
+	return {
+		trace: options.trace === void 0 ? void 0 : { ...options.trace },
+		startedAt: performance.now(),
+		bytes: 0
+	};
+}
+function reportFailed(t, error, stage) {
+	callHook(t.trace?.failed, t.trace, () => ({
+		error,
+		bytes: t.bytes,
+		durationMs: performance.now() - t.startedAt,
+		stage
+	}));
+}
 /**
 * Open a connection to the file transfer port and send the transfer key.
 * The caller owns the returned stream and must end or destroy it.
 */
 async function dialFileTransfer(host, port, key, options = {}) {
+	const t = newTransferTrace(options);
+	const idle = newIdleGuard(options);
+	try {
+		return await dial(host, port, key, options, t, idle);
+	} catch (error) {
+		const failure = idleOr(idle, error);
+		reportFailed(t, failure, "dial");
+		throw failure;
+	} finally {
+		idle.stop();
+	}
+}
+async function dial(host, port, key, options, t, idle) {
 	const { signal, socketFactory } = options;
+	const timeout = AbortSignal.timeout(DIAL_TIMEOUT_MS);
+	const dialSignal = AbortSignal.any(signal ? [
+		signal,
+		timeout,
+		idle.signal
+	] : [timeout, idle.signal]);
+	const addr = joinHostPort(host, String(port));
+	callHook(t.trace?.dialStart, t.trace, () => ({ addr }));
 	signal?.throwIfAborted();
 	const socket = socketFactory ? socketFactory(host, port) : connect({
 		host,
@@ -2299,57 +2520,138 @@ async function dialFileTransfer(host, port, key, options = {}) {
 	const swallow = () => {};
 	socket.on("error", swallow);
 	try {
-		await connected(socket, signal);
-		await new Promise((resolve, reject) => {
+		await abortable(connected(socket), dialSignal);
+		idle.touch();
+		await abortable(new Promise((resolve, reject) => {
 			socket.write(key, (err) => err ? reject(new FileTransferError(`failed to send transfer key: ${err.message}`, { cause: err })) : resolve());
-		});
+		}), dialSignal);
+		idle.touch();
 	} catch (error) {
 		socket.destroy();
+		if (timeout.aborted && error === timeout.reason) throw new FileTransferError("file transfer connection timed out", { cause: error });
 		throw error;
 	} finally {
 		socket.off("error", swallow);
 	}
+	callHook(t.trace?.dialDone, t.trace, () => {
+		let localAddr = "";
+		const local = socket;
+		if (typeof local.localAddress === "string" && typeof local.localPort === "number") localAddr = joinHostPort(local.localAddress, String(local.localPort));
+		return {
+			addr,
+			localAddr,
+			durationMs: performance.now() - t.startedAt
+		};
+	});
 	return socket;
 }
 /**
+* A pass-through that counts what moves and reports it to `progress`. It never
+* fails the pipeline: a hook's error is reported, not thrown.
+*/
+function countingStream(t, total, idle) {
+	let reported = 0;
+	return new Transform({ transform(chunk, _encoding, callback) {
+		t.bytes += typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.length;
+		idle.touch();
+		if (t.bytes - reported >= PROGRESS_STEP_BYTES) {
+			reported = t.bytes;
+			const bytes = t.bytes;
+			callHook(t.trace?.progress, t.trace, () => ({
+				bytes,
+				total
+			}));
+		}
+		callback(null, chunk);
+	} });
+}
+/**
+* Passes exactly `expected` bytes. One more byte fails the transfer, and is
+* not passed on; a stream that ends before `expected` fails it too.
+*/
+function exactSize(expected) {
+	let received = 0;
+	return new Transform({
+		transform(chunk, _encoding, callback) {
+			const room = expected - received;
+			if (chunk.length > room) {
+				this.push(chunk.subarray(0, room));
+				received = expected;
+				callback(new FileTransferError(`file transfer sent more than the announced ${expected} bytes`));
+				return;
+			}
+			received += chunk.length;
+			callback(null, chunk);
+		},
+		flush(callback) {
+			callback(received === expected ? null : new FileTransferError(`file transfer ended after ${received} of the announced ${expected} bytes`));
+		}
+	});
+}
+/** Run a transfer's data phase, and report how the whole call ended. */
+async function transfer(host, port, key, total, options, move) {
+	const t = newTransferTrace(options);
+	const idle = newIdleGuard(options);
+	try {
+		let socket;
+		try {
+			socket = await dial(host, port, key, options, t, idle);
+		} catch (error) {
+			const failure = idleOr(idle, error);
+			reportFailed(t, failure, "dial");
+			throw failure;
+		}
+		try {
+			const signal = options.signal ? AbortSignal.any([options.signal, idle.signal]) : idle.signal;
+			await move(socket, countingStream(t, total, idle), { signal });
+		} catch (error) {
+			const failure = idleOr(idle, error);
+			reportFailed(t, failure, "transfer");
+			throw failure;
+		}
+	} finally {
+		idle.stop();
+	}
+	const bytes = t.bytes;
+	callHook(t.trace?.progress, t.trace, () => ({
+		bytes,
+		total
+	}));
+	callHook(t.trace?.done, t.trace, () => ({
+		bytes,
+		durationMs: performance.now() - t.startedAt
+	}));
+}
+/**
 * Wait for a stream to be connected. A `node:net` socket says so with
 * `connect`; a stream from elsewhere that is already writable is taken as
 * connected.
 */
-function connected(socket, signal) {
+function connected(socket) {
 	const pending = socket.pending;
 	if (pending === false || pending === void 0 && socket.writable) return Promise.resolve();
 	return new Promise((resolve, reject) => {
-		const timeout = AbortSignal.timeout(DIAL_TIMEOUT_MS);
 		const done = (error) => {
 			socket.off("connect", onConnect);
 			socket.off("ready", onConnect);
 			socket.off("error", onError);
-			signal?.removeEventListener("abort", onAbort);
-			timeout.removeEventListener("abort", onTimeout);
 			if (error === void 0) resolve();
 			else reject(error);
 		};
 		const onConnect = () => done();
 		const onError = (error) => done(new FileTransferError(`file transfer connection failed: ${error.message}`, { cause: error }));
-		const onAbort = () => done(signal.reason);
-		const onTimeout = () => done(new FileTransferError("file transfer connection timed out"));
 		socket.once("connect", onConnect);
 		socket.once("ready", onConnect);
 		socket.once("error", onError);
-		signal?.addEventListener("abort", onAbort, { once: true });
-		timeout.addEventListener("abort", onTimeout, { once: true });
 	});
 }
 /** Upload `data` over a negotiated transfer. Resolves once every byte is sent. */
-async function uploadFileData(host, info, data, options = {}) {
-	const socket = await dialFileTransfer(host, info.port, info.fileTransferKey, options);
-	await pipeline(data, socket, options.signal ? { signal: options.signal } : {});
+function uploadFileData(host, info, data, options = {}) {
+	return transfer(host, info.port, info.fileTransferKey, 0, options, (socket, counter, pipeOptions) => pipeline(data, counter, socket, pipeOptions));
 }
 /** Download a negotiated transfer into `dest`. Resolves once the file is written. */
-async function downloadFileData(host, info, dest, options = {}) {
-	const socket = await dialFileTransfer(host, info.port, info.fileTransferKey, options);
-	await pipeline(socket, dest, options.signal ? { signal: options.signal } : {});
+function downloadFileData(host, info, dest, options = {}) {
+	return transfer(host, info.port, info.fileTransferKey, Number(info.size), options, (socket, counter, pipeOptions) => pipeline(socket, exactSize(Number(info.size)), counter, dest, pipeOptions));
 }
 //#endregion
 //#region src/events.ts
@@ -2370,6 +2672,19 @@ function buildEventChain(middlewares, base) {
 //#endregion
 //#region src/capabilities.ts
 /**
+* What the connected server is, and what that means for the caller.
+*
+* TS3 and TS6 differ in ways that stay invisible until something breaks. The
+* clearest: the server hashes a client's public key with SHA-1 on TS3 and
+* SHA-256 on TS6, so a client that assumes either one computes a
+* `client_unique_identifier` the other server never sends.
+*
+* Everything below comes from the handshake — `initserver` carries
+* `virtualserver_version`, the one place the server names itself, along with
+* its name, icon, banner and welcome message — so reading it costs no extra
+* round trip.
+*/
+/**
 * Read what a server says about itself in `initserver`, or a version string
 * alone, such as "6.0.0-beta13.1 [Build: 1]".
 */
@@ -2389,7 +2704,11 @@ function parseServerCapabilities(initserver) {
 		name: params["virtualserver_name"] ?? "",
 		iconID: parseIconID(params["virtualserver_icon_id"]),
 		hostBannerImageURL: params["virtualserver_hostbanner_gfx_url"]?.trim() || void 0,
-		welcomeMessage: params["virtualserver_welcomemessage"] ?? ""
+		welcomeMessage: params["virtualserver_welcomemessage"] ?? "",
+		serverID: asServerID(parseUint64(params["virtualserver_id"] ?? "")),
+		serverUID: params["virtualserver_unique_identifier"] ?? "",
+		hostMessage: params["virtualserver_hostmessage"] ?? "",
+		hostMessageMode: hostMessageMode(params["virtualserver_hostmessage_mode"])
 	};
 }
 /**
@@ -2401,6 +2720,10 @@ function parseServerCapabilities(initserver) {
 function unknownServerCapabilities() {
 	return parseServerCapabilities("");
 }
+function hostMessageMode(value) {
+	const parsed = Number.parseInt(value ?? "", 10);
+	return Number.isNaN(parsed) ? 0 : parsed;
+}
 //#endregion
 //#region src/handshake/license.ts
 var LICENSE_ROOT_KEY = new Uint8Array([
@@ -2589,7 +2912,7 @@ function deriveKeyFromBlock(block, parent) {
 * Mirrors Go's handshake.CryptoInit2.
 */
 function cryptoInit2(crypt, license, omega, proof, beta, privateKey) {
-	if (crypt.alpha.length === 0) throw new CryptoInitError("initivexpand2 arrived before clientinitiv was sent");
+	if (crypt.alpha.length === 0) throw new HandshakeError("initivexpand2 arrived before clientinitiv was sent");
 	const licenseBytes = Buffer.from(license, "base64");
 	const omegaBytes = Buffer.from(omega, "base64");
 	const proofBytes = Buffer.from(proof, "base64");
@@ -2598,14 +2921,14 @@ function cryptoInit2(crypt, license, omega, proof, beta, privateKey) {
 	try {
 		serverPubKey = importPublicKey(omegaBytes);
 	} catch (error) {
-		throw new CryptoInitError("the server's public key is invalid", { cause: error });
+		throw new HandshakeError("the server's public key is invalid", { cause: error });
 	}
-	if (!verifySign(serverPubKey, licenseBytes, proofBytes)) throw new CryptoInitError("the server's license proof is not valid");
+	if (!verifySign(serverPubKey, licenseBytes, proofBytes)) throw new HandshakeError("the server's license proof is not valid");
 	let sharedSecret;
 	try {
 		sharedSecret = getSharedSecret2(parseLicenses(licenseBytes).deriveKey(), privateKey);
 	} catch (error) {
-		throw new CryptoInitError("the server's license is invalid", { cause: error });
+		throw new HandshakeError("the server's license is invalid", { cause: error });
 	}
 	crypt.setSharedSecret(crypt.alpha, betaBytes, sharedSecret);
 }
@@ -2618,6 +2941,7 @@ function handleHandshakeInitIV(client, params) {
 	const omega = params["omega"] ?? "";
 	client.handler.receivedFinalInitAck();
 	client.crypt.initCrypto(alpha, beta, omega);
+	client.markHandshakeDone(omega);
 	client.logger.info("crypto initialized (P-256 path), sending clientinit");
 	sendClientInit(client);
 }
@@ -2631,6 +2955,7 @@ function handleHandshakeExpand2(client, params) {
 	const beta = params["beta"] ?? "";
 	const privateKey = sendClientEkPacket(client, beta);
 	cryptoInit2(client.crypt, license, omega, proof, beta, privateKey);
+	client.markHandshakeDone(omega);
 	sendClientInit(client);
 }
 /** Handle `initserver` — marks the client as connected. */
@@ -2643,7 +2968,7 @@ function handleInitServer(client, params) {
 	}
 	client.capabilities = parseServerCapabilities(params);
 	client.logger.info("connected to server", { selfId: client.clid });
-	client.markConnected();
+	client.markConnected(params);
 	setImmediate(() => {
 		const updateCmd = buildCommand("clientupdate", {
 			client_input_muted: "0",
@@ -2807,7 +3132,7 @@ var CommandThrottle = class CommandThrottle {
 	static TOKEN_RATE = 4;
 	static TOKEN_MAX = 8;
 	#tokens = 5;
-	#lastUpdate = Date.now();
+	#lastUpdate = performance.now();
 	#waiters = [];
 	#timer;
 	/**
@@ -2839,7 +3164,7 @@ var CommandThrottle = class CommandThrottle {
 		});
 	}
 	#refill() {
-		const now = Date.now();
+		const now = performance.now();
 		const elapsed = (now - this.#lastUpdate) / 1e3;
 		this.#tokens = Math.min(this.#tokens + elapsed * CommandThrottle.TOKEN_RATE, CommandThrottle.TOKEN_MAX);
 		this.#lastUpdate = now;
@@ -3013,6 +3338,13 @@ var DEFAULT_COMMAND_TIMEOUT_MS = 1e4;
 var DISCONNECT_TIMEOUT_MS = 1e3;
 /** How long each reconnection attempt may take. */
 var RECONNECT_ATTEMPT_TIMEOUT_MS = 3e4;
+/** The `initserver` parameters a trace never sees, because they could carry a secret. */
+var SECRET_INITSERVER_PARAMS = /* @__PURE__ */ new Set([
+	"client_server_password",
+	"client_default_channel_password",
+	"client_default_token",
+	"client_key_offset"
+]);
 function newConnectAttempt() {
 	let resolve;
 	let reject;
@@ -3026,6 +3358,8 @@ function newConnectAttempt() {
 		promise,
 		signal: controller.signal,
 		settled: false,
+		trace: void 0,
+		onFail: void 0,
 		resolve() {
 			if (attempt.settled) return;
 			attempt.settled = true;
@@ -3034,12 +3368,14 @@ function newConnectAttempt() {
 		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);
 			until.finally(() => reject(error));
 		}
@@ -3086,6 +3422,10 @@ var Client = class {
 	#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;
 	/**
@@ -3106,6 +3446,8 @@ var Client = class {
 	* 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;
 	/**
@@ -3141,6 +3483,7 @@ var Client = class {
 		this.#socketFactory = options.socketFactory;
 		this.#fileTransferSocketFactory = options.fileTransferSocketFactory;
 		this.#reconnectOptions = options.reconnect;
+		this.#trace = options.trace === void 0 ? void 0 : { ...options.trace };
 		this.#crypt = new Crypt(identity);
 		this.#handler = this.#newHandler();
 		const self = this;
@@ -3175,7 +3518,8 @@ var Client = class {
 			set capabilities(value) {
 				self.#capabilities = value;
 			},
-			markConnected: () => this.#markConnected(),
+			markConnected: (initServer) => this.#markConnected(initServer),
+			markHandshakeDone: (serverPublicKey) => this.#markHandshakeDone(serverPublicKey),
 			execNoWait: (command) => this.#execNoWait(command, void 0, true),
 			handlePacket: (packet) => this.#handlePacket(packet)
 		};
@@ -3214,6 +3558,9 @@ var Client = class {
 	* 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;
@@ -3226,14 +3573,61 @@ var Client = class {
 		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
+		}));
 		const onAbort = () => this.#failConnection(abortReason(signal));
 		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);
+					if (trace.phase === ConnectPhase.Open) trace.phase = ConnectPhase.Handshake;
 				}
 			} catch (error) {
 				this.#failConnection(error);
@@ -3275,14 +3669,26 @@ var Client = class {
 	}
 	async #leave(wasConnected, signal) {
 		this.#logger.info("disconnecting from server");
-		if (wasConnected) try {
-			await this.#exec("clientdisconnect reasonmsg=Shutdown", {
+		if (wasConnected) {
+			this.#callHook(this.#trace?.disconnectStart, () => ({}));
+			const goodbyeStarted = performance.now();
+			const left = new Promise((resolve) => {
+				this.#goodbyeAnswered = () => resolve(true);
+			});
+			const answered = this.#exec("clientdisconnect reasonmsg=Shutdown", {
 				signal,
 				timeout: DISCONNECT_TIMEOUT_MS
-			}, true);
-		} catch {}
+			}, true).then(() => true, () => false);
+			const acknowledged = await Promise.race([answered, left]);
+			this.#goodbyeAnswered = void 0;
+			this.#callHook(this.#trace?.disconnectDone, () => ({
+				acknowledged,
+				durationMs: performance.now() - goodbyeStarted
+			}));
+		}
 		this.#handler.close();
 		this.#cmdTrack.reset(new NotConnectedError());
+		this.#endSession(void 0);
 		await this.#announceDisconnected(void 0);
 	}
 	/** `await using client = …` disconnects when the scope ends. */
@@ -3424,67 +3830,95 @@ var Client = class {
 	* ```
 	*
 	* 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(event, options = {}) {
 		const { signal } = options;
 		const buffered = [];
-		let wake;
+		const waiting = [];
 		let ended = false;
+		let aborted = false;
+		const finishWaiting = () => {
+			for (const waiter of waiting.splice(0)) waiter.resolve({
+				value: void 0,
+				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);
-			wake?.();
 		}));
 		const stopOnDisconnect = event === "disconnected" ? void 0 : this.on("disconnected", () => {
-			ended = true;
-			stopListening();
-			wake?.();
+			cleanup();
+			finishWaiting();
 		});
 		const cleanup = () => {
 			ended = true;
 			stopListening();
 			stopOnDisconnect?.();
 			signal?.removeEventListener("abort", abort);
-			wake?.();
 		};
 		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 = {
-			async next() {
-				while (buffered.length === 0 && !ended) {
-					await new Promise((resolve) => wake = resolve);
-					wake = void 0;
-				}
-				if (buffered.length > 0) return {
+			next() {
+				if (aborted) return Promise.reject(abortReason(signal));
+				if (buffered.length > 0) return Promise.resolve({
 					value: buffered.shift(),
 					done: false
-				};
-				cleanup();
-				return {
-					value: void 0,
-					done: true
-				};
+				});
+				if (ended) {
+					cleanup();
+					return Promise.resolve({
+						value: void 0,
+						done: true
+					});
+				}
+				return new Promise((resolve, reject) => waiting.push({
+					resolve,
+					reject
+				}));
 			},
-			async return() {
+			return() {
 				buffered.length = 0;
 				cleanup();
-				return {
+				finishWaiting();
+				return Promise.resolve({
 					value: void 0,
 					done: true
-				};
+				});
 			},
 			[Symbol.asyncIterator]() {
 				return iterator;
@@ -3555,12 +3989,108 @@ var Client = class {
 			socketFactory: this.#fileTransferSocketFactory
 		});
 	}
-	#markConnected() {
+	#markConnected(initServer = {}) {
 		if (this.#status !== ClientStatus.Connecting || this.#attempt.settled) return;
 		this.#status = ClientStatus.Connected;
 		this.#attempt.resolve();
+		const trace = this.#attempt.trace;
+		if (trace !== void 0) {
+			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", void 0);
 	}
+	/** The socket is open: the attempt's handshake begins. */
+	#markConnectDone(socket) {
+		const trace = this.#attempt.trace;
+		if (trace === void 0 || 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 !== void 0) localAddr = joinHostPort(local.address, String(local.port));
+			} catch {}
+			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 === void 0 || 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,
+				resends: this.#handler.resends,
+				serverPublicKey
+			};
+		});
+	}
+	#markWelcomeDone() {
+		const trace = this.#attempt.trace;
+		if (trace === void 0 || !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 === void 0) return;
+		this.#session = void 0;
+		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);
+	}
 	#newHandler() {
 		const handler = new PacketHandler(this.#crypt, this.#logger, this.#socketFactory);
 		handler.onPacket = (p) => {
@@ -3569,6 +4099,9 @@ var Client = class {
 		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);
 		};
@@ -3591,23 +4124,36 @@ var Client = class {
 		const timer = setTimeout(() => budget.abort(new TeamspeakError("address resolution took too long")), RESOLVE_BUDGET_MS);
 		const lookup = AbortSignal.any([signal, budget.signal]);
 		try {
-			return (await abortable(this.#resolver.resolve(this.#addr, { signal: lookup }), lookup))[0]?.addr ?? fallback;
+			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: void 0
+			};
 		} catch (error) {
 			signal.throwIfAborted();
-			this.#logger.warn("address resolution failed, falling back to direct", { error: String(budget.signal.aborted ? budget.signal.reason : error) });
-			return fallback;
+			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 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) {
 		if (this.#status !== ClientStatus.Connected) {
-			this.#failConnection(error instanceof CryptoInitError ? error : new CryptoInitError("the handshake failed on a malformed packet", { cause: error }));
+			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) });
@@ -3674,8 +4220,14 @@ var Client = class {
 		}
 		if (cmd.name === "channellistfinished") {
 			this.#cmdTrack.signalWelcomeComplete();
+			this.#markWelcomeDone();
 			return;
 		}
+		if (cmd.name === "channellist") {
+			const trace = this.#attempt.trace;
+			if (trace !== void 0 && !trace.welcomeDone) trace.channels++;
+		}
+		if (cmd.name === "notifyclientleftview" && this.#goodbyeAnswered !== void 0 && cmd.params["clid"] === String(this.#clid)) this.#goodbyeAnswered();
 		if (cmd.name.startsWith("notify")) {
 			if (this.#cmdTrack.expects(cmd.name)) {
 				this.#cmdTrack.buffer(cmd.params, cmd.name);
@@ -3786,7 +4338,7 @@ var Client = class {
 	*/
 	#dropVoice() {
 		this.#voiceDropped++;
-		const now = Date.now();
+		const now = performance.now();
 		if (now - this.#voiceDropWarnedAt < VOICE_DROP_WARN_INTERVAL_MS) return;
 		this.#voiceDropWarnedAt = now;
 		this.#logger.warn("voice dropped: listeners are not keeping up", { dropped: this.#voiceDropped });
@@ -3860,6 +4412,7 @@ var Client = class {
 		this.#status = ClientStatus.Disconnected;
 		const cause = err ?? new TeamspeakError("connection closed");
 		this.#lastDrop = cause;
+		this.#endSession(cause);
 		this.#announceDisconnected(cause);
 		this.#scheduleReconnect(cause).catch((error) => {
 			this.#logger.error("reconnecting failed", { error: String(error) });
@@ -3882,14 +4435,20 @@ var Client = class {
 		this.#reconnecting = true;
 		const stop = new AbortController();
 		this.#stopReconnecting = stop;
+		let made = 0;
+		let stoppedBy;
 		try {
 			for (let attempt = 1; policy.maxAttempts === 0 || attempt <= policy.maxAttempts; attempt++) {
-				if (this.#stopped) return;
+				if (this.#stopped) {
+					stoppedBy = { cause: void 0 };
+					return;
+				}
 				let retry;
 				try {
 					retry = shouldRetry(err, attempt);
 				} catch (error) {
 					this.#logger.error("shouldRetry threw; not reconnecting", { error: String(error) });
+					stoppedBy = { cause: err };
 					return;
 				}
 				if (!retry) {
@@ -3897,6 +4456,7 @@ var Client = class {
 						attempt,
 						reason: err.message
 					});
+					stoppedBy = { cause: err };
 					return;
 				}
 				const delay = backoffDelay(policy, attempt);
@@ -3904,14 +4464,23 @@ var Client = class {
 					attempt,
 					delayMs: delay
 				});
+				this.#callHook(this.#trace?.reconnectScheduled, () => ({
+					attempt,
+					delayMs: delay,
+					cause: err
+				}));
 				await sleep(delay, stop.signal);
-				if (this.#stopped) return;
+				if (this.#stopped) {
+					stoppedBy = { cause: void 0 };
+					return;
+				}
 				if (this.#status !== ClientStatus.Disconnected) {
 					this.#logger.info("reconnect loop ended: connected by other means", { attempt });
 					return;
 				}
 				try {
-					await this.connect({ signal: AbortSignal.timeout(RECONNECT_ATTEMPT_TIMEOUT_MS) });
+					made++;
+					await this.#connect({ signal: AbortSignal.timeout(RECONNECT_ATTEMPT_TIMEOUT_MS) }, attempt, true);
 					if (this.status === ClientStatus.Connected) {
 						this.#logger.info("reconnected", { attempt });
 						return;
@@ -3919,11 +4488,19 @@ var Client = class {
 					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 !== void 0) {
+				const { cause } = stoppedBy;
+				this.#callHook(this.#trace?.reconnectStopped, () => ({
+					attempts: made,
+					cause
+				}));
+			}
 			this.#reconnecting = false;
 			if (this.#stopReconnecting === stop) this.#stopReconnecting = void 0;
 		}
@@ -3944,7 +4521,7 @@ var Client = class {
 		if (this.#status === ClientStatus.Disconnected) return;
 		this.#status = ClientStatus.Disconnected;
 		this.#handler.close();
-		this.#announceDisconnected(error instanceof Error ? error : new TeamspeakError(String(error)));
+		this.#announceDisconnected(error instanceof Error ? error : new TeamspeakError(String(error), { cause: error }));
 	}
 };
 function kickedEvent(event) {
@@ -3991,6 +4568,6 @@ async function unsubscribeAllChannels(client, options) {
 	await client.send({ command: "channelunsubscribeall" }, options);
 }
 //#endregion
-export { AlreadyConnectedError, Client, ClientStatus, ConnectionTimeoutError, CryptoInitError, FileTransferError, Identity, InvalidAddressError, InvalidIdentityError, RemovedError, backoffDelay, commandChannel, defaultBackoffPolicy, defaultShouldRetry, dialFileTransfer, downloadFileData, generateIdentity, generateIdentitySync, getChannelDescription, packetChannel, parseIdentity, subscribeAllChannels, subscribeChannel, uidFromPublicKey, unknownServerCapabilities, unsubscribeAllChannels, unsubscribeChannel, uploadFileData };
+export { AlreadyConnectedError, Client, ClientStatus, ConnectPhase, ConnectionTimeoutError, FileTransferError, HandshakeError, Identity, InvalidAddressError, InvalidIdentityError, RemovedError, backoffDelay, commandChannel, defaultBackoffPolicy, defaultShouldRetry, dialFileTransfer, downloadFileData, generateIdentity, generateIdentitySync, getChannelDescription, packetChannel, parseIdentity, subscribeAllChannels, subscribeChannel, uidFromPublicKey, unknownServerCapabilities, unsubscribeAllChannels, unsubscribeChannel, uploadFileData };
 
 //# sourceMappingURL=index.js.map