ts-server-lib 0.0.17

package/utils/TSStub.js

@@ -0,0 +1,296 @@
+"use strict";
+/**
+ * TSStub — generic driver stub utility for all at-prefixed provider packages.
+ *
+ * Provides the shared scaffolding every stub needs:
+ *   - Latency injection (fixed, random range, or abortable timeout)
+ *   - Error injection (network error, timeout, rate-limit exceeded)
+ *   - Outcome simulation (success / failure / pending / processing)
+ *   - Retry-N-then-succeed counter
+ *   - Webhook signature validation
+ *   - In-memory store with deterministic ID generation
+ *   - Rate-limit capability declaration
+ *   - OAuth token / session simulation (atsocial)
+ *   - Exchange rate table lookup (atexchange)
+ *   - Capability matrix helper (atsocial)
+ *   - Health status simulation (atkyc, others)
+ *   - Config field extractor (normalise simulate* + latency from raw config)
+ *   - Noop links factory
+ *
+ * Each at-package stub only needs to handle its domain-specific response shapes.
+ * TSStub has zero dependencies on any at-package — purely generic infrastructure.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TSStub = exports.TSStubRateLimitError = void 0;
+const node_crypto_1 = require("node:crypto");
+const abort_js_1 = require("./abort.js");
+const TSHash_js_1 = require("./TSHash.js");
+function createStore() {
+    const map = new Map();
+    let counter = 0;
+    return {
+        get: (id) => map.get(id),
+        set: (id, value) => { map.set(id, value); },
+        delete: (id) => map.delete(id),
+        list: () => Array.from(map.values()),
+        entries: () => Array.from(map.entries()),
+        clear: () => { map.clear(); counter = 0; },
+        nextId: (prefix = 'stub') => `${prefix}-${String(++counter).padStart(3, '0')}`,
+        get size() { return map.size; },
+    };
+}
+function createRetryCounter() {
+    const counts = new Map();
+    return {
+        shouldFail(key, n) {
+            const c = (counts.get(key) ?? 0) + 1;
+            counts.set(key, c);
+            return c <= n;
+        },
+        reset(key) {
+            if (key !== undefined)
+                counts.delete(key);
+            else
+                counts.clear();
+        },
+    };
+}
+// ═══════════════════════════════════════════════════════════════════
+// Rate-limit exceeded response (generic shape)
+// ═══════════════════════════════════════════════════════════════════
+class TSStubRateLimitError extends Error {
+    code = 'STUB_RATE_LIMIT_EXCEEDED';
+    retryAfterMs;
+    constructor(retryAfterMs = 1000) {
+        super('Rate limit exceeded (stub)');
+        this.name = 'TSStubRateLimitError';
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+exports.TSStubRateLimitError = TSStubRateLimitError;
+// ═══════════════════════════════════════════════════════════════════
+// TSStub — static API
+// ═══════════════════════════════════════════════════════════════════
+class TSStub {
+    // ── Latency ────────────────────────────────────────────────────
+    /**
+     * Delay by `cfg.latencyMs` (fixed) or a uniform random value in
+     * `[cfg.latencyMsMin, cfg.latencyMsMax]`. Abortable via `signal`.
+     * If `cfg.simulateTimeoutMs` is set, waits that long then throws AbortError.
+     */
+    static async maybeDelay(cfg, signal) {
+        (0, abort_js_1.throwIfAborted)(signal);
+        if (typeof cfg.simulateTimeoutMs === 'number') {
+            await (0, abort_js_1.abortableDelay)(cfg.simulateTimeoutMs, signal);
+            throw (0, abort_js_1.abortError)();
+        }
+        let ms = 0;
+        if (typeof cfg.latencyMsMin === 'number' &&
+            typeof cfg.latencyMsMax === 'number' &&
+            cfg.latencyMsMax >= cfg.latencyMsMin &&
+            cfg.latencyMsMax > 0) {
+            const min = Math.max(0, cfg.latencyMsMin);
+            const max = Math.max(min, cfg.latencyMsMax);
+            ms = min + Math.random() * (max - min);
+        }
+        else if (typeof cfg.latencyMs === 'number' && cfg.latencyMs > 0) {
+            ms = cfg.latencyMs;
+        }
+        if (ms > 0)
+            await (0, abort_js_1.abortableDelay)(ms, signal);
+    }
+    // ── Error injection ─────────────────────────────────────────────
+    /**
+     * Call at the start of every stub method. Throws a network error or rate-limit
+     * error when the corresponding simulate flag is set.
+     * Also honours `simulateTimeoutMs` via `maybeDelay`.
+     */
+    static async maybeInjectError(cfg, signal) {
+        (0, abort_js_1.throwIfAborted)(signal);
+        if (cfg.simulateNetworkError) {
+            throw new Error('network error (stub)');
+        }
+        if (cfg.simulateRateLimitExceeded) {
+            throw new TSStubRateLimitError();
+        }
+        if (cfg.simulateTimeoutMs) {
+            await (0, abort_js_1.abortableDelay)(cfg.simulateTimeoutMs, signal);
+            throw (0, abort_js_1.abortError)();
+        }
+    }
+    // ── Outcome helpers ─────────────────────────────────────────────
+    /**
+     * Return `cfg.simulateOutcome ?? fallback`, cast to T.
+     * Domain stubs pass their expected outcome union as T.
+     */
+    static outcome(cfg, fallback) {
+        return cfg.simulateOutcome ?? fallback;
+    }
+    static isFailed(cfg) {
+        return cfg.simulateOutcome === 'failed';
+    }
+    static isPending(cfg) {
+        const o = cfg.simulateOutcome;
+        return o === 'pending' || o === 'processing';
+    }
+    static failureReason(cfg, fallback = 'simulated failure') {
+        return cfg.simulateFailureReason ?? fallback;
+    }
+    // ── Retry ────────────────────────────────────────────────────────
+    /** Factory — create one per stub instance; call `reset()` in test teardown. */
+    static createRetryCounter() {
+        return createRetryCounter();
+    }
+    /**
+     * Check retry counter. Returns true when the call should fail.
+     * Usage inside a stub method:
+     *   if (retry.shouldFail(operationKey, cfg.simulateFailFirstN ?? 0)) throw ...
+     */
+    static shouldFail(counter, key, cfg) {
+        const n = cfg.simulateFailFirstN ?? 0;
+        if (n === 0)
+            return false;
+        return counter.shouldFail(key, n);
+    }
+    // ── Webhook ─────────────────────────────────────────────────────
+    /**
+     * Validate webhook signature against `cfg.simulateWebhookSignature`.
+     * Returns true when signatures match (or when incoming equals the default stub value).
+     */
+    static validateSignature(incoming, cfg, defaultSignature = 'stub-signature') {
+        const expected = cfg.simulateWebhookSignature ?? defaultSignature;
+        if (!incoming)
+            return false;
+        try {
+            return timingSafeCompare(expected, incoming);
+        }
+        catch {
+            return incoming === expected;
+        }
+    }
+    // ── Capabilities ─────────────────────────────────────────────────
+    static rateLimitCapabilities(cfg) {
+        const out = {};
+        if (typeof cfg.simulateRateLimitPerSecond === 'number')
+            out.rateLimitPerSecond = cfg.simulateRateLimitPerSecond;
+        if (typeof cfg.simulateRateLimitBurst === 'number')
+            out.rateLimitBurst = cfg.simulateRateLimitBurst;
+        return out;
+    }
+    static healthStatus(cfg) {
+        return cfg.simulateHealthStatus ?? 'healthy';
+    }
+    // ── In-memory store ──────────────────────────────────────────────
+    /** Factory — create one store per entity type in the stub constructor. */
+    static createStore() {
+        return createStore();
+    }
+    // ── ID generation ────────────────────────────────────────────────
+    /** Generate a random stub ID: `stub-<prefix>-<8 hex chars>`. */
+    static id(prefix = 'item') {
+        return `stub-${prefix}-${TSHash_js_1.TSHash.randomId(4, 'hex')}`;
+    }
+    /**
+     * Create a sequential ID generator: returns a function that yields
+     * `stub-<prefix>-001`, `stub-<prefix>-002`, ... (resets per call to this factory).
+     */
+    static seqId(prefix = 'item') {
+        let n = 0;
+        return () => `stub-${prefix}-${String(++n).padStart(3, '0')}`;
+    }
+    // ── OAuth / token simulation ─────────────────────────────────────
+    static fakeToken(cfg = {}) {
+        const prefix = cfg.simulateTokenPrefix ?? 'stub-token';
+        return {
+            accessToken: `${prefix}-access-${TSHash_js_1.TSHash.randomId(8, 'hex')}`,
+            refreshToken: `${prefix}-refresh-${TSHash_js_1.TSHash.randomId(8, 'hex')}`,
+            expiresAt: Date.now() + 3600_000,
+        };
+    }
+    static fakeAuthUrl(cfg = {}, params = {}) {
+        const base = cfg.simulateCallbackBase ?? 'https://stub.local/authorize';
+        const qs = new URLSearchParams({ state: TSHash_js_1.TSHash.randomId(8, 'hex'), ...params }).toString();
+        return `${base}?${qs}`;
+    }
+    // ── Exchange rate table ──────────────────────────────────────────
+    /**
+     * Look up `from → to` in a rate table, then try inverse, then fall back to `defaultRate`.
+     * Same logic as atexchange `Stub` driver.
+     */
+    static resolveRate(from, to, table = {}, defaultRate = 1) {
+        const f = from.trim().toUpperCase();
+        const t = to.trim().toUpperCase();
+        if (f === t)
+            return 1;
+        const direct = table[`${f}:${t}`];
+        if (typeof direct === 'number')
+            return direct;
+        const inverse = table[`${t}:${f}`];
+        if (typeof inverse === 'number' && inverse !== 0)
+            return 1 / inverse;
+        return defaultRate;
+    }
+    // ── Capability matrix ────────────────────────────────────────────
+    /**
+     * Build a capability map for packages like atsocial that expose a fixed set of keys.
+     * All keys default to `'unsupported'`; `supported` overrides per key.
+     */
+    static capabilities(allKeys, supported = {}) {
+        const result = {};
+        for (const key of allKeys) {
+            result[key] = supported[key] ?? 'unsupported';
+        }
+        return result;
+    }
+    // ── Config extractor ─────────────────────────────────────────────
+    /**
+     * Extract all TSStubConfig fields from a raw config object.
+     * Used in `normalizeDriverConfig` in each at-package stub.
+     */
+    static extractConfig(raw) {
+        const out = {};
+        const n = (k, type) => {
+            const v = raw[k];
+            if (typeof v === type)
+                out[k] = v;
+        };
+        n('latencyMs', 'number');
+        n('latencyMsMin', 'number');
+        n('latencyMsMax', 'number');
+        n('simulateTimeoutMs', 'number');
+        n('simulateNetworkError', 'boolean');
+        n('simulateRateLimitExceeded', 'boolean');
+        n('simulateOutcome', 'string');
+        n('simulateFailureReason', 'string');
+        n('simulateFailFirstN', 'number');
+        n('simulateWebhookSignature', 'string');
+        n('simulateRateLimitPerSecond', 'number');
+        n('simulateRateLimitBurst', 'number');
+        n('simulateHealthStatus', 'string');
+        n('simulateTokenPrefix', 'string');
+        n('simulateCallbackBase', 'string');
+        return out;
+    }
+    // ── Links factory ────────────────────────────────────────────────
+    /**
+     * Noop links object — used as the `protected links` property in stub drivers.
+     * scheme defaults to 'stub'.
+     */
+    static noopLinks(scheme = 'stub') {
+        return {
+            default: { BASE: `${scheme}://noop` },
+            sandbox: { BASE: `${scheme}://noop` },
+        };
+    }
+}
+exports.TSStub = TSStub;
+// ═══════════════════════════════════════════════════════════════════
+// Internal helpers
+// ═══════════════════════════════════════════════════════════════════
+function timingSafeCompare(a, b) {
+    const ba = Buffer.from(a, 'utf8');
+    const bb = Buffer.from(b, 'utf8');
+    if (ba.length !== bb.length)
+        return false;
+    return (0, node_crypto_1.timingSafeEqual)(ba, bb);
+}

