@honeybbq/teamspeak 0.0.1 → 1.0.0-beta.8

package/dist/client/throttle.js

@@ -0,0 +1,83 @@
+var _a;
+/**
+ * Token-bucket limiter for outbound TS3 commands.
+ * Mirrors Go's commandThrottle.
+ *
+ * Waiters are released in the order they arrived: each used to poll for a
+ * token on its own timer, so a command that came later could take the turn of
+ * one that had waited longer, and the commands went out of order.
+ */
+export class CommandThrottle {
+    static TOKEN_RATE = 4.0; // tokens per second
+    static TOKEN_MAX = 8.0; // bucket capacity
+    #tokens = 5.0;
+    #lastUpdate = performance.now();
+    #waiters = [];
+    #timer;
+    /**
+     * Wait for a token, behind every earlier waiter. Aborting `signal` rejects
+     * with its reason and gives the place in line up; the abort listener is
+     * removed however the wait ends.
+     */
+    wait(signal) {
+        if (signal?.aborted)
+            return Promise.reject(signal.reason);
+        this.#refill();
+        if (this.#waiters.length === 0 && this.#tokens >= 1.0) {
+            this.#tokens -= 1.0;
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                resolve,
+                signal,
+                onAbort: () => {
+                    const index = this.#waiters.indexOf(waiter);
+                    if (index >= 0)
+                        this.#waiters.splice(index, 1);
+                    if (this.#waiters.length === 0)
+                        this.#stopTimer();
+                    reject(signal.reason);
+                },
+            };
+            signal?.addEventListener("abort", waiter.onAbort, { once: true });
+            this.#waiters.push(waiter);
+            this.#schedule();
+        });
+    }
+    #refill() {
+        const now = performance.now();
+        const elapsed = (now - this.#lastUpdate) / 1000;
+        this.#tokens = Math.min(this.#tokens + elapsed * _a.TOKEN_RATE, _a.TOKEN_MAX);
+        this.#lastUpdate = now;
+    }
+    /** Arm the timer for when the next token is due, unless it already is. */
+    #schedule() {
+        if (this.#timer !== undefined || this.#waiters.length === 0)
+            return;
+        const waitMs = this.#tokens >= 1.0
+            ? 0
+            : Math.ceil(((1.0 - this.#tokens) / _a.TOKEN_RATE) * 1000) + 10;
+        this.#timer = setTimeout(() => {
+            this.#timer = undefined;
+            this.#release();
+        }, waitMs);
+    }
+    #stopTimer() {
+        clearTimeout(this.#timer);
+        this.#timer = undefined;
+    }
+    /** Hand the tokens there are to the waiters at the head of the line. */
+    #release() {
+        this.#refill();
+        while (this.#waiters.length > 0 && this.#tokens >= 1.0) {
+            this.#tokens -= 1.0;
+            const waiter = this.#waiters.shift();
+            waiter.signal?.removeEventListener("abort", waiter.onAbort);
+            waiter.resolve();
+        }
+        this.#schedule();
+    }
+}
+_a = CommandThrottle;
+//# sourceMappingURL=throttle.js.map

package/dist/client/throttle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.js","sourceRoot":"","sources":["../../src/client/throttle.ts"],"names":[],"mappings":"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"}

package/dist/client/trace.d.ts

