@honeybbq/teamspeak 1.0.0-beta.13 → 1.0.0-beta.14

package/src/core/api/moderation.ts

@@ -10,6 +10,8 @@ import {
   firstRow,
   exec,
   query,
+  queryRows,
+  continueOnErrorParams,
   list,
   encodeFields,
   nonEmpty,
@@ -22,7 +24,7 @@ import {
   durationMs,
   SECOND,
 } from "./command.js";
-import type { Params, WireNames } from "./command.js";
+import type { BatchOptions, Params, WireNames } from "./command.js";
 import type { CommandExecutor, CommandOptions, ParamValue } from "../command/request.js";
 import type { BanID, ClientDBID, ClientID, MessageID, UID } from "../command/ids.js";
 import { asBanID, asClientDBID, asMessageID, asUID } from "../command/ids.js";
@@ -250,8 +252,11 @@ export async function addBan(
  *
  * Measured on TS3 3.13.8 and TS6 beta13.1: two bans, one for the uid and one
  * for the address. TS6 has also answered with no `banid` at all though both
- * bans were made (about once in a hundred calls over SSH and WebQuery), so an
- * empty result does not mean no ban. A caller that must undo the ban lists the
+ * bans were made (about once in a hundred calls over WebQuery), so an empty
+ * result does not mean no ban, and no lookup of the ids is made: a ban has no
+ * field that ties it to this call. Over SSH, TS6 may write the `banid` rows
+ * after the `error` line; the ServerQuery client waits briefly for them, so
+ * they are not lost to that. A caller that must undo the ban lists the
  * bans before and after and removes what is new: a ban on the address refuses
  * every later connection from it.
  */
@@ -269,6 +274,50 @@ export async function banClient(
   return rows.flatMap((row) => (str(row, "banid") === "" ? [] : [asBanID(big(row, "banid"))]));
 }
 
+/** How {@link banClients} bans, and whether it goes on past a failure. */
+export interface BanClientsOptions extends BanClientOptions, BatchOptions {}
+
+/**
+ * Ban several connected clients by clid, in one command, such as
+ * `banclient time=60 clid=5|clid=6`, and return the id of every ban the server
+ * reports. With no ids nothing is sent and the result is `[]`.
+ *
+ * Each client costs the bans {@link banClient} describes; clients that share an
+ * address share one address ban, so two clients behind one address made three
+ * ids. The voice protocol reports no ids, so there this resolves to `[]` even
+ * when bans were made.
+ *
+ * The server reports one answer for the whole call, never one per client: the
+ * ids of the bans made, then success, or one error. Measured on TeamSpeak 3
+ * 3.13.8 and TeamSpeak 6 beta13.1, over raw ServerQuery, SSH, WebQuery and the
+ * voice protocol alike:
+ *
+ * - Without `continueOnError`, the server first checks that every id names a
+ *   client: one that does not (512) refuses the call and nothing is banned.
+ *   Past that, clients are banned in the order given and a failure for one
+ *   (insufficient permissions, 2568) stops the call: the clients before it are
+ *   banned, the ones after it are not, and the error is that client's.
+ * - With it (`-continueonerror`), a client that cannot be banned is skipped,
+ *   the others are banned, the ids of the bans made are returned, and the
+ *   answer is success even when none could be banned.
+ *
+ * A client that is banned is disconnected.
+ */
+export async function banClients(
+  client: CommandExecutor,
+  clientIDs: readonly ClientID[],
+  options: BanClientsOptions = {},
+): Promise<BanID[]> {
+  const rows = await queryRows(
+    client,
+    "banclient",
+    [...continueOnErrorParams(options), ...encodeFields<BanClientOptions>(options, banClientNames)],
+    clientIDs.map((clid) => [["clid", clid]]),
+    options,
+  );
+  return rows.flatMap((row) => (str(row, "banid") === "" ? [] : [asBanID(big(row, "banid"))]));
+}
+
 /** Remove a ban. */
 export async function deleteBan(
   client: CommandExecutor,

package/src/core/api/server.ts

@@ -13,6 +13,8 @@ import {
   U16,
   firstRow,
   exec,
+  execRows,
+  continueOnErrorParams,
   query,
   list,
   encodeFields,
@@ -28,7 +30,13 @@ import {
   durationMs,
   SECOND,
 } from "./command.js";
-import type { PermissionEntry, WireNames } from "./command.js";
+import type {
+  BatchOptions,
+  Params,
+  PermissionEntry,
+  PermissionValue,
+  WireNames,
+} from "./command.js";
 import type { CommandExecutor, CommandOptions } from "../command/request.js";
 import type {
   ChannelID,
@@ -560,6 +568,67 @@ export async function getServerGroupsByClient(
   return rows.map((row) => ({ id: asServerGroupID(big(row, "sgid")), name: str(row, "name") }));
 }
 
+/**
+ * Add several clients to a server group, in one command, such as
+ * `servergroupaddclient sgid=9 cldbid=3|cldbid=4`. With no ids nothing is sent.
+ *
+ * The server reports one answer for the whole call, never one per client.
+ * Measured on TeamSpeak 3 3.13.8 and TeamSpeak 6 beta13.1, over raw
+ * ServerQuery, SSH, WebQuery and the voice protocol alike, so this resolves to
+ * nothing and a failure says only what the server said:
+ *
+ * - Without `continueOnError`, the clients are added in the order given and
+ *   the call stops at the first one that fails (an unknown database id, 512;
+ *   a client already in the group, 2561): the clients before it are in the
+ *   group, the ones after it are not, and the error is that client's.
+ * - With it (`-continueonerror`), every client is tried and each one that can
+ *   be added is. The answer is success only if none failed; otherwise it is
+ *   the error of the last one that failed, so two different failures show
+ *   only the later. Read the members, as `listServerGroupClients` reports
+ *   them, to know who was added.
+ */
+export async function addClientsToServerGroup(
+  client: CommandExecutor,
+  sgid: ServerGroupID,
+  databaseIDs: readonly ClientDBID[],
+  options: BatchOptions = {},
+): Promise<void> {
+  await execRows(
+    client,
+    "servergroupaddclient",
+    [...continueOnErrorParams(options), ["sgid", sgid]],
+    databaseIDs.map((cldbid) => [["cldbid", cldbid]]),
+    options,
+  );
+}
+
+/**
+ * Remove several clients from a server group, in one command
+ * (`servergroupdelclient sgid=9 cldbid=3|cldbid=4`). With no ids nothing is
+ * sent.
+ *
+ * As for {@link addClientsToServerGroup}, the server reports one answer for
+ * the call. Without `continueOnError` the call stops at the first client that
+ * fails, with earlier clients removed and later ones not; with it, every client
+ * is tried and the answer is the error of the last that failed. A client that
+ * is not in the group fails with 2563 (empty result set), as does an unknown
+ * database id.
+ */
+export async function removeClientsFromServerGroup(
+  client: CommandExecutor,
+  sgid: ServerGroupID,
+  databaseIDs: readonly ClientDBID[],
+  options: BatchOptions = {},
+): Promise<void> {
+  await execRows(
+    client,
+    "servergroupdelclient",
+    [...continueOnErrorParams(options), ["sgid", sgid]],
+    databaseIDs.map((cldbid) => [["cldbid", cldbid]]),
+    options,
+  );
+}
+
 /** Permissions set on a server group. */
 export async function listServerGroupPermissions(
   client: CommandExecutor,
@@ -601,6 +670,84 @@ export async function addServerGroupPermission(
   );
 }
 
+/** One permission to set on a server group, as {@link addServerGroupPermissions} takes it. */
+export interface ServerGroupPermissionValue extends PermissionValue {
+  /** Whether the value is negated, so the lowest wins; false by default. Always sent (`permnegated`). */
+  readonly negated?: boolean | undefined;
+  /** Whether it skips channel and client overrides; false by default. Always sent (`permskip`). */
+  readonly skip?: boolean | undefined;
+}
+
+/**
+ * Set several permissions on a server group, in one command: each permission
+ * is a row of its own, with all its parameters. With none, nothing is sent.
+ *
+ * The server checks every row before it applies any: a permission it does not
+ * know (2562), a value it cannot read (1540) or a row missing a parameter
+ * (1539) refuses the call, and none is set, with or without `continueOnError`.
+ * Measured on TeamSpeak 3 3.13.8 and TeamSpeak 6 beta13.1, over raw
+ * ServerQuery, SSH, WebQuery and the voice protocol alike. Resolves to
+ * nothing: the server never reports an answer per row.
+ *
+ * A permission the caller has too little modify power for (2570, or 2568 where
+ * the group power is short) is another matter: the rows are applied in order.
+ * Without `continueOnError` the first row that fails ends the call, so the rows
+ * before it are set and the rows after it are not; with it the rows that fail
+ * are skipped and the others set. The error is the failing row's, and which row
+ * is not reported; with several failing rows which error comes back was not
+ * measured. Measured on TeamSpeak 3 3.13.8 and TeamSpeak 6 beta13.1, over raw
+ * ServerQuery (TeamSpeak 3), SSH, WebQuery and the voice protocol, in both
+ * orders of a free and a locked permission.
+ */
+export async function addServerGroupPermissions(
+  client: CommandExecutor,
+  sgid: ServerGroupID,
+  permissions: readonly ServerGroupPermissionValue[],
+  options: BatchOptions = {},
+): Promise<void> {
+  await execRows(
+    client,
+    "servergroupaddperm",
+    [...continueOnErrorParams(options), ["sgid", sgid]],
+    permissions.map(serverGroupPermissionRow),
+    options,
+  );
+}
+
+const serverGroupPermissionRow = (entry: ServerGroupPermissionValue): Params => [
+  permissionParam(entry.permission),
+  ["permvalue", entry.value],
+  ["permnegated", entry.negated ?? false],
+  ["permskip", entry.skip ?? false],
+];
+
+/**
+ * Remove several permissions from a server group, in one command: each
+ * permission is a row (`permsid=…|permsid=…`). With none, nothing is sent.
+ *
+ * As for {@link addServerGroupPermissions}, the server checks every row first
+ * and a permission it does not know (2562) refuses the call with none removed,
+ * with or without `continueOnError`. Removing a permission the group does not
+ * have succeeds. A permission the caller has too little modify power for
+ * (2570) ends the call at that row, so the rows before it are removed and the
+ * rows after it are not; with `continueOnError` that row is skipped and the
+ * others removed.
+ */
+export async function deleteServerGroupPermissions(
+  client: CommandExecutor,
+  sgid: ServerGroupID,
+  permissions: readonly Permission[],
+  options: BatchOptions = {},
+): Promise<void> {
+  await execRows(
+    client,
+    "servergroupdelperm",
+    [...continueOnErrorParams(options), ["sgid", sgid]],
+    permissions.map((permission) => [permissionParam(permission)]),
+    options,
+  );
+}
+
 /** Remove a permission from a server group. */
 export async function deleteServerGroupPermission(
   client: CommandExecutor,
@@ -643,6 +790,52 @@ export async function addServerGroupPermissionByType(
   );
 }
 
+/**
+ * Set several permissions on every regular server group of a type, on every
+ * virtual server of the instance, in one command; see
+ * {@link addServerGroupPermissionByType} for what the type selects and what it
+ * needs. Each permission is a row of its own. With none, nothing is sent.
+ *
+ * The server documents no `-continueonerror` for this command, so none is
+ * offered. A permission it does not know (2562) refuses the call before any is
+ * set; a voice client gets error 2568, as for the single form.
+ */
+export async function addServerGroupPermissionsByType(
+  client: CommandExecutor,
+  type: GroupAutoUpdateType,
+  permissions: readonly ServerGroupPermissionValue[],
+  options?: CommandOptions,
+): Promise<void> {
+  await execRows(
+    client,
+    "servergroupautoaddperm",
+    [["sgtype", type]],
+    permissions.map(serverGroupPermissionRow),
+    options,
+  );
+}
+
+/**
+ * Remove several permissions from every regular server group of a type, in one
+ * command; see {@link addServerGroupPermissionsByType}. With none, nothing is
+ * sent. Needs `b_permission_modify_power_ignore`: a voice client gets error
+ * 2568.
+ */
+export async function deleteServerGroupPermissionsByType(
+  client: CommandExecutor,
+  type: GroupAutoUpdateType,
+  permissions: readonly Permission[],
+  options?: CommandOptions,
+): Promise<void> {
+  await execRows(
+    client,
+    "servergroupautodelperm",
+    [["sgtype", type]],
+    permissions.map((permission) => [permissionParam(permission)]),
+    options,
+  );
+}
+
 /**
  * Remove a permission from every regular server group of a type, on every
  * virtual server of the instance; see {@link addServerGroupPermissionByType}.

package/src/core/index.ts

@@ -150,5 +150,12 @@ export * from "./api/icons.js";
 export * from "./api/credentials.js";
 export * from "./api/instance.js";
 export { applyChannelChanges } from "./api/command.js";
-export type { Channel, ChannelChanges, PagingOptions, PermissionEntry } from "./api/command.js";
+export type {
+  BatchOptions,
+  Channel,
+  ChannelChanges,
+  PagingOptions,
+  PermissionEntry,
+  PermissionValue,
+} from "./api/command.js";
 export { ChannelTree } from "./channel-tree.js";

package/src/query/client.ts

@@ -39,6 +39,7 @@ import { connectTcp } from "./tcp.js";
 import { connectSsh } from "./ssh.js";
 import { WebQueryTransport } from "./web.js";
 import { GuestAccessError, QueryAuthError } from "./errors.js";
+import { LATE_ROW_GRACE_MS, LATE_ROW_QUIET_MS, hasLateRow, lateRowsOf } from "./late-rows.js";
 import {
   assertEventsSupported,
   normalizeQueryOptions,
@@ -103,6 +104,16 @@ interface Pending {
   readonly rows: Array<Record<string, string>>;
   resolve(rows: Array<Record<string, string>>): void;
   reject(error: unknown): void;
+  /** Set once the `error` line has been read: what follows is a late row or nothing. */
+  held?: {
+    readonly keys: readonly string[];
+    readonly several: boolean;
+    readonly any: boolean;
+    timer: ReturnType<typeof setTimeout>;
+    /** Wait for another row, or for the rows to stop. */
+    wait(ms: number): void;
+    finish(): void;
+  };
 }
 
 /**
@@ -132,6 +143,12 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
   #version = "";
 
   #pending: Pending | null = null;
+  /**
+   * The key of a row that was waited for and did not come before its answer
+   * was given up on. Should it arrive later, it belongs to that command and is
+   * dropped rather than handed to the next one.
+   */
+  #strayKey: string | undefined;
   /**
    * Answers still to come for commands that gave up waiting. ServerQuery has
    * no return_code, only order, so each is read and discarded when it arrives
@@ -392,6 +409,7 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
     this.#closed = false;
     this.#abandoned = 0;
     this.#pending = null;
+    this.#strayKey = undefined;
     this.#clients.clear();
     this.#clid = 0;
     this.#serverFamily = "unknown";
@@ -933,8 +951,12 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
       clearTimeout(nudger);
       if (onAbort) signal?.removeEventListener("abort", onAbort);
       if (this.#pending !== null) {
+        const gone = this.#pending;
         this.#pending = null;
-        if (!sending.failed) {
+        if (gone.held) {
+          // Its `error` line was read already, so no answer is still to come.
+          clearTimeout(gone.held.timer);
+        } else if (!sending.failed) {
           this.#abandoned++;
           abandonedByUs = true;
         }
@@ -957,9 +979,49 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
       this.#pending = null;
       if (!pending) return;
       const { err } = parseServerError(cmd.params);
+      this.#strayKey = undefined;
       const refusal = err ?? transferRefusal(pending.command, pending.rows);
-      if (refusal) pending.reject(refusal);
-      else pending.resolve(pending.rows);
+      if (refusal) {
+        pending.reject(refusal);
+        return;
+      }
+      const late = this.#options.transport.kind === "web" ? undefined : lateRowsOf(pending.command);
+      const hasRow = late !== undefined && hasLateRow(late, pending.rows);
+      if (late === undefined || (hasRow && late.several !== true)) {
+        pending.resolve(pending.rows);
+        return;
+      }
+      // A create that succeeded, with its row not here yet or perhaps not all
+      // of them: the server may write them just after this line. Wait briefly,
+      // with the command still the one on the wire, so the rows are its own and
+      // the next command is not sent before them.
+      this.#pending = pending;
+      const finish = (): void => {
+        clearTimeout(pending.held?.timer);
+        if (this.#pending === pending) this.#pending = null;
+        pending.resolve(pending.rows);
+      };
+      const held: NonNullable<Pending["held"]> = {
+        keys: late.keys,
+        several: late.several === true,
+        any: late.any === true,
+        timer: setTimeout(() => {}, 0),
+        finish,
+        wait: (ms) => {
+          clearTimeout(held.timer);
+          held.timer = setTimeout(() => {
+            // Given up on, with no row at all: one that still comes is not the
+            // next command's.
+            const got = hasLateRow(late, pending.rows);
+            if (!got && this.#pending === pending && held.keys[0] !== undefined) {
+              this.#strayKey = held.keys[0];
+            }
+            finish();
+          }, ms);
+        },
+      };
+      pending.held = held;
+      held.wait(hasRow || late.any === true ? LATE_ROW_QUIET_MS : LATE_ROW_GRACE_MS);
       return;
     }
     if (cmd.name.startsWith("notify")) {
@@ -973,7 +1035,23 @@ export class QueryClient implements CommandExecutor, AsyncDisposable {
     if (this.#abandoned > 0) return;
     for (const row of splitRows(trimmed)) {
       const parsed = parseCommand(row);
-      if (parsed) this.#pending?.rows.push(parsed.params);
+      if (!parsed) continue;
+      const keys = Object.keys(parsed.params);
+      if (this.#strayKey !== undefined && keys.length === 1 && keys[0] === this.#strayKey) {
+        const own = this.#pending === null ? undefined : lateRowsOf(this.#pending.command);
+        this.#strayKey = undefined;
+        // The late row of an earlier command, which gave up waiting for it. A
+        // command whose own answer carries that key keeps it: the two cannot be
+        // told apart, and lateness was measured at under a millisecond against
+        // a wait of 250, so it almost certainly belongs to the command asking.
+        if (!own?.keys.includes(keys[0])) continue;
+      }
+      this.#pending?.rows.push(parsed.params);
+      const held = this.#pending?.held;
+      if (held && (held.any || keys.some((k) => held.keys.includes(k)))) {
+        if (held.several || held.any) held.wait(LATE_ROW_QUIET_MS);
+        else held.finish();
+      }
     }
   }
 

package/src/query/late-rows.ts

@@ -0,0 +1,64 @@
+/** The row a command's answer carries, and whether it carries several. */
+export interface LateRows {
+  /** The keys the row is known by. */
+  readonly keys: readonly string[];
+  /**
+   * The answer has one row for each of several things it made, and all, some or
+   * none of them may follow the `error` line, so it is held until the rows stop.
+   */
+  readonly several?: boolean;
+  /** Any row is the answer: a read, which has no one key. */
+  readonly any?: boolean;
+}
+
+/**
+ * Commands whose answer carries the row that names what they made, and the key
+ * that row is known by.
+ *
+ * TeamSpeak 6 over SSH has been measured to write that row after the command's
+ * `error` line, a fraction of a millisecond later, in a share of the answers.
+ * A client that takes the `error` line for the end of the answer loses the row
+ * and, worse, hands it to whichever command is sent next.
+ */
+export const LATE_ROWS: ReadonlyMap<string, LateRows> = new Map<string, LateRows>([
+  ["channelcreate", { keys: ["cid"] }],
+  ["servergroupadd", { keys: ["sgid"] }],
+  ["servergroupcopy", { keys: ["sgid"] }],
+  ["channelgroupadd", { keys: ["cgid"] }],
+  ["channelgroupcopy", { keys: ["cgid"] }],
+  ["banadd", { keys: ["banid"] }],
+  ["banclient", { keys: ["banid"], several: true }],
+  ["privilegekeyadd", { keys: ["token"] }],
+  ["tokenadd", { keys: ["token"] }],
+  ["apikeyadd", { keys: ["apikey"] }],
+  ["servercreate", { keys: ["sid"] }],
+]);
+
+/** How long a successful answer without its row is held open for the row to arrive. */
+export const LATE_ROW_GRACE_MS = 250;
+
+/** For an answer with several rows: how long without a new one counts as its end. */
+export const LATE_ROW_QUIET_MS = 25;
+
+/**
+ * Commands that read something, by their names: a `list`, `info` or `find`, a
+ * `get…`, `whoami`, `version`. A plain read has been measured to have its whole
+ * answer after the `error` line too, much less often than a create (2 in 3000
+ * `clientlist` calls, while clients were connecting), so one that is answered
+ * with no row is held briefly as well. An empty success is rare for these: the
+ * servers answer an empty list with error 1281.
+ */
+const READS = /(list|info|find|search)$|^(get\w+|whoami|version|permfind|permoverview|permget)$/;
+
+/** What is known of where a command's answer rows may fall, or `undefined` for none. */
+export function lateRowsOf(command: string): LateRows | undefined {
+  const known = LATE_ROWS.get(command);
+  if (known !== undefined) return known;
+  return READS.test(command) ? { keys: [], any: true } : undefined;
+}
+
+/** Whether `rows` already hold what {@link lateRowsOf} says to wait for. */
+export function hasLateRow(late: LateRows, rows: ReadonlyArray<Record<string, string>>): boolean {
+  if (late.any === true) return rows.length > 0;
+  return rows.some((row) => late.keys.some((k) => row[k] !== undefined));
+}