package/utils/abort.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared abort helpers for any package that depends on `ts-server-lib` (HTTP via {@link TSRequest},
+ * SMTP, perf stubs, etc.). Prefer `signal` on HTTP options where supported; use these for timers
+ * and APIs that do not accept `AbortSignal` natively.
+ */
+/** DOM-style abort error (`name === 'AbortError'`). Uses `DOMException` when available. */
+export declare function abortError(): Error;
+export declare function throwIfAborted(signal?: AbortSignal | null): void;
+/**
+ * Sleep for `ms` that rejects with `AbortError` if `signal` aborts first.
+ * With no `signal`, behaves like `setTimeout` sleep.
+ */
+export declare function abortableDelay(ms: number, signal?: AbortSignal | null): Promise<void>;
+/**
+ * Await `operation` unless `signal` aborts first. When aborted, runs `onAbort` (e.g. close a socket)
+ * then rejects with `AbortError`. With no `signal`, returns `operation` unchanged.
+ */
+export declare function raceWithAbort<T>(operation: Promise<T>, signal: AbortSignal | undefined | null, onAbort?: () => void): Promise<T>;

package/utils/abort.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Shared abort helpers for any package that depends on `ts-server-lib` (HTTP via {@link TSRequest},
+ * SMTP, perf stubs, etc.). Prefer `signal` on HTTP options where supported; use these for timers
+ * and APIs that do not accept `AbortSignal` natively.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.abortError = abortError;
+exports.throwIfAborted = throwIfAborted;
+exports.abortableDelay = abortableDelay;
+exports.raceWithAbort = raceWithAbort;
+/** DOM-style abort error (`name === 'AbortError'`). Uses `DOMException` when available. */
+function abortError() {
+    if (typeof DOMException !== 'undefined') {
+        return new DOMException('The operation was aborted', 'AbortError');
+    }
+    const e = new Error('The operation was aborted');
+    e.name = 'AbortError';
+    return e;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw abortError();
+    }
+}
+/**
+ * Sleep for `ms` that rejects with `AbortError` if `signal` aborts first.
+ * With no `signal`, behaves like `setTimeout` sleep.
+ */
+async function abortableDelay(ms, signal) {
+    if (ms <= 0) {
+        return;
+    }
+    if (!signal) {
+        await new Promise((resolve) => setTimeout(resolve, ms));
+        return;
+    }
+    throwIfAborted(signal);
+    await new Promise((resolve, reject) => {
+        const t = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(t);
+            signal.removeEventListener('abort', onAbort);
+            reject(abortError());
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * Await `operation` unless `signal` aborts first. When aborted, runs `onAbort` (e.g. close a socket)
+ * then rejects with `AbortError`. With no `signal`, returns `operation` unchanged.
+ */
+async function raceWithAbort(operation, signal, onAbort) {
+    if (!signal) {
+        return operation;
+    }
+    throwIfAborted(signal);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const detachAbort = () => {
+            signal.removeEventListener('abort', onAbortHandler);
+        };
+        const onAbortHandler = () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            detachAbort();
+            try {
+                onAbort?.();
+            }
+            catch {
+                /* ignore */
+            }
+            reject(abortError());
+        };
+        signal.addEventListener('abort', onAbortHandler, { once: true });
+        operation.then((value) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            detachAbort();
+            resolve(value);
+        }, (err) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            detachAbort();
+            reject(err);
+        });
+    });
+}