@@ -0,0 +1,223 @@
+import type { ChannelID, ClientID } from "@honeybbq/teamspeak";
+import type { ServerCapabilities } from "./capabilities.js";
+import type { ResolvedAddr } from "./types.js";
+/** The values of the table below, before freezing. */
+declare const connectPhaseValues: {
+    /** Opening the socket, or the address was not usable once resolved. */
+    readonly Open: "open";
+    /** The handshake, from the first packet until the shared secret exists. */
+    readonly Handshake: "handshake";
+    /** After the handshake, waiting for the server to accept the client: a wrong password, a ban or an invalid nickname end here. */
+    readonly Join: "join";
+};
+/** Where a connection attempt can fail; see {@link AttemptFailedInfo}. */
+export declare const ConnectPhase: typeof connectPhaseValues;
+/**
+ * One of {@link ConnectPhase}. May gain members in a minor release: a
+ * `switch` over it needs a default case.
+ */
+export type ConnectPhase = (typeof ConnectPhase)[keyof typeof ConnectPhase];
+/** What every milestone of one connection attempt says about the attempt. */
+interface AttemptInfo {
+    /**
+     * The attempt's number, from 1. The attempt `connect()` starts is 1; a
+     * reconnection attempt carries the retry number the reconnect policy uses,
+     * the one `shouldRetry` and the backoff see.
+     */
+    readonly attempt: number;
+    /** Whether the reconnect loop started this attempt rather than a call to `connect()`. */
+    readonly reconnect: boolean;
+}
+/** The address is about to be resolved. */
+export interface ResolveStartInfo extends AttemptInfo {
+    /** The address as the client was given it. */
+    readonly addr: string;
+}
+/** The address has been resolved, or the lookup failed and the address is used as given. */
+export interface ResolveDoneInfo extends AttemptInfo {
+    /** The address as the client was given it. */
+    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. */
+    readonly source: string;
+    /** Every answer the resolver gave, in order; empty when the address is used as given. */
+    readonly candidates: readonly ResolvedAddr[];
+    /** Why the lookup failed, when the address is used as given; `undefined` otherwise. */
+    readonly error: unknown;
+    /** How long the resolution took, in milliseconds. */
+    readonly durationMs: number;
+}
+/** The socket is about to be opened. */
+export interface ConnectStartInfo extends AttemptInfo {
+    /** The `host:port` being dialled. */
+    readonly target: string;
+}
+/** The socket is open; the first handshake packet has not been sent yet. */
+export interface ConnectDoneInfo extends AttemptInfo {
+    /** The `host:port` being dialled. */
+    readonly target: string;
+    /** The local socket's `host:port`; empty when the socket does not say. */
+    readonly localAddr: string;
+    /** Milliseconds since `connectStart`. */
+    readonly durationMs: number;
+}
+/** The encrypted session exists; `clientinit` has not been sent yet. */
+export interface HandshakeDoneInfo extends AttemptInfo {
+    /** Milliseconds since `connectStart`. */
+    readonly durationMs: number;
+    /** The level of the RSA puzzle the server demanded; 0 if it sent none. */
+    readonly puzzleLevel: number;
+    /** Milliseconds spent solving the puzzle. */
+    readonly puzzleDurationMs: number;
+    /**
+     * The packets sent again from `connectStart` to now, for want of an
+     * acknowledgement: the Init1 steps and the handshake's command packets.
+     */
+    readonly resends: number;
+    /**
+     * The server's public key exactly as it sent it, base64, so that a caller can
+     * pin a server's identity.
+     */
+    readonly serverPublicKey: string;
+}
+/** The server accepted the client, which is now connected. */
+export interface SessionStartInfo extends AttemptInfo {
+    /** The client's ID on the server, the same as `client.clientID`. */
+    readonly clientID: ClientID;
+    /**
+     * The nickname the server accepted (`acn`), which differs from the one asked
+     * for when that was taken. The one asked for when the server did not say.
+     */
+    readonly nickname: string;
+    /** The client's talk power (`client_talk_power`); 0 when the server did not say. */
+    readonly talkPower: number;
+    /**
+     * Every parameter of `initserver`, unescaped, except those that could carry a
+     * secret: `client_server_password`, `client_default_channel_password`,
+     * `client_default_token` and `client_key_offset`. Frozen.
+     */
+    readonly initServer: Readonly<Record<string, string>>;
+    /** What the server said about itself in this handshake. */
+    readonly capabilities: ServerCapabilities;
+    /** Milliseconds since `connectStart`. */
+    readonly durationMs: number;
+}
+/** The server's welcome sequence ended: the channel list and the clients already there have arrived. */
+export interface WelcomeDoneInfo extends AttemptInfo {
+    /**
+     * The channel the client is in at the end of the welcome: where it landed,
+     * which differs from the default channel asked for when that was refused.
+     */
+    readonly channelID: ChannelID;
+    /** How many channel rows the welcome delivered. */
+    readonly channels: number;
+    /** How many clients are in view at the end of the welcome, this client included. */
+    readonly clients: number;
+    /** Milliseconds since `connectStart`. */
+    readonly durationMs: number;
+}
+/** An attempt ended without a session. */
+export interface AttemptFailedInfo extends AttemptInfo {
+    /** Where the attempt failed. */
+    readonly phase: ConnectPhase;
+    /** Why: the error `connect()` rejects with, or the one that ended the reconnection attempt. */
+    readonly error: unknown;
+    /** The `host:port` being dialled; empty when the attempt failed before `resolveDone`. */
+    readonly target: string;
+    /** Milliseconds since `resolveStart`. */
+    readonly durationMs: number;
+}
+/** The reconnect loop will retry, after a wait. */
+export interface ReconnectScheduledInfo {
+    /** The attempt that will follow, numbered as in {@link ResolveStartInfo.attempt}. */
+    readonly attempt: number;
+    /** How long the loop waits first, in milliseconds. */
+    readonly delayMs: number;
+    /** The error that ended the previous connection or attempt. */
+    readonly cause: unknown;
+}
+/** A connected session is about to be left with `disconnect()`. It has no fields yet. */
+export interface DisconnectStartInfo {
+}
+/** The goodbye of `disconnect()` is over. */
+export interface DisconnectDoneInfo {
+    /** Whether the server acknowledged the goodbye before the goodbye timeout. */
+    readonly acknowledged: boolean;
+    /** Milliseconds since `disconnectStart`. */
+    readonly durationMs: number;
+}
+/** A session that had a `sessionStart` has ended, however it ended. */
+export interface SessionEndInfo {
+    /** The client's ID on the server during the session. */
+    readonly clientID: ClientID;
+    /**
+     * `undefined` after `disconnect()`, and otherwise the cause the
+     * `disconnected` event gets.
+     */
+    readonly error: unknown;
+    /** Milliseconds since `sessionStart`. */
+    readonly durationMs: number;
+    /** The number of the attempt that started the session. */
+    readonly attempt: number;
+    /** Whether the reconnect loop started the attempt that started the session. */
+    readonly reconnect: boolean;
+}
+/** The reconnect loop ended without a session. */
+export interface ReconnectStoppedInfo {
+    /** How many reconnection attempts the loop made. */
+    readonly attempts: number;
+    /**
+     * The error `shouldRetry` declined, or the last attempt's when the attempts
+     * ran out; `undefined` when `disconnect()` stopped the loop.
+     */
+    readonly cause: unknown;
+}
+/**
+ * Hooks that observe a client for timing, metrics, logs or a progress
+ * display: the milestones of every connection attempt, the end of a session,
+ * and the reconnect loop. Every hook is optional.
+ *
+ * A hook is called synchronously, at the moment of the milestone, and the
+ * client waits for it to return: keep it quick, and hand slow work to your own
+ * task. What it returns is ignored, and a returned promise is never awaited. A
+ * hook that throws, or whose promise rejects, is reported the way a throwing
+ * event listener is, and the client carries on. A hook may read the
+ * client's state. It must not call `connect()` or `disconnect()`: to give up
+ * on an attempt, abort the signal passed to `connect()`, and to leave once
+ * connected, call `disconnect()` from a `connected` listener.
+ *
+ * Every attempt ends with exactly one of `sessionStart` and `attemptFailed`,
+ * and every session that started with exactly one `sessionEnd`. The hooks are
+ * read when the client is made, from a copy of this object.
+ */
+export interface ClientTrace {
+    /** Before the address is resolved. */
+    readonly resolveStart?: (info: ResolveStartInfo) => void;
+    /** After the address is resolved, also when it fell back to the address as given. */
+    readonly resolveDone?: (info: ResolveDoneInfo) => void;
+    /** Right before the socket is opened. */
+    readonly connectStart?: (info: ConnectStartInfo) => void;
+    /** Once the socket is open, before the first handshake packet is sent. */
+    readonly connectDone?: (info: ConnectDoneInfo) => void;
+    /** When the shared secret is derived, before `clientinit` is sent. */
+    readonly handshakeDone?: (info: HandshakeDoneInfo) => void;
+    /** When the server accepts the client: before `connect()` resolves and before `connected` is delivered. */
+    readonly sessionStart?: (info: SessionStartInfo) => void;
+    /** When the server's welcome sequence ends; at most once per attempt, and only after `sessionStart`. */
+    readonly welcomeDone?: (info: WelcomeDoneInfo) => void;
+    /** When an attempt ends without `sessionStart`, for any reason, an abort or `disconnect()` included. */
+    readonly attemptFailed?: (info: AttemptFailedInfo) => void;
+    /** When `disconnect()` begins saying goodbye to a connected session. */
+    readonly disconnectStart?: (info: DisconnectStartInfo) => void;
+    /** When that goodbye is over. */
+    readonly disconnectDone?: (info: DisconnectDoneInfo) => void;
+    /** When a session ends, however it ends; before `disconnected` is queued. */
+    readonly sessionEnd?: (info: SessionEndInfo) => void;
+    /** When the reconnect loop has decided to retry and is about to wait. */
+    readonly reconnectScheduled?: (info: ReconnectScheduledInfo) => void;
+    /** When the reconnect loop ends without a session. */
+    readonly reconnectStopped?: (info: ReconnectStoppedInfo) => void;
+}
+export {};
+//# sourceMappingURL=trace.d.ts.map

