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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@honeybbq/teamspeak",
-  "version": "1.0.0-beta.21",
+  "version": "1.0.0-beta.23",
   "description": "TeamSpeak SDK for TypeScript: an independent voice client for Node.js, and the typed commands, ids and errors every connection shares",
   "keywords": [
     "client",
@@ -71,23 +71,24 @@
     "@changesets/changelog-github": "^1.0.1",
     "@changesets/cli": "^3.0.3",
     "@honeybbq/teamspeak": "link:.",
-    "@microsoft/api-extractor": "7.59.4",
-    "@types/node": "^26.6.5",
+    "@microsoft/api-extractor": "7.60.1",
+    "@types/node": "^26.6.6",
     "@types/ssh2": "^1.15.6",
+    "@vitest/coverage-v8": "5.0.5",
     "fast-check": "^4.10.2",
-    "oxfmt": "^0.73.0",
-    "oxlint": "^1.88.0",
-    "oxlint-tsgolint": "^7.0.2004",
+    "oxfmt": "^0.75.0",
+    "oxlint": "^1.90.0",
+    "oxlint-tsgolint": "^7.0.2005",
     "publint": "^0.3.25",
     "ssh2": "^1.17.0",
-    "tsx": "^4.21.0",
+    "tsx": "^4.23.15",
     "typedoc": "0.28.20",
     "typedoc-material-theme": "^1.4.1",
     "typescript": "^7.0.2",
-    "typescript-api": "npm:typescript@^5.9.3",
-    "vite": "^8.3.4",
+    "typescript-api": "npm:typescript@^6.0.3",
+    "vite": "^8.3.5",
     "vitest": "^5.0.5",
-    "werift": "^0.25.1"
+    "werift": "^0.25.2"
   },
   "peerDependencies": {
     "ssh2": "^1.17.0"
@@ -103,6 +104,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest run --project @honeybbq/teamspeak --project scripts",
+    "test:coverage": "vitest run --coverage --project @honeybbq/teamspeak --project scripts",
     "test:watch": "vitest",
     "lint": "oxlint --deny-warnings .",
     "fmt": "oxfmt .",

package/src/client/crypto/identity.ts

@@ -246,6 +246,13 @@ function generateKey(): KeyObject {
   return generateKeyPairSync("ec", { namedCurve: "prime256v1" }).privateKey;
 }
 
+/** The values of the table below, before freezing. */
+const uidAlgorithmValues = {
+  /** SHA-1, 20 bytes: a TeamSpeak 3 server. */
+  SHA1: "sha1",
+  /** SHA-256, 32 bytes: a TeamSpeak 6 server. */
+  SHA256: "sha256",
+} as const;
 /**
  * The hash a server uses for `client_unique_identifier`, keyed by the server's
  * major version.
@@ -254,16 +261,20 @@ function generateKey(): KeyObject {
  * 6 switched to SHA-256 (32 bytes). The algorithm is not negotiable on the
  * wire, so a client that guesses wrong computes a UID that matches nothing the
  * server ever sends — self-identification by UID silently fails.
- *
- * May gain members in a minor release, should a server generation change the
- * hash again: a `switch` over it needs a default case.
  */
-export type UIDAlgorithm = "sha1" | "sha256";
+export const UIDAlgorithm: typeof uidAlgorithmValues =
+  /* @__PURE__ */ Object.freeze(uidAlgorithmValues);
+/**
+ * One of {@link UIDAlgorithm}. May gain members in a minor release, should a
+ * server generation change the hash again: a `switch` over it needs a default
+ * case.
+ */
+export type UIDAlgorithm = (typeof UIDAlgorithm)[keyof typeof UIDAlgorithm];
 
 /** Pick the UID hash from a `virtualserver_version` string, e.g. "6.0.0-beta13.1". */
 export function uidAlgorithmForVersion(version: string): UIDAlgorithm {
   const major = Number.parseInt(version, 10);
-  return Number.isNaN(major) || major < 6 ? "sha1" : "sha256";
+  return Number.isNaN(major) || major < 6 ? UIDAlgorithm.SHA1 : UIDAlgorithm.SHA256;
 }
 
 /**

package/src/client/crypto/index.ts

@@ -9,7 +9,7 @@ export {
   hash512,
   importPublicKey,
 } from "./identity.js";
-export type { UIDAlgorithm } from "./identity.js";
+export { UIDAlgorithm } from "./identity.js";
 export { Crypt } from "./crypt.js";
 export type { KeyNonce } from "./crypt.js";
 export { EAX, aesCmac } from "./eax.js";

package/src/client/discovery/resolver.ts

@@ -1,11 +1,15 @@
 import { resolveSrv } from "node:dns/promises";
 import { createConnection } from "node:net";
-import type { ResolvedAddr } from "../types.js";
+import { ResolveSource } from "../types.js";
+import type { AddrResolver, ResolvedAddr } from "../types.js";
 import { isIpAddress, joinHostPort, splitHostPort } from "../address.js";
 import { abortable } from "../abort.js";
+import { TeamspeakError } from "@honeybbq/teamspeak";
 import { InvalidAddressError } from "../errors.js";
 
 const TS_DNS_DEFAULT_PORT = 41144;
+/** What a TSDNS entry has for a port to say: the one the user gave. */
+const PORT_PLACEHOLDER = ":$PORT";
 const NICKNAME_LOOKUP_URL = "https://named.myteamspeak.com/lookup";
 const CACHE_TTL_MS = 10 * 60 * 1000;
 /**
@@ -29,14 +33,31 @@ export const MAX_DISCOVERY_RESPONSE: number = 8 * 1024;
 export interface ResolverOptions {
   /** Look dot-less names up at named.myteamspeak.com; off by default. */
   readonly nicknameLookup?: boolean | undefined;
+  /**
+   * The nickname lookup endpoint, an http: or https: URL; the default is
+   * `https://named.myteamspeak.com/lookup`. Used only with `nicknameLookup`:
+   * setting it does not turn the lookup on. For a test double or a mirror of
+   * the service. The name is sent as the `name` query parameter, and the first
+   * line of the answer is the address. A URL that is not http: or https: throws
+   * a TypeError.
+   */
+  readonly nicknameService?: string | URL | undefined;
 }
 
