@honeybbq/teamspeak 0.0.1 → 1.0.0-beta.7

package/src/query/stream.ts

@@ -0,0 +1,91 @@
+import { LineReader } from "./lines.js";
+import type { QueryTransport } from "./transport.js";
+
+/**
+ * The part of a duplex byte stream a line transport uses. A `node:net` socket
+ * is one; so is an SSH shell channel, or a test double.
+ */
+export interface QueryStream {
+  /** Write bytes to the peer; `callback` runs once they are flushed, with the failure if any. */
+  write(data: string, callback: (error?: Error | null) => void): unknown;
+  /** Close the stream. */
+  end(): unknown;
+  /** Listen for each chunk received. */
+  on(event: "data", listener: (chunk: Uint8Array) => void): unknown;
+  /** Listen for a failure, which ends the connection. */
+  on(event: "error", listener: (error: Error) => void): unknown;
+  /** Listen for the stream closing. */
+  on(event: "close", listener: () => void): unknown;
+}
+
+/**
+ * A {@link QueryTransport} over a byte stream: raw TCP, or an SSH shell.
+ *
+ * Both greet with a two-line banner, `TS3` and a welcome sentence, before any
+ * answer. It is skipped, so the client sees only answers and notifications.
+ */
+export class StreamTransport implements QueryTransport {
+  /** A raw TCP connection and an SSH session both carry pushed notifications. */
+  readonly supportsNotifications = true;
+  onLine: ((line: string) => void) | null = null;
+  onClose: ((error: Error | undefined) => void) | null = null;
+
+  #stream: QueryStream;
+  #reader = new LineReader();
+  #onEnd: (() => void) | undefined;
+  /** How many of the two banner lines are still to come. */
+  #banner = 2;
+  #closing = false;
+  #ended = false;
+  #error: Error | undefined;
+
+  /**
+   * `onEnd` runs once the stream is closed, to release what the stream sits
+   * on: an SSH session's connection, say.
+   */
+  constructor(stream: QueryStream, onEnd?: () => void) {
+    this.#stream = stream;
+    this.#onEnd = onEnd;
+    stream.on("data", (chunk) => this.#handleData(chunk));
+    stream.on("error", (error) => {
+      this.#error = error;
+    });
+    stream.on("close", () => this.#handleClose());
+  }
+
+  send(line: string): Promise<void> {
+    if (this.#ended) return Promise.reject(new Error("the query connection is closed"));
+    return new Promise((resolve, reject) => {
+      this.#stream.write(`${line}\n`, (error) => (error ? reject(error) : resolve()));
+    });
+  }
+
+  close(): Promise<void> {
+    if (this.#ended) return Promise.resolve();
+    this.#closing = true;
+    // Ending the stream is not enough to hear it close. An SSH session channel
+    // is half-open, so `end()` sends EOF and stops there without reporting
+    // 'close', and the hook that releases the connection underneath would never
+    // run; the close is owed here as well as from the stream's own event.
+    this.#stream.end();
+    this.#handleClose();
+    return Promise.resolve();
+  }
+
+  #handleData(chunk: Uint8Array): void {
+    for (const line of this.#reader.push(chunk)) {
+      if (this.#banner > 0) {
+        this.#banner--;
+        continue;
+      }
+      this.onLine?.(line);
+    }
+  }
+
+  #handleClose(): void {
+    if (this.#ended) return;
+    this.#ended = true;
+    this.#onEnd?.();
+    this.onClose?.(this.#closing ? undefined : this.#error);
+  }
+}

package/src/query/tcp.ts

@@ -0,0 +1,85 @@
+import { createConnection } from "node:net";
+import type { Duplex } from "node:stream";
+import { StreamTransport } from "./stream.js";
+
+/**
+ * Opens the byte stream a raw ServerQuery connection runs over.
+ *
+ * Returns a `Duplex` rather than a `node:net` socket: naming a concrete
+ * platform type here would bind the interface to Node's socket class for good,
+ * and a caller supplying a TLS socket, a SOCKS proxy's socket or a test double
+ * has no reason to hand back that particular class.
+ */
+export type TcpConnector = (host: string, port: number) => Duplex | Promise<Duplex>;
+
+/** Where a raw ServerQuery listens. */
+export interface TcpOptions {
+  /** The server's host. */
+  readonly host: string;
+  /** The raw query port; 10011 by default. */
+  readonly port?: number | undefined;
+  /** Abandons the connection attempt. */
+  readonly signal?: AbortSignal | undefined;
+  /**
+   * Opens the connection. `net.createConnection` by default.
+   *
+   * The seam into the transport: supplying one lets an application route the
+   * session through a TLS terminator or a SOCKS proxy, or drive it from
+   * something that is not a socket at all. It is deliberately narrow, so that
+   * a later release can widen what it hands back without breaking an
+   * implementation written today.
+   */
+  readonly connect?: TcpConnector | undefined;
+}
+
+/**
+ * Open a raw ServerQuery connection (`node:net`, 10011 by default).
+ *
+ * Resolves once the stream is connected; the server's banner is read and
+ * dropped by the transport.
+ */
+export async function connectTcp(options: TcpOptions): Promise<StreamTransport> {
+  const { host, port = 10011, signal, connect = defaultConnect } = options;
+  signal?.throwIfAborted();
+  const stream = await connect(host, port);
+  await opened(stream, signal);
+  return new StreamTransport(stream);
+}
+
+/** A connected `node:net` socket, with whole lines sent as they are written. */
+function defaultConnect(host: string, port: number): Duplex {
+  const socket = createConnection({ host, port });
+  // Whole lines are sent, and a query's answers are small: no waiting to
+  // coalesce.
+  socket.setNoDelay(true);
+  return socket;
+}
+
+/**
+ * Wait until the stream is connected, if it is not already.
+ *
+ * A `Duplex` a caller handed back may be open, still opening, or a test double
+ * that is neither — `connecting` says which, and a stream without it counts as
+ * open, since nothing else could report the moment it becomes usable.
+ */
+function opened(stream: Duplex, signal: AbortSignal | undefined): Promise<void> {
+  const connecting = (stream as { readonly connecting?: boolean }).connecting;
+  if (connecting !== true) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const failed = (error: Error): void => {
+      signal?.removeEventListener("abort", onAbort);
+      reject(error);
+    };
+    const onAbort = (): void => {
+      stream.destroy();
+      failed(signal!.reason as Error);
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    stream.once("error", failed);
+    stream.once("connect", () => {
+      stream.off("error", failed);
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    });
+  });
+}

package/src/query/transport.ts

@@ -0,0 +1,35 @@
+/**
+ * The connection a ServerQuery client talks over.
+ *
+ * ServerQuery is a line protocol on three transports: raw TCP (10011), SSH
+ * (10022) and, on TeamSpeak 6, an HTTP WebQuery (10080) that frames each
+ * command as a request. The client depends on this interface only, so each
+ * transport is a separate piece, and a test or a proxy can supply its own.
+ */
+export interface QueryTransport {
+  /**
+   * Whether this connection can receive notifications at all.
+   *
+   * Raw TCP and SSH can: the server pushes `notify…` lines down the same
+   * connection whenever it likes. WebQuery cannot — it has no session for the
+   * server to push to, and refuses `servernotifyregister` with 5120 — so it
+   * reports false.
+   *
+   * A custom transport declares its own truth here rather than leaving the
+   * caller to guess: a client uses it to decide whether to register for
+   * notifications at all, and whether a listener for a server event can ever
+   * run.
+   */
+  readonly supportsNotifications: boolean;
+  /** Send one command line; the transport adds the line terminator. */
+  send(line: string): Promise<void>;
+  /**
+   * Called with each line the server sends, without its terminator, in the
+   * order received.
+   */
+  onLine: ((line: string) => void) | null;
+  /** Called once when the connection ends, with the cause unless it was `close()`. */
+  onClose: ((error: Error | undefined) => void) | null;
+  /** End the connection. */
+  close(): Promise<void>;
+}

package/src/query/web.ts

@@ -0,0 +1,195 @@
+import { request } from "node:http";
+import { TeamspeakError } from "@honeybbq/teamspeak";
+import { buildCommandOrdered, parseCommand, splitCommandRows } from "../core/internal.js";
+import type { QueryTransport } from "./transport.js";
+
+/**
+ * A WebQuery request that failed with an HTTP status and no TeamSpeak error in
+ * its answer: a wrong or missing api key, a server that is not a WebQuery. A
+ * refusal from the server itself carries a TeamSpeak code and is a
+ * `ServerError` instead.
+ */
+export class WebQueryHttpError extends TeamspeakError {
+  /** {@inheritDoc @honeybbq/teamspeak!TeamspeakError.kind} */
+  static override readonly kind: string = "WebQueryHttpError";
+  static {
+    Object.defineProperty(this.prototype, "name", {
+      value: "WebQueryHttpError",
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
+  }
+
+  /** The HTTP status. */
+  readonly status: number;
+
+  constructor(status: number, statusText: string) {
+    super(`WebQuery answered HTTP ${status}${statusText === "" ? "" : ` ${statusText}`}`);
+    this.status = status;
+  }
+}
+
+/** How a WebQuery is reached. */
+export interface WebQueryOptions {
+  /** The server's base URL, such as `http://127.0.0.1:10080`. */
+  readonly url: string;
+  /** The api key, sent as `x-api-key`. */
+  readonly apiKey: string;
+  /** The virtual server to address; `use` changes it. Unset addresses the instance. */
+  readonly serverID?: number | bigint | undefined;
+  /**
+   * The `fetch` to use. By default a small one over `node:http`: the global
+   * `fetch` refuses port 10080, WebQuery's own default, as a port the Fetch
+   * standard blocks.
+   */
+  readonly fetch?: typeof fetch | undefined;
+}
+
+/** The answer WebQuery gives: rows, and the status of the command. */
+interface WebAnswer {
+  readonly body?: unknown;
+  readonly status?: {
+    readonly code?: unknown;
+    readonly message?: unknown;
+    readonly extra_message?: unknown;
+  };
+}
+
+/**
+ * A {@link QueryTransport} over WebQuery, TeamSpeak 6's HTTP interface.
+ *
+ * Each command line becomes one request, `POST /<server>/<command>` with the
+ * parameters as JSON, and the JSON answer is turned back into what a raw
+ * connection would have sent: one line per row, then `error id=… msg=…`. The
+ * client above sees one answer shape.
+ *
+ * WebQuery has no session, so two things differ. The api key replaces `login`,
+ * which the server refuses; and `use` is answered here, by changing the server
+ * the following requests address, since the server has no `use` either. It
+ * also sends no notifications, so there is nothing to register for.
+ */
+export class WebQueryTransport implements QueryTransport {
+  /** WebQuery has no session for the server to push a notification to. */
+  readonly supportsNotifications = false;
+  onLine: ((line: string) => void) | null = null;
+  onClose: ((error: Error | undefined) => void) | null = null;
+
+  #base: string;
+  #apiKey: string;
+  #prefix: string;
+  #fetch: typeof fetch;
+  #closed = false;
+
+  constructor(options: WebQueryOptions) {
+    this.#base = options.url.replace(/\/+$/, "");
+    this.#apiKey = options.apiKey;
+    this.#prefix = options.serverID === undefined ? "" : `/${options.serverID}`;
+    this.#fetch = options.fetch ?? httpFetch;
+  }
+
+  async send(line: string): Promise<void> {
+    if (this.#closed) throw new Error("the query connection is closed");
+    const rows = splitCommandRows(line)
+      .map((row) => parseCommand(row))
+      .filter((row) => row !== null);
+    const name = rows[0]?.name ?? "";
+
+    if (name === "use") {
+      this.#use(rows[0]!.params);
+      return;
+    }
+
+    const params = rows.map((row) => ({ ...row.params }));
+    const response = await this.#fetch(`${this.#base}${this.#prefix}/${name}`, {
+      method: "POST",
+      headers: { "x-api-key": this.#apiKey, "content-type": "application/json" },
+      body: JSON.stringify(params.length === 1 ? params[0] : params),
+    });
+
+    let answer: WebAnswer | undefined;
+    try {
+      answer = (await response.json()) as WebAnswer;
+    } catch {
+      // Not JSON: nothing the server said about the command.
+    }
+    const code = answer?.status?.code;
+    if (typeof code !== "number") throw new WebQueryHttpError(response.status, response.statusText);
+
+    const body = answer?.body;
+    for (const row of Array.isArray(body) ? body : []) {
+      if (typeof row === "object" && row !== null) this.onLine?.(rowLine(row));
+    }
+    const message = answer?.status?.message;
+    const extra = answer?.status?.extra_message;
+    const tail = typeof extra === "string" && extra !== "" ? { extra_msg: extra } : {};
+    this.onLine?.(
+      buildCommandOrdered("error", [
+        ["id", String(code)],
+        ["msg", typeof message === "string" ? message : ""],
+        ...Object.entries(tail),
+      ]),
+    );
+  }
+
+  close(): Promise<void> {
+    if (this.#closed) return Promise.resolve();
+    this.#closed = true;
+    this.onClose?.(undefined);
+    return Promise.resolve();
+  }
+
+  /** `use sid=1`, or `use port=9987`, which WebQuery addresses as `/byport/9987`. */
+  #use(params: Readonly<Record<string, string>>): void {
+    const sid = params["sid"];
+    const port = params["port"];
+    if (sid !== undefined && /^\d+$/.test(sid)) this.#prefix = `/${sid}`;
+    else if (port !== undefined && /^\d+$/.test(port)) this.#prefix = `/byport/${port}`;
+    else {
+      this.onLine?.(
+        buildCommandOrdered("error", [
+          ["id", "1538"],
+          ["msg", "invalid parameter"],
+        ]),
+      );
+      return;
+    }
+    this.onLine?.("error id=0 msg=ok");
+  }
+}
+
+/** One answer row as a line of `key=value` fields; a field that is not text is written as text. */
+function rowLine(row: object): string {
+  const fields = Object.entries(row).map(
+    ([key, value]) => [key, typeof value === "string" ? value : String(value)] as const,
+  );
+  // buildCommandOrdered writes a name first; a row has none.
+  return buildCommandOrdered("", fields).slice(1);
+}
+
+/**
+ * The part of `fetch` this transport uses, over `node:http`: a POST with a
+ * string body, answered with a `Response`. Plain HTTP only, as WebQuery is.
+ */
+const httpFetch = ((url: string, init: RequestInit) =>
+  new Promise<Response>((resolve, reject) => {
+    const req = request(
+      url,
+      { method: init.method, headers: init.headers as Record<string, string> },
+      (res) => {
+        const chunks: Buffer[] = [];
+        res.on("data", (chunk: Buffer) => chunks.push(chunk));
+        res.on("error", reject);
+        res.on("end", () =>
+          resolve(
+            new Response(Buffer.concat(chunks), {
+              status: res.statusCode ?? 0,
+              statusText: res.statusMessage ?? "",
+            }),
+          ),
+        );
+      },
+    );
+    req.on("error", reject);
+    req.end(init.body as string);
+  })) as unknown as typeof fetch;