package/dist/client/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/client/trace.ts"],"names":[],"mappings":"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"}

package/dist/client/trace.js

@@ -0,0 +1,13 @@
+/** The values of the table below, before freezing. */
+const connectPhaseValues = {
+    /** 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",
+};
+/** Where a connection attempt can fail; see {@link AttemptFailedInfo}. */
+export const ConnectPhase = 
+/* @__PURE__ */ Object.freeze(connectPhaseValues);
+//# sourceMappingURL=trace.js.map

package/dist/client/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/client/trace.ts"],"names":[],"mappings":"AAIA,sDAAsD;AACtD,MAAM,kBAAkB,GAAG;IACzB,uEAAuE;IACvE,IAAI,EAAE,MAAM;IACZ,2EAA2E;IAC3E,SAAS,EAAE,WAAW;IACtB,iIAAiI;IACjI,IAAI,EAAE,MAAM;CACJ,CAAC;AACX,0EAA0E;AAC1E,MAAM,CAAC,MAAM,YAAY;AACvB,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC"}

package/dist/client/transfer.d.ts

@@ -0,0 +1,111 @@
+/**
+ * File transfer data.
+ *
+ * Negotiating a transfer is a command (`initFileUpload`, `initFileDownload`);
+ * the bytes then go over a separate TCP connection to the server's file
+ * transfer port, opened with the key the negotiation returned.
+ */
+import { type Duplex, type Readable, type Writable } from "node:stream";
+import type { FileUploadInfo, FileDownloadInfo } from "@honeybbq/teamspeak";
+import type { FileTransferSocketFactory } from "./types.js";
+import { FileTransferError } from "./errors.js";
+/** Where a failed transfer failed. */
+export type FileTransferStage = "dial" | "transfer";
+/** The file transfer port is about to be dialled. */
+export interface FileTransferDialStartInfo {
+    /** The `host:port` being dialled. */
+    readonly addr: string;
+}
+/** The connection is open and the transfer key has been sent. */
+export interface FileTransferDialDoneInfo {
+    /** The `host:port` dialled. */
+    readonly addr: string;
+    /** The local socket's `host:port`; empty when the socket does not say. */
+    readonly localAddr: string;
+    /** Milliseconds since `dialStart`. */
+    readonly durationMs: number;
+}
+/** Data has moved. */
+export interface FileTransferProgressInfo {
+    /** The bytes moved so far. */
+    readonly bytes: number;
+    /** The size the negotiation gave; 0 when it is not known, as for an upload. */
+    readonly total: number;
+}
+/** The transfer succeeded. */
+export interface FileTransferDoneInfo {
+    /** The bytes moved. */
+    readonly bytes: number;
+    /** Milliseconds since `dialStart`. */
+    readonly durationMs: number;
+}
+/** The transfer failed. */
+export interface FileTransferFailedInfo {
+    /** Why: the error the transfer function rejects with. */
+    readonly error: unknown;
+    /** The bytes moved before it failed. */
+    readonly bytes: number;
+    /** Milliseconds since `dialStart`. */
+    readonly durationMs: number;
+    /** Whether the failure came while dialling or while the data moved. */
+    readonly stage: FileTransferStage;
+}
+/**
+ * Hooks that observe one file transfer. Every hook is optional, and none ever
+ * sees the transfer key.
+ *
+ * A hook runs synchronously on the task doing the transfer, and its return
+ * value is ignored: a returned promise is not awaited. A hook that throws, or
+ * whose promise rejects, is reported the way a throwing event listener is, and
+ * the transfer goes on. Keep hooks quick.
+ *
+ * A call of `uploadFileData` or `downloadFileData` ends with exactly one of
+ * `done` and `failed`; `dialFileTransfer` on its own reports `dialStart`, then
+ * `dialDone` or `failed` with the stage `"dial"`.
+ */
+export interface FileTransferTrace {
+    /** Before the file transfer port is dialled. */
+    readonly dialStart?: (info: FileTransferDialStartInfo) => void;
+    /** When the connection is open and the transfer key is sent. */
+    readonly dialDone?: (info: FileTransferDialDoneInfo) => void;
+    /** While data moves, at most once per 64 KiB, and once more at the end with the final count. */
+    readonly progress?: (info: FileTransferProgressInfo) => void;
+    /** When the transfer function is about to resolve. */
+    readonly done?: (info: FileTransferDoneInfo) => void;
+    /** When the transfer function is about to reject, a failed dial included. */
+    readonly failed?: (info: FileTransferFailedInfo) => void;
+}
+/** Options for a file transfer. */
+export interface FileTransferOptions {
+    /** Abandons the transfer; it then rejects with the signal's reason. */
+    readonly signal?: AbortSignal | undefined;
+    /**
+     * Opens the connection instead of a direct TCP dial, to route the transfer
+     * through a proxy or tunnel.
+     */
+    readonly socketFactory?: FileTransferSocketFactory | undefined;
+    /**
+     * Hooks called at each milestone of this transfer. The object is copied when
+     * the call starts. See {@link FileTransferTrace}.
+     */
+    readonly trace?: FileTransferTrace | undefined;
+    /**
+     * The longest, in milliseconds, the transfer may go without moving a byte,
+     * the write of the transfer key included. When it passes, the transfer
+     * rejects with a {@link FileTransferError} whose `cause` is a `TimeoutError`
+     * and the connection is destroyed. `undefined` means the default, 30 000;
+     * `0` turns the limit off.
+     */
+    readonly idleTimeoutMs?: number | undefined;
+}
+/**
+ * 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.
+ */
+export declare function dialFileTransfer(host: string, port: number, key: string, options?: FileTransferOptions): Promise<Duplex>;
+/** Upload `data` over a negotiated transfer. Resolves once every byte is sent. */
+export declare function uploadFileData(host: string, info: FileUploadInfo, data: Readable, options?: FileTransferOptions): Promise<void>;
+/** Download a negotiated transfer into `dest`. Resolves once the file is written. */
+export declare function downloadFileData(host: string, info: FileDownloadInfo, dest: Writable, options?: FileTransferOptions): Promise<void>;
+export { FileTransferError };
+//# sourceMappingURL=transfer.d.ts.map

package/dist/client/transfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer.d.ts","sourceRoot":"","sources":["../../src/client/transfer.ts"],"names":[],"mappings":"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"}