-export class Resolver {
+/**
+ * The resolver a Client uses unless it is given another. It resolves as the
+ * TeamSpeak application does, so on its own it shows where an address leads:
+ * `await new Resolver().resolve("ts.example.com")`. Answers are kept for ten
+ * minutes.
+ */
+export class Resolver implements AddrResolver {
   readonly #cache = new Map<string, ResolvedAddr[]>();
   readonly #nicknameLookup: boolean;
+  readonly #nicknameService: URL;
 
   constructor(options: ResolverOptions = {}) {
     this.#nicknameLookup = options.nicknameLookup ?? false;
+    this.#nicknameService = parseNicknameService(options.nicknameService ?? NICKNAME_LOOKUP_URL);
   }
 
   /**
@@ -58,7 +79,7 @@ export class Resolver {
       options.signal?.throwIfAborted();
       if (!budget.aborted) throw error;
       const { host, port } = splitHostPort(inputAddr);
-      return [{ addr: joinHostPort(host, port), source: "Direct" }];
+      return [{ addr: joinHostPort(host, port), source: ResolveSource.Direct }];
     }
   }
 
@@ -73,14 +94,14 @@ export class Resolver {
     const { host, port } = splitHostPort(inputAddr);
 
     if (isIpAddress(host)) {
-      return [{ addr: joinHostPort(host, port), source: "Direct" }];
+      return [{ addr: joinHostPort(host, port), source: ResolveSource.Direct }];
     }
 
     // A dot-less name may be a server nickname, which only the TeamSpeak
     // service can answer: asking it sends the name to a third party, so it is
     // opt-in. Otherwise the name is resolved like any host.
     if (nicknames && this.#nicknameLookup && !host.includes(".") && host !== "localhost") {
-      const nickAddr = await resolveNickname(host, signal);
+      const nickAddr = await resolveNickname(host, this.#nicknameService, signal);
       signal.throwIfAborted();
       if (nickAddr) return this.#resolve(nickAddr, signal, false);
     }
@@ -92,20 +113,28 @@ export class Resolver {
     const domainList = getDomainList(host);
 
     // TSDNS via SRV _tsdns._tcp.<domain>
-    const tsdnsSrv = await this.#resolveTSDNSSRV(domainList, host, signal);
-    if (tsdnsSrv) {
-      return this.#setCache(inputAddr, [{ addr: tsdnsSrv, source: "TSDNS-SRV" }]);
+    const tsdnsSrv = await this.#resolveTSDNSSRV(domainList, host, port, signal);
+    if (tsdnsSrv.length > 0) {
+      return this.#setCache(
+        inputAddr,
+        tsdnsSrv.map((addr) => ({ addr, source: ResolveSource.TSDNSSRV })),
+      );
     }
 
     // TSDNS direct :41144
-    const tsdnsDirect = await this.#resolveTSDNSDirect(domainList, host, signal);
-    if (tsdnsDirect) {
-      return this.#setCache(inputAddr, [{ addr: tsdnsDirect, source: "TSDNS-Direct" }]);
+    const tsdnsDirect = await this.#resolveTSDNSDirect(domainList, host, port, signal);
+    if (tsdnsDirect.length > 0) {
+      return this.#setCache(
+        inputAddr,
+        tsdnsDirect.map((addr) => ({ addr, source: ResolveSource.TSDNSDirect })),
+      );
     }
 
     signal.throwIfAborted();
     // Plain DNS fallback
-    const fallback: ResolvedAddr[] = [{ addr: joinHostPort(host, port), source: "Direct" }];
+    const fallback: ResolvedAddr[] = [
+      { addr: joinHostPort(host, port), source: ResolveSource.Direct },
+    ];
     return this.#setCache(inputAddr, fallback);
   }
 
@@ -130,7 +159,7 @@ export class Resolver {
       if (!srvs || srvs.length === 0) return null;
       return orderSrvRecords(srvs).map((srv) => ({
         addr: joinHostPort(srv.name.replace(/\.$/, ""), String(srv.port)),
-        source: "SRV",
+        source: ResolveSource.SRV,
       }));
     } catch {
       return null;
@@ -140,40 +169,77 @@ export class Resolver {
   async #resolveTSDNSSRV(
     domains: string[],
     queryHost: string,
+    port: string,
     signal?: AbortSignal,
-  ): Promise<string | null> {
+  ): Promise<string[]> {
     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 orderSrvRecords(srvs)) {
           const tsdnsAddr = joinHostPort(srv.name.replace(/\.$/, ""), String(srv.port));
-          const result = await queryTSDNS(tsdnsAddr, queryHost, signal);
-          if (result) return result;
+          const result = await askTSDNS(tsdnsAddr, queryHost, port, signal);
+          if (result.length > 0) return result;
         }
       } catch {
         continue;
       }
     }
-    return null;
+    return [];
   }
 
   async #resolveTSDNSDirect(
     domains: string[],
     queryHost: string,
+    port: string,
     signal?: AbortSignal,
-  ): Promise<string | null> {
+  ): Promise<string[]> {
     // Asked at once rather than in turn, so the probes cost one timeout in
     // all; the most specific domain's answer wins.
     const answers = await Promise.all(
       domains.map((domain) =>
-        queryTSDNS(joinHostPort(domain, String(TS_DNS_DEFAULT_PORT)), queryHost, signal),
+        askTSDNS(joinHostPort(domain, String(TS_DNS_DEFAULT_PORT)), queryHost, port, signal),
       ),
     );
-    return answers.find((answer) => answer !== null) ?? null;
+    return answers.find((answer) => answer.length > 0) ?? [];
   }
 }
 
+/**
+ * Ask one TSDNS server; a server that fails to answer is one with no answer,
+ * so it never fails the resolution.
+ */
+async function askTSDNS(
+  server: string,
+  host: string,
+  port: string,
+  signal?: AbortSignal,
+): Promise<string[]> {
+  try {
+    return normalizeTSDNSEntries(await lookupTSDNS(server, host, { signal }), port);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Make each entry of a TSDNS answer a `host:port`, as TeamSpeak reads it: an
+ * entry without a port means 9987, and the port `$PORT` means `port`, the one
+ * the address being resolved had.
+ *
+ * @internal
+ */
+export function normalizeTSDNSEntries(entries: readonly string[], port: string): string[] {
+  return entries.map((entry) => {
+    if (entry.endsWith(PORT_PLACEHOLDER)) {
+      const host = splitHostPort(entry.slice(0, -PORT_PLACEHOLDER.length)).host;
+      return joinHostPort(host, port);
+    }
+    const target = splitHostPort(entry, "9987");
+    return joinHostPort(target.host, target.port);
+  });
+}
+
 // ---- Helpers ----------------------------------------------------------------
 
 /** The part of an SRV record that decides the order they are tried in. */
@@ -228,13 +294,27 @@ export function orderSrvRecords<T extends SrvRecord>(
   return ordered;
 }
 
+function parseNicknameService(service: string | URL): URL {
+  let url: URL;
+  try {
+    url = new URL(service);
+  } catch {
+    throw new TypeError(`nicknameService is not a URL: ${String(service)}`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new TypeError(`nicknameService is an http: or https: URL, not ${url.protocol}`);
+  }
+  return url;
+}
+
 /** @internal Ask the nickname service for `nickname`'s address. */
 export async function resolveNickname(
   nickname: string,
+  service: URL,
   signal?: AbortSignal,
 ): Promise<string | null> {
   try {
-    const url = new URL(NICKNAME_LOOKUP_URL);
+    const url = new URL(service);
     url.searchParams.set("name", nickname);
     const init: RequestInit = signal ? { signal } : {};
     const resp = await fetch(url.toString(), init);
@@ -267,54 +347,82 @@ async function readLimited(resp: Response, limit: number): Promise<string> {
   return Buffer.concat(chunks).toString("utf8");
 }
 
-/** @internal Ask the TSDNS server at `tsdnsAddr` for `queryHost`'s address. */
-export function queryTSDNS(
-  tsdnsAddr: string,
-  queryHost: string,
-  signal?: AbortSignal,
-): Promise<string | null> {
-  const [host, portStr] = splitHostPortParts(tsdnsAddr);
-  const port = parseInt(portStr, 10);
-
-  return new Promise((resolve) => {
-    if (signal?.aborted) return resolve(null);
-    const finish = (answer: string | null): void => {
+/**
+ * Ask a TSDNS server where `host` is. The answer is the server's targets in
+ * its order and as it sent them: an entry may have no port, which TeamSpeak
+ * takes as 9987, or the literal port `$PORT`, the port the user gave (9987 by
+ * default). {@link Resolver} applies both. A name the server has no record for
+ * gives an empty list.
+ *
+ * The answer ends at its first line break or when the server closes the
+ * connection, whichever comes first. It rejects when the connection fails,
+ * when no answer completes within three seconds or grows past 8 KiB, and with
+ * the signal's reason when it aborts.
+ *
+ * @param server - The TSDNS server, `host` or `host:port`; the port defaults to 41144.
+ * @param host - The name to look up; it is sent without a port.
+ */
+export function lookupTSDNS(
+  server: string,
+  host: string,
+  options: { readonly signal?: AbortSignal | undefined } = {},
+): Promise<string[]> {
+  const { signal } = options;
+  const target = splitHostPort(server, String(TS_DNS_DEFAULT_PORT));
+  const port = parseInt(target.port, 10);
+
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(signal.reason);
+    const chunks: Buffer[] = [];
+    let size = 0;
+    let done = false;
+    const finish = (error: unknown, answer?: string[]): void => {
+      if (done) return;
+      done = true;
       clearTimeout(timeout);
       signal?.removeEventListener("abort", onAbort);
       socket.destroy();
-      resolve(answer);
+      if (error !== undefined) reject(error);
+      else resolve(answer ?? []);
     };
-    const onAbort = (): void => finish(null);
-    const timeout = setTimeout(() => finish(null), TSDNS_TIMEOUT_MS);
+    const answerOf = (bytes: Buffer): string[] => {
+      const line = bytes.toString("utf8").trim();
+      return !line || line === "404" || line === "errors" ? [] : line.split(/\s+/);
+    };
+    const timedOut = (): void =>
+      finish(new TeamspeakError(`the TSDNS server ${server} did not answer in time`));
+    const onAbort = (): void => finish(signal?.reason);
+    const timeout = setTimeout(timedOut, TSDNS_TIMEOUT_MS);
 
-    const socket = createConnection({ host, port, timeout: 2_000 }, () => {
-      socket.write(`${queryHost}\n`);
+    const socket = createConnection({ host: target.host, port, timeout: 2_000 }, () => {
+      socket.write(`${host}\n`);
     });
 
-    let buf = "";
     socket.on("data", (chunk: Buffer) => {
-      buf += chunk.toString("latin1");
-      const idx = buf.indexOf("\n");
+      chunks.push(chunk);
+      size += chunk.length;
+      const all = chunks.length === 1 ? chunks[0]! : Buffer.concat(chunks);
+      chunks.length = 0;
+      chunks.push(all);
+      const idx = all.indexOf(0x0a);
       if (idx >= 0 && idx < MAX_DISCOVERY_RESPONSE) {
-        const line = Buffer.from(buf.slice(0, idx), "latin1").toString("utf8").trim();
-        finish(!line || line === "404" || line === "errors" ? null : line);
-      } else if (buf.length >= MAX_DISCOVERY_RESPONSE) {
+        finish(undefined, answerOf(all.subarray(0, idx)));
+      } else if (size >= MAX_DISCOVERY_RESPONSE) {
         // No answer is that long.
-        finish(null);
+        finish(
+          new TeamspeakError(
+            `the TSDNS server ${server} sent ${MAX_DISCOVERY_RESPONSE} bytes without ending its answer`,
+          ),
+        );
       }
     });
-
-    socket.on("error", () => finish(null));
-    socket.on("timeout", () => finish(null));
+    socket.on("end", () => finish(undefined, answerOf(Buffer.concat(chunks))));
+    socket.on("error", (error) => finish(error));
+    socket.on("timeout", timedOut);
     signal?.addEventListener("abort", onAbort, { once: true });
   });
 }
 
-function splitHostPortParts(addr: string): [string, string] {
-  const { host, port } = splitHostPort(addr);
-  return [host, port];
-}
-
 function getDomainList(host: string): string[] {
   const parts = host.split(".");
   const list: string[] = [];

package/src/client/handshake/license.ts

@@ -78,6 +78,7 @@ function parseLicenseBlock(data: Uint8Array): { block: LicenseBlock; consumed: n
   if (data.length < MIN_BLOCK_LEN) throw new Error("license too short");
   if (data[0] !== 0) throw new Error(`wrong key kind in license: ${data[0]}`);
 
+  // oxlint-disable-next-line typescript/no-unsafe-enum-assignment -- read off the wire; parseBlockPayload refuses a value no member names
   const blockType = data[33] as LicenseBlockType;
 
   // Timestamps are seconds since Unix epoch offset by 0x50e22700

package/src/client/index.ts

@@ -10,9 +10,13 @@
 
 // The client
 export { Client } from "./client.js";
-export { EventName, GroupWhisperType, GroupWhisperScope } from "./types.js";
+export { EventName, GroupWhisperType, GroupWhisperScope, ResolveSource } from "./types.js";
 
-export type { ServerView, ViewChangedEvent, ViewReadyEvent, ViewStatus } from "./view.js";
+export { Resolver, lookupTSDNS } from "./discovery/resolver.js";
+export type { ResolverOptions } from "./discovery/resolver.js";
+
+export { ViewStatus } from "./view.js";
+export type { ServerView, ViewChangedEvent, ViewReadyEvent } from "./view.js";
 
 export type {
   EventMap,
@@ -47,11 +51,15 @@ export * from "./api/avatars.js";
 export * from "./api/files.js";
 
 // File transfer data
-export { dialFileTransfer, uploadFileData, downloadFileData } from "./transfer.js";
+export {
+  dialFileTransfer,
+  uploadFileData,
+  downloadFileData,
+  FileTransferStage,
+} from "./transfer.js";
 export type {
   FileTransferOptions,
   FileTransferTrace,
-  FileTransferStage,
   FileTransferDialStartInfo,
   FileTransferDialDoneInfo,
   FileTransferProgressInfo,
@@ -99,4 +107,4 @@ export {
   uidAlgorithmForVersion,
   MAX_SECURITY_LEVEL,
 } from "./crypto/index.js";
-export type { UIDAlgorithm } from "./crypto/index.js";
+export { UIDAlgorithm } from "./crypto/index.js";

package/src/client/trace.ts

@@ -44,7 +44,10 @@ export interface ResolveDoneInfo extends AttemptInfo {
   readonly addr: string;
   /** The `host:port` that will be dialled. */
   readonly target: string;
-  /** What the resolver reports as the source of the answer dialled; may be empty. */
+  /**
+   * What the resolver reports as the source of the answer dialled: one of
+   * `ResolveSource` for the built-in resolver. May be empty.
+   */
   readonly source: string;
   /** Every answer the resolver gave, in order; empty when the address is used as given. */
   readonly candidates: readonly ResolvedAddr[];

package/src/client/transfer.ts

@@ -44,8 +44,18 @@ export function failedToConnect(error: unknown): boolean {
   return typeof error === "object" && error !== null && failedBeforeConnect.has(error);
 }
 
+/** The values of the table below, before freezing. */
+const fileTransferStageValues = {
+  /** Reaching the transfer port, before the key is written. */
+  Dial: "dial",
+  /** After the connection opened, while the key or the file moved. */
+  Transfer: "transfer",
+} as const;
 /** Where a failed transfer failed. */
-export type FileTransferStage = "dial" | "transfer";
+export const FileTransferStage: typeof fileTransferStageValues =
+  /* @__PURE__ */ Object.freeze(fileTransferStageValues);
+/** One of {@link FileTransferStage}. */
+export type FileTransferStage = (typeof FileTransferStage)[keyof typeof FileTransferStage];
 
 /** The file transfer port is about to be dialled. */
 export interface FileTransferDialStartInfo {

package/src/client/transport/handler.ts

@@ -10,6 +10,7 @@ import {
   PacketType,
   PacketFlags,
   packetType,
+  packetTypeOfByte,
   packetFlags,
   buildC2SHeader,
   parseS2CHeader,
@@ -563,7 +564,7 @@ export class PacketHandler {
     if (!this.#conn) return;
     if (data.length > TAG_SIZE + HEADER_SIZE - 1) {
       this.#traffic.recordSent(
-        data[TAG_SIZE + HEADER_SIZE - 1]! & 0x0f,
+        packetTypeOfByte(data[TAG_SIZE + HEADER_SIZE - 1]!),
         data.length,
         performance.now(),
       );
@@ -597,7 +598,7 @@ export class PacketHandler {
     const parsed = parseS2CHeader(header);
     // Init1 belongs to the start of the handshake; once crypto init has
     // completed, another one can only restart a session that is already set up.
-    const parsedType: PacketType = parsed.typeFlagged & 0x0f;
+    const parsedType = packetTypeOfByte(parsed.typeFlagged);
     if (parsedType === PacketType.Init1 && this.#crypt.cryptoInitComplete) return;
 
     const p: Packet = {

package/src/client/transport/packet.ts

@@ -27,8 +27,17 @@ export interface Packet {
   receivedAt: number; // performance.now(), a monotonic clock
 }
 
+/**
+ * The packet type in the low nibble of a type byte, as it came off the wire:
+ * the nibble can also hold 9 to 15, which name no type.
+ */
+export function packetTypeOfByte(typeByte: number): PacketType {
+  // oxlint-disable-next-line typescript/no-unsafe-enum-assignment -- read off the wire, where the nibble can be any value
+  return typeByte & 0x0f;
+}
+
 export function packetType(p: Packet): PacketType {
-  return p.typeFlagged & 0x0f;
+  return packetTypeOfByte(p.typeFlagged);
 }
 
 export function packetFlags(p: Packet): number {

package/src/client/types.ts

@@ -385,6 +385,32 @@ export type EventMiddleware = (next: (event: ServerEvent) => void) => (event: Se
 
 // ---- Resolved address (from discovery) --------------------------------------
 
+/** The values of the table below, before freezing. */
+const resolveSourceValues = {
+  /** A `_ts3._udp` SRV record of the host named the address. */
+  SRV: "SRV",
+  /**
+   * A TSDNS server, found through a `_tsdns._tcp` SRV record of the host's
+   * domain, named the address.
+   */
+  TSDNSSRV: "TSDNS-SRV",
+  /** A TSDNS server on the host's domain, at its default port, named the address. */
+  TSDNSDirect: "TSDNS-Direct",
+  /**
+   * The address as given: an IP address, a name nothing else answered for, or
+   * any name once resolution ran out of time.
+   */
+  Direct: "Direct",
+} as const;
+/** How the built-in resolver found an address, as `ResolvedAddr` records it. */
+export const ResolveSource: typeof resolveSourceValues =
+  /* @__PURE__ */ Object.freeze(resolveSourceValues);
+/**
+ * One of {@link ResolveSource}. May gain members in a minor release: a
+ * `switch` over it needs a default case.
+ */
+export type ResolveSource = (typeof ResolveSource)[keyof typeof ResolveSource];
+
 /**
  * An address a server's name resolved to. Only `addr` is needed to connect;
  * the rest describes the answer.
@@ -392,7 +418,10 @@ export type EventMiddleware = (next: (event: ServerEvent) => void) => (event: Se
 export interface ResolvedAddr {
   /** The endpoint, as `host:port`. */
   readonly addr: string;
-  /** How it was found, such as `SRV`, `TSDNS-SRV`, `TSDNS-Direct` or `Direct`. */
+  /**
+   * How it was found. The built-in resolver sets one of `ResolveSource`; a
+   * plain string, since an `AddrResolver` of your own may set any.
+   */
   readonly source?: string | undefined;
   /** When the answer stops being valid; unset for no stated lifetime. */
   readonly expiry?: Date | undefined;