wafio-client 1.0.0

package/dist/index.js

@@ -0,0 +1,766 @@
+/**
+ * Wafio client: TCP mTLS client for Wafio WAF server.
+ * Send requests for analysis (analyze) and check block status (checkBlock).
+ * Works with Node.js and Bun.
+ */
+import * as fs from "fs";
+import * as tls from "tls";
+// --- Frame type constants (must match server) ---
+const TYPE_CHECK_BLOCK_REQ = 0x01;
+const TYPE_ANALYZE_REQ = 0x02;
+const TYPE_TIER_LIMITS_REQ = 0x03;
+const TYPE_CHECK_BLOCK_RESP = 0x81;
+const TYPE_ANALYZE_RESP = 0x82;
+const TYPE_TIER_LIMITS_RESP = 0x83;
+/** Normalize connection errors so caller gets a single Error with .code (e.g. ECONNREFUSED) for fail-open. */
+function normalizeConnectError(err, host, port) {
+    const code = getConnectErrorCode(err);
+    const msg = code === "ECONNREFUSED"
+        ? `Wafio server unreachable at ${host}:${port} (ECONNREFUSED). Is the server running?`
+        : err instanceof Error
+            ? err.message
+            : String(err);
+    const out = err instanceof Error ? err : new Error(String(err));
+    if (code) {
+        out.code = code;
+    }
+    out.message = msg;
+    return out;
+}
+const CONNECTION_ERROR_CODES = ["ECONNREFUSED", "ENOTFOUND", "ETIMEDOUT", "ECONNRESET", "ENETUNREACH", "EPIPE"];
+function getConnectErrorCode(err) {
+    if (err && typeof err === "object") {
+        const c = err.code;
+        if (typeof c === "string" && CONNECTION_ERROR_CODES.includes(c))
+            return c;
+        const agg = err;
+        if (Array.isArray(agg.errors)) {
+            for (const e of agg.errors) {
+                const inner = getConnectErrorCode(e);
+                if (inner)
+                    return inner;
+            }
+        }
+    }
+    return undefined;
+}
+function normalizePem(pem) {
+    if (typeof pem !== "string")
+        return "";
+    let s = pem.replace(/\\n/g, "\n").replace(/\r\n/g, "\n");
+    if (s.length > 0 && s[s.length - 1] !== "\n")
+        s += "\n";
+    return s;
+}
+function parseAndNormalizeMtlsFile(filePath, data) {
+    if (!data.client_cert_pem || !data.client_key_pem) {
+        throw new Error("JSON file must contain client_cert_pem and client_key_pem");
+    }
+    if (!data.ca_pem) {
+        throw new Error("JSON file must contain ca_pem (credentials from Wafio API include ca_pem)");
+    }
+    const cert = normalizePem(data.client_cert_pem);
+    const key = normalizePem(data.client_key_pem);
+    const ca = normalizePem(data.ca_pem);
+    if (!cert.includes("BEGIN CERTIFICATE") || !cert.includes("END CERTIFICATE")) {
+        throw new Error("client_cert_pem must be valid PEM with BEGIN/END CERTIFICATE");
+    }
+    if (!key.includes("BEGIN") || !key.includes("PRIVATE KEY")) {
+        throw new Error("client_key_pem must be valid PEM with BEGIN PRIVATE KEY");
+    }
+    return {
+        client_cert_pem: cert,
+        client_key_pem: key,
+        ca_pem: ca,
+        tcp_url: typeof data.tcp_url === "string" ? data.tcp_url.trim() : undefined,
+    };
+}
+/**
+ * Load the mtls-credentials.json file (saved from Wafio API, e.g. POST /api/projects/:id/mtls-keys).
+ * The file must contain client_cert_pem, client_key_pem, and ca_pem.
+ *
+ * @param filePath - Path ke file JSON (e.g. "./mtls-credentials.json")
+ * @returns WafioCredentials untuk new WafioClient({ credentials: ... })
+ */
+export function loadMtlsCredentialsFile(filePath) {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const data = JSON.parse(raw);
+    return parseAndNormalizeMtlsFile(filePath, data);
+}
+/**
+ * Load credentials from a JSON file (same format as mtls-credentials.json).
+ */
+export function loadCredentialsFromFile(filePath) {
+    return loadMtlsCredentialsFile(filePath);
+}
+/**
+ * Load the full mtls-credentials.json and return the parsed object (includes project_id, secret, etc.).
+ */
+export function loadMtlsCredentialsFileFull(filePath) {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const data = JSON.parse(raw);
+    const creds = parseAndNormalizeMtlsFile(filePath, data);
+    return { ...data, ...creds };
+}
+/**
+ * Generic helper to add an application‑level timeout to a Wafio operation.
+ * Does not change the internal client timeout; only wraps the promise with an extra time limit.
+ *
+ * @param p - Wafio operation promise (e.g. pool.analyze()).
+ * @param ms - Timeout in milliseconds. 0/negative = no extra timeout.
+ * @param onTimeout - Optional callback invoked before rejecting when the timeout elapses.
+ *                    Useful for logging/metrics or building a custom error.
+ */
+export function withWafioTimeout(p, ms, onTimeout) {
+    if (!ms || ms <= 0)
+        return p;
+    return Promise.race([
+        p,
+        new Promise((_, reject) => setTimeout(() => {
+            if (onTimeout)
+                onTimeout();
+            reject(new Error("Wafio timeout"));
+        }, ms)),
+    ]);
+}
+/**
+ * Resolve credentials: if string, load from file; otherwise use object and normalize PEMs.
+ */
+function parseTcpEndpoint(raw) {
+    if (!raw || typeof raw !== "string")
+        return null;
+    let endpoint = raw.trim();
+    if (!endpoint)
+        return null;
+    endpoint = endpoint
+        .replace(/^tls:\/\//i, "")
+        .replace(/^tcp:\/\//i, "")
+        .replace(/^https?:\/\//i, "");
+    const slashIndex = endpoint.indexOf("/");
+    if (slashIndex >= 0)
+        endpoint = endpoint.slice(0, slashIndex);
+    if (endpoint.startsWith(":"))
+        endpoint = `localhost${endpoint}`;
+    try {
+        const url = new URL(`tcp://${endpoint}`);
+        const host = url.hostname || "localhost";
+        const port = Number(url.port || "9089");
+        if (!Number.isInteger(port) || port <= 0 || port > 65535)
+            return null;
+        return { host, port };
+    }
+    catch {
+        return null;
+    }
+}
+function resolveCredentials(credentials) {
+    let cred;
+    if (typeof credentials === "string") {
+        cred = loadMtlsCredentialsFileFull(credentials);
+    }
+    else {
+        cred = {
+            client_cert_pem: normalizePem(credentials.client_cert_pem),
+            client_key_pem: normalizePem(credentials.client_key_pem),
+            ca_pem: credentials.ca_pem ? normalizePem(credentials.ca_pem) : undefined,
+            tcp_url: credentials.tcp_url,
+        };
+    }
+    if (!cred.ca_pem) {
+        throw new Error("CA PEM is required (credentials object must include ca_pem)");
+    }
+    return {
+        cert: cred.client_cert_pem,
+        key: cred.client_key_pem,
+        ca: cred.ca_pem,
+        tcpUrl: cred.tcp_url,
+    };
+}
+/** Normalize headers to Record<string, string[]>. Server expects array per header. */
+export function normalizeHeaders(headers) {
+    if (!headers || typeof headers !== "object")
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(headers)) {
+        if (v === undefined)
+            continue;
+        out[k] = Array.isArray(v) ? v : [v];
+    }
+    return out;
+}
+/** Ambil nilai pertama dari header (case-insensitive). */
+function getFirstHeader(headers, name) {
+    if (!headers)
+        return "";
+    const lower = name.toLowerCase();
+    for (const [k, v] of Object.entries(headers)) {
+        if (k.toLowerCase() === lower && v !== undefined) {
+            const s = Array.isArray(v) ? v[0] : v;
+            return typeof s === "string" ? s.trim() : "";
+        }
+    }
+    return "";
+}
+/**
+ * Resolve client IP from a snapshot: prefer proxy headers (X-Forwarded-For, X-Real-IP, Forwarded) then fall back to remoteAddress.
+ * When running behind a proxy, ensure it sets X-Forwarded-For or X-Real-IP; the leftmost value is treated as the original client.
+ */
+export function resolveClientIp(snapshot) {
+    const headers = snapshot.headers;
+    const xff = getFirstHeader(headers, "x-forwarded-for");
+    if (xff) {
+        const first = xff.split(",")[0]?.trim() ?? "";
+        if (first)
+            return first;
+    }
+    const xri = getFirstHeader(headers, "x-real-ip");
+    if (xri)
+        return xri;
+    const forwarded = getFirstHeader(headers, "forwarded");
+    if (forwarded) {
+        const forMatch = /for\s*=\s*["']?([^"',;\s]+)/i.exec(forwarded);
+        if (forMatch?.[1])
+            return forMatch[1].trim();
+    }
+    return snapshot.remoteAddress ?? "127.0.0.1";
+}
+/**
+ * Build an AnalyzeRequest from a RequestSnapshot (framework‑agnostic).
+ * Client IP is resolved from proxy headers (X-Forwarded-For, X-Real-IP) when present.
+ */
+export function buildAnalyzeRequest(snapshot) {
+    const headers = normalizeHeaders(snapshot.headers);
+    const remote_addr = resolveClientIp(snapshot);
+    const user_agent = snapshot.userAgent ?? getFirstHeader(snapshot.headers, "user-agent");
+    return {
+        method: snapshot.method || "GET",
+        uri: snapshot.url || "/",
+        remote_addr,
+        host: snapshot.host ?? "",
+        headers,
+        body: snapshot.body ?? "",
+        user_agent,
+        request_id: snapshot.requestId ?? "",
+    };
+}
+/**
+ * Convert an Express/Fastify/Hono‑style request (object with method, url, headers, body, ip, get, ...) into a RequestSnapshot.
+ * There is no hard dependency on Express; any framework with a similar shape can be used.
+ */
+export function fromRequest(req) {
+    const url = req.originalUrl ?? req.url ?? "";
+    const headers = req.headers;
+    const body = req.body !== undefined
+        ? (typeof req.body === "string" ? req.body : JSON.stringify(req.body))
+        : undefined;
+    const remoteAddress = req.ip ?? req.socket?.remoteAddress;
+    const host = req.hostname ?? (typeof req.get === "function" ? req.get?.("host") : undefined);
+    return {
+        method: req.method ?? "GET",
+        url,
+        headers,
+        body,
+        remoteAddress,
+        host,
+        requestId: typeof req.get === "function" ? req.get?.("x-request-id") : undefined,
+        userAgent: typeof req.get === "function" ? req.get?.("user-agent") : undefined,
+    };
+}
+/**
+ * Wafio TCP mTLS client.
+ * Connect once, then call analyze() / checkBlock() as needed. Call close() when done.
+ */
+export class WafioClient {
+    socket = null;
+    host;
+    port;
+    cert;
+    key;
+    ca;
+    maxPayloadSize;
+    failOpenOnUnreachable;
+    requestTimeoutMs;
+    reconnectCooldownMs;
+    connectTimeoutMs;
+    onRequestTimeout;
+    logRequestTimeout;
+    keepaliveIntervalMs;
+    failOpenCooldownMs;
+    _unreachable = false;
+    lastUnreachableTime = 0;
+    failOpenUntil = 0;
+    socketBuffer = new Map();
+    keepaliveTimerId = null;
+    inFlightRequests = 0;
+    pingInProgress = false;
+    constructor(options) {
+        const resolved = resolveCredentials(options.credentials);
+        const endpoint = parseTcpEndpoint(resolved.tcpUrl);
+        this.host = options.host ?? endpoint?.host ?? "localhost";
+        this.port = options.port ?? endpoint?.port ?? 9089;
+        this.maxPayloadSize = options.maxPayloadSize ?? 0;
+        this.failOpenOnUnreachable = options.failOpenOnUnreachable ?? true;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 300;
+        this.reconnectCooldownMs = options.reconnectCooldownMs ?? 2000;
+        this.connectTimeoutMs = options.connectTimeoutMs ?? 2000;
+        this.onRequestTimeout = options.onRequestTimeout;
+        this.logRequestTimeout = options.logRequestTimeout ?? false;
+        this.keepaliveIntervalMs = options.keepaliveIntervalMs ?? 25000;
+        this.failOpenCooldownMs = options.failOpenCooldownMs ?? 5000;
+        this.cert = resolved.cert;
+        this.key = resolved.key;
+        this.ca = resolved.ca;
+    }
+    /**
+     * Connect to the Wafio server (mTLS). Must be called before analyze/checkBlock.
+     * On failure (e.g. ECONNREFUSED), rejects with a single Error with .code set so caller can do fail-open.
+     */
+    connect() {
+        return new Promise((resolve, reject) => {
+            if (this.socket) {
+                resolve();
+                return;
+            }
+            this._unreachable = false;
+            const socket = tls.connect({
+                host: this.host,
+                port: this.port,
+                cert: this.cert,
+                key: this.key,
+                ca: this.ca,
+                rejectUnauthorized: true,
+            }, () => {
+                this.socket = socket;
+                socket.setMaxListeners(2048);
+                this.startKeepalive();
+                resolve();
+            });
+            socket.on("error", (err) => {
+                const code = getConnectErrorCode(err);
+                if (code && this.failOpenOnUnreachable) {
+                    this._unreachable = true;
+                    resolve();
+                }
+                else {
+                    reject(normalizeConnectError(err, this.host, this.port));
+                }
+            });
+        });
+    }
+    /** Whether the client is connected. */
+    get connected() {
+        return this.socket != null && !this.socket.destroyed;
+    }
+    startKeepalive() {
+        if (this.keepaliveIntervalMs <= 0 || this.keepaliveTimerId != null)
+            return;
+        this.keepaliveTimerId = setInterval(() => this.tickKeepalive(), this.keepaliveIntervalMs);
+    }
+    stopKeepalive() {
+        if (this.keepaliveTimerId != null) {
+            clearInterval(this.keepaliveTimerId);
+            this.keepaliveTimerId = null;
+        }
+    }
+    destroySocket() {
+        if (this.socket) {
+            this.socket.destroy();
+            this.socketBuffer.delete(this.socket);
+            this.socket = null;
+        }
+        this.lastUnreachableTime = Date.now();
+    }
+    async doKeepalivePing() {
+        const sock = this.socket;
+        if (!sock)
+            return;
+        const p = this.sendFrame(TYPE_CHECK_BLOCK_REQ, { key: "__keepalive__" });
+        const timeoutMs = 2000;
+        await Promise.race([
+            p,
+            new Promise((_, rej) => setTimeout(() => rej(new Error("keepalive timeout")), timeoutMs)),
+        ]);
+    }
+    tickKeepalive() {
+        if (!this.socket || this.socket.destroyed || this.inFlightRequests > 0 || this.pingInProgress)
+            return;
+        this.pingInProgress = true;
+        this.doKeepalivePing()
+            .then(() => {
+            this.pingInProgress = false;
+        })
+            .catch(() => {
+            this.destroySocket();
+            this.stopKeepalive();
+            this.pingInProgress = false;
+        });
+    }
+    /** Wrap promise in timeout; on timeout reject dulu (return allow cepat), cleanup (destroy, log) jalan async. */
+    withRequestTimeout(p) {
+        if (this.requestTimeoutMs <= 0)
+            return p;
+        return new Promise((resolve, reject) => {
+            const t = setTimeout(() => {
+                const err = new Error("Wafio request timeout");
+                err.code = "ETIMEDOUT";
+                reject(err);
+                setImmediate(() => {
+                    this.stopKeepalive();
+                    this.destroySocket();
+                    const timeoutMs = this.requestTimeoutMs;
+                    if (this.onRequestTimeout) {
+                        this.onRequestTimeout({ timeoutMs });
+                    }
+                    else if (this.logRequestTimeout) {
+                        console.info(`Wafio: request timeout (${timeoutMs}ms), request allowed (fail-open)`);
+                    }
+                });
+            }, this.requestTimeoutMs);
+            p.then((v) => {
+                clearTimeout(t);
+                resolve(v);
+            }, (e) => {
+                clearTimeout(t);
+                reject(e);
+            });
+        });
+    }
+    /**
+     * Lazy reconnect: try to connect once when there is no active socket. Uses a cooldown to avoid hammering a down server.
+     * Returns true when connected, false when skipped (cooldown) or failed (fail‑open).
+     */
+    async tryConnectIfNeeded() {
+        if (this.socket?.destroyed === false)
+            return true;
+        this.socket = null;
+        const now = Date.now();
+        if (this.reconnectCooldownMs > 0 && now - this.lastUnreachableTime < this.reconnectCooldownMs) {
+            return false;
+        }
+        this._unreachable = false;
+        try {
+            await Promise.race([
+                this.connect(),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("connect timeout")), this.connectTimeoutMs)),
+            ]);
+            if (this.socket !== null && !this.socket.destroyed)
+                return true;
+            this.lastUnreachableTime = Date.now();
+            return false;
+        }
+        catch {
+            this.lastUnreachableTime = Date.now();
+            return false;
+        }
+    }
+    isTimeoutOrConnectionError(err) {
+        if (err instanceof Error) {
+            if (err.message === "Wafio request timeout" || err.message === "Wafio timeout")
+                return true;
+            const code = err.code;
+            if (typeof code === "string" && CONNECTION_ERROR_CODES.includes(code))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Send a frame and wait for the matching response (same type | 0x80).
+     */
+    sendFrame(type, payload) {
+        const sock = this.socket;
+        if (!sock) {
+            return Promise.reject(new Error("WafioClient: not connected. Call connect() first."));
+        }
+        const body = Buffer.from(JSON.stringify(payload), "utf8");
+        if (this.maxPayloadSize > 0 && body.length > this.maxPayloadSize) {
+            return Promise.reject(new Error(`WafioClient: payload too large (max ${this.maxPayloadSize})`));
+        }
+        const len = Buffer.allocUnsafe(4);
+        len.writeUInt32BE(body.length, 0);
+        sock.write(Buffer.concat([Buffer.from([type]), len, body]));
+        return this.readFrame(sock);
+    }
+    readFrame(socket) {
+        return new Promise((resolve, reject) => {
+            if (!this.socketBuffer.has(socket)) {
+                this.socketBuffer.set(socket, Buffer.alloc(0));
+            }
+            const tryConsume = () => {
+                const buf = this.socketBuffer.get(socket);
+                if (buf.length < 5)
+                    return false;
+                const bodyLen = buf.readUInt32BE(1);
+                if (buf.length < 5 + bodyLen)
+                    return false;
+                const type = buf[0];
+                const bodyStr = buf.subarray(5, 5 + bodyLen).toString("utf8");
+                this.socketBuffer.set(socket, buf.subarray(5 + bodyLen));
+                try {
+                    resolve({ type, body: JSON.parse(bodyStr) });
+                }
+                catch {
+                    resolve({ type, body: { error: "invalid json" } });
+                }
+                return true;
+            };
+            if (tryConsume())
+                return;
+            const onData = (chunk) => {
+                const part = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, "utf8");
+                this.socketBuffer.set(socket, Buffer.concat([this.socketBuffer.get(socket), part]));
+                if (tryConsume()) {
+                    socket.off("data", onData);
+                    socket.off("error", onError);
+                }
+            };
+            const onError = (err) => {
+                socket.off("data", onData);
+                reject(err);
+            };
+            socket.on("data", onData);
+            socket.on("error", onError);
+        });
+    }
+    /**
+     * Request tier limits from the server (max_tcp_connections). Use once after connect() to cap pool size.
+     * Returns undefined on error or if server does not support tier limits.
+     */
+    async getTierLimits() {
+        const sock = this.socket;
+        if (!sock)
+            return undefined;
+        try {
+            const { type, body } = await this.sendFrame(TYPE_TIER_LIMITS_REQ, {});
+            if (type !== TYPE_TIER_LIMITS_RESP || typeof body !== "object" || body === null)
+                return undefined;
+            const max = body.max_tcp_connections;
+            return typeof max === "number" && max >= 0 ? max : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Analyze a request. Returns allow/block and metadata.
+     * Uses lazy reconnect: when there is no socket, it tries to connect once (with cooldown). On timeout/unreachable
+     * it returns allow when failOpenOnUnreachable is enabled.
+     */
+    async analyze(req) {
+        if (this.failOpenOnUnreachable && this.failOpenUntil > 0 && Date.now() < this.failOpenUntil) {
+            return { action: "allow" };
+        }
+        if (!this.socket) {
+            const ok = await this.tryConnectIfNeeded();
+            if (!ok && this.failOpenOnUnreachable)
+                return { action: "allow" };
+            if (!this.socket)
+                return { action: "allow" };
+        }
+        this.inFlightRequests++;
+        try {
+            const payload = {
+                method: req.method,
+                uri: req.uri,
+                remote_addr: req.remote_addr,
+                host: req.host ?? "",
+                headers: req.headers ?? {},
+                body: req.body ?? "",
+                body_b64: req.body_b64 ?? "",
+                user_agent: req.user_agent ?? "",
+                request_id: req.request_id ?? "",
+            };
+            if (req.body_size != null && req.body_size > 0) {
+                payload.body_size = req.body_size;
+            }
+            const sendPromise = this.sendFrame(TYPE_ANALYZE_REQ, payload);
+            const { type, body } = await (this.requestTimeoutMs > 0 ? this.withRequestTimeout(sendPromise) : sendPromise);
+            if (type !== TYPE_ANALYZE_RESP) {
+                return { action: "allow", error: "unexpected response type" };
+            }
+            const resp = body;
+            // Treat server-side concurrency/rate shaping as soft fail-open for the app.
+            if (resp.code === "RATE_LIMIT" || resp.code === "CONCURRENCY_LIMIT") {
+                return { action: "allow", error: resp.error, message: resp.message, categories: resp.categories };
+            }
+            return resp;
+        }
+        catch (err) {
+            if (this.failOpenOnUnreachable && this.isTimeoutOrConnectionError(err)) {
+                if (this.failOpenCooldownMs > 0) {
+                    this.failOpenUntil = Date.now() + this.failOpenCooldownMs;
+                }
+                return { action: "allow" };
+            }
+            throw err;
+        }
+        finally {
+            this.inFlightRequests--;
+        }
+    }
+    /**
+     * Check if a key is currently in the block window.
+     * Uses lazy reconnect when there is no socket; on timeout/unreachable it returns not blocked when
+     * failOpenOnUnreachable is enabled.
+     */
+    async checkBlock(key) {
+        if (this.failOpenOnUnreachable && this.failOpenUntil > 0 && Date.now() < this.failOpenUntil) {
+            return { blocked: false };
+        }
+        if (!this.socket) {
+            const ok = await this.tryConnectIfNeeded();
+            if (!ok && this.failOpenOnUnreachable)
+                return { blocked: false };
+            if (!this.socket)
+                return { blocked: false };
+        }
+        this.inFlightRequests++;
+        try {
+            const sendPromise = this.sendFrame(TYPE_CHECK_BLOCK_REQ, { key: key || "unknown" });
+            const { type, body } = await (this.requestTimeoutMs > 0 ? this.withRequestTimeout(sendPromise) : sendPromise);
+            if (type !== TYPE_CHECK_BLOCK_RESP) {
+                return { blocked: false, error: "unexpected response type" };
+            }
+            const resp = body;
+            if (resp.code === "RATE_LIMIT" || resp.code === "CONCURRENCY_LIMIT") {
+                return { blocked: false, error: resp.error };
+            }
+            return resp;
+        }
+        catch (err) {
+            if (this.failOpenOnUnreachable && this.isTimeoutOrConnectionError(err)) {
+                if (this.failOpenCooldownMs > 0) {
+                    this.failOpenUntil = Date.now() + this.failOpenCooldownMs;
+                }
+                return { blocked: false };
+            }
+            throw err;
+        }
+        finally {
+            this.inFlightRequests--;
+        }
+    }
+    /**
+     * Close the connection.
+     */
+    close() {
+        this.stopKeepalive();
+        if (this.socket) {
+            this.socket.destroy();
+            this.socketBuffer.delete(this.socket);
+            this.socket = null;
+        }
+    }
+}
+/**
+ * Simple connection pool for WafioClient.
+ * On first init(), opens one connection to fetch tier limits (max_tcp_connections) and caps pool size to that;
+ * then creates up to that many connections. If the fetch fails, uses the configured pool size.
+ */
+export class WafioClientPool {
+    options;
+    /** Configured pool size (from options). */
+    configuredPoolSize;
+    /** Effective pool size (capped by tier limit after first init). */
+    effectivePoolSize;
+    clients = [];
+    available = [];
+    initPromise = null;
+    constructor(options) {
+        const { poolSize, ...clientOpts } = options;
+        this.options = clientOpts;
+        this.configuredPoolSize = Math.max(1, poolSize ?? 5);
+        this.effectivePoolSize = this.configuredPoolSize;
+    }
+    /** Initialize the pool: fetch tier limits once, cap size, then create WafioClient instances (lazy connection). Idempotent. */
+    async init() {
+        if (this.clients.length >= this.effectivePoolSize)
+            return;
+        if (this.initPromise)
+            return this.initPromise;
+        this.initPromise = (async () => {
+            // One connection just to get tier limits; does not count toward project connection limit.
+            const tempClient = new WafioClient(this.options);
+            let maxConns = null;
+            let probeErr = null;
+            try {
+                await tempClient.connect();
+                maxConns = (await tempClient.getTierLimits()) ?? null;
+                if (typeof maxConns === "number" && maxConns > 0) {
+                    this.effectivePoolSize = Math.min(this.configuredPoolSize, maxConns);
+                    if (this.effectivePoolSize < this.configuredPoolSize) {
+                        console.error(`[wafio-client] Pool size capped by server tier limit: configured=${this.configuredPoolSize}, effective=${this.effectivePoolSize} (server max_tcp_connections=${maxConns})`);
+                    }
+                    else {
+                        console.error(`[wafio-client] Pool size initialized: configured=${this.configuredPoolSize}, effective=${this.effectivePoolSize} (server max_tcp_connections=${maxConns} allows full size)`);
+                    }
+                }
+                else {
+                    console.error(`[wafio-client] Pool size probe failed or server returned 0, using configured size: ${this.configuredPoolSize} (maxConns=${maxConns})`);
+                }
+            }
+            catch (err) {
+                probeErr = err instanceof Error ? err : new Error(String(err));
+                console.error(`[wafio-client] Pool size probe failed, using configured size: ${this.configuredPoolSize} (err=${probeErr.message})`);
+            }
+            finally {
+                tempClient.close();
+            }
+            // Create effectivePoolSize clients (lazy connection: connection established per request by analyze/checkBlock).
+            for (let i = 0; i < this.effectivePoolSize; i++) {
+                const client = new WafioClient(this.options);
+                this.clients.push(client);
+                this.available.push(client);
+            }
+        })();
+        return this.initPromise;
+    }
+    /** Get a client from the pool (waits if all are in use). */
+    async getClient() {
+        if (this.available.length > 0) {
+            return this.available.pop();
+        }
+        return new Promise((resolve) => {
+            const tryGet = () => {
+                if (this.available.length > 0) {
+                    resolve(this.available.pop());
+                }
+                else {
+                    setImmediate(tryGet);
+                }
+            };
+            setImmediate(tryGet);
+        });
+    }
+    /** Return a client to the pool (including disconnected ones; the client will lazy‑reconnect on next use). */
+    releaseClient(client) {
+        this.available.push(client);
+    }
+    /** Generic helper: run a function with a single client from the pool. */
+    async withClient(fn) {
+        await this.init();
+        const client = await this.getClient();
+        try {
+            return await fn(client);
+        }
+        finally {
+            this.releaseClient(client);
+        }
+    }
+    /** Call analyze() using a client from the pool. */
+    analyze(req) {
+        return this.withClient((c) => c.analyze(req));
+    }
+    /** Call checkBlock() using a client from the pool. */
+    checkBlock(key) {
+        return this.withClient((c) => c.checkBlock(key));
+    }
+    /** Close all connections in the pool. */
+    close() {
+        for (const c of this.clients) {
+            c.close();
+        }
+        this.clients.splice(0, this.clients.length);
+        this.available.splice(0, this.available.length);
+        this.initPromise = null;
+    }
+}