threadforge 0.1.1 → 0.2.1

package/dist/plugins/index.js

@@ -0,0 +1,1942 @@
+/**
+ * ThreadForge Built-in Plugins
+ *
+ *   import { redis, postgres, s3, cors, cron, realtime } from 'threadforge/plugins';
+ */
+async function importModuleDynamically(specifier) {
+    return (await import(specifier));
+}
+// ─── Redis ─────────────────────────────────────────────────
+export function redis(options = {}) {
+    const url = options.url ?? `redis://${options.host ?? "127.0.0.1"}:${options.port ?? 6379}/${options.db ?? 0}`;
+    const poolSize = Math.max(1, Math.min(options.poolSize ?? 2, 8));
+    return {
+        name: "redis",
+        version: "1.0.0",
+        inject: "redis",
+        validate() {
+            try {
+                new URL(url);
+            }
+            catch {
+                throw new Error(`Invalid Redis URL: ${url}`);
+            }
+        },
+        env() {
+            // REL-C2: Sanitize URL before propagating to env — strip credentials
+            // to prevent exposure via /proc/<pid>/environ. The connect() function
+            // uses the original `url` variable from closure scope.
+            try {
+                const parsed = new URL(url);
+                parsed.username = "";
+                parsed.password = "";
+                return { FORGE_REDIS_URL: parsed.toString() };
+            }
+            catch {
+                return { FORGE_REDIS_URL: url };
+            }
+        },
+        async connect(ctx) {
+            let RedisClientCtor;
+            try {
+                RedisClientCtor = (await importModuleDynamically("ioredis")).default;
+            }
+            catch {
+                // P16: Pool built-in Redis connections to avoid head-of-line blocking
+                if (poolSize <= 1) {
+                    return _mkRedis(url, ctx);
+                }
+                return _mkRedisPool(url, ctx, poolSize);
+            }
+            // ioredis is available — connection errors should propagate
+            const c = new RedisClientCtor(url, {
+                keyPrefix: options.keyPrefix ?? "",
+                maxRetriesPerRequest: 3,
+                lazyConnect: true,
+            });
+            await c.connect();
+            return c;
+        },
+        async healthCheck(c) {
+            try {
+                return { status: (await c.ping()) === "PONG" ? "ok" : "degraded" };
+            }
+            catch (e) {
+                return { status: "error", error: e.message };
+            }
+        },
+        async disconnect(c) {
+            await c.quit?.();
+        },
+        metrics(c) {
+            return { connected: c.status === "ready" ? 1 : 0 };
+        },
+        nginx() {
+            return options.commanderUI
+                ? {
+                    locations: [
+                        { path: "/admin/redis", config: "proxy_pass http://127.0.0.1:8081;\nproxy_set_header Host $host;" },
+                    ],
+                }
+                : {};
+        },
+    };
+}
+/**
+ * Convert a RESP value to a string if it's a Buffer.
+ * Returns null unchanged. For ioredis API compatibility.
+ * @internal
+ */
+function _bufToStr(v) {
+    if (v === null || v === undefined)
+        return v;
+    if (Buffer.isBuffer(v))
+        return v.toString("utf8");
+    return v;
+}
+/** @internal Exported for testing only */
+export async function _mkRedis(url, ctx) {
+    const net = await import("node:net");
+    const p = new URL(url);
+    const host = p.hostname || "127.0.0.1";
+    const port = parseInt(p.port || "6379", 10);
+    const MAX_REDIS_BUFFER = 16 * 1024 * 1024; // 16 MB
+    let socket = null;
+    let connected = false;
+    const rq = [];
+    let bufChunks = [];
+    let bufTotalLen = 0;
+    const CRLF = Buffer.from("\r\n");
+    // Reconnection state
+    let intentionalClose = false;
+    let reconnectAttempts = 0;
+    let reconnectTimer = null;
+    let subReconnectAttempts = 0;
+    let subReconnectTimer = null;
+    let subConnecting = null;
+    const MAX_RECONNECT_RETRIES = 10;
+    const BASE_RECONNECT_DELAY = 1000;
+    const MAX_RECONNECT_DELAY = 30000;
+    // C-PLUGIN-5: Helper to cleanly destroy socket and prevent leaks
+    function destroySocket() {
+        if (socket) {
+            socket.removeAllListeners();
+            socket.destroy();
+            socket = null;
+        }
+    }
+    function conn() {
+        return new Promise((ok, no) => {
+            // C-PLUGIN-5: Destroy previous socket before creating new one
+            destroySocket();
+            socket = net.connect({ host, port });
+            socket.on("connect", () => {
+                connected = true;
+                reconnectAttempts = 0;
+                ok();
+            });
+            socket.on("error", (err) => {
+                if (!connected)
+                    return no(err);
+                ctx.logger.warn(`Redis socket error: ${err.message}`);
+            });
+            socket.on("data", (d) => {
+                if (bufTotalLen + d.length > MAX_REDIS_BUFFER) {
+                    socket.destroy(new Error("Redis response buffer overflow"));
+                    return;
+                }
+                // P-7: Accumulate chunks in array, concat only when parsing needs contiguous buffer
+                bufChunks.push(d);
+                bufTotalLen += d.length;
+                flush();
+            });
+            socket.on("close", () => {
+                connected = false;
+                clientRef.status = "disconnected";
+                // Reject pending requests
+                const pending = rq.splice(0);
+                for (const r of pending)
+                    r.no(new Error("Redis connection closed"));
+                bufChunks = [];
+                bufTotalLen = 0;
+                if (intentionalClose)
+                    return;
+                scheduleReconnect();
+            });
+        });
+    }
+    function scheduleReconnect() {
+        if (reconnectTimer !== null)
+            return; // Already reconnecting
+        if (reconnectAttempts >= MAX_RECONNECT_RETRIES) {
+            ctx.logger.error(`Redis reconnect failed after ${MAX_RECONNECT_RETRIES} attempts, giving up`);
+            clientRef.status = "disconnected";
+            // M-PLUGIN-4: Reject all pending requests on reconnect exhaustion
+            const pending = rq.splice(0);
+            for (const r of pending)
+                r.no(new Error("Redis reconnect failed"));
+            // C-PLUGIN-5: Clean up socket
+            destroySocket();
+            return;
+        }
+        const delay = Math.min(BASE_RECONNECT_DELAY * 2 ** reconnectAttempts, MAX_RECONNECT_DELAY);
+        reconnectAttempts++;
+        ctx.logger.warn(`Redis reconnecting in ${delay}ms (attempt ${reconnectAttempts}/${MAX_RECONNECT_RETRIES})`);
+        reconnectTimer = setTimeout(async () => {
+            reconnectTimer = null;
+            try {
+                await conn();
+                // Re-authenticate and select DB after reconnect
+                if (p.password)
+                    await cmd("AUTH", p.password);
+                const db = parseInt(p.pathname?.slice(1) || "0", 10);
+                if (db > 0)
+                    await cmd("SELECT", String(db));
+                clientRef.status = "ready";
+                ctx.logger.info("Redis reconnected (built-in client)", { host, port });
+            }
+            catch (err) {
+                ctx.logger.warn(`Redis reconnect attempt ${reconnectAttempts} failed: ${err.message}`);
+                scheduleReconnect();
+            }
+        }, delay);
+    }
+    const MAX_NEST_DEPTH = 32;
+    const MAX_RESP_ARRAY = 10_000;
+    const MAX_RESP_BULK = 16 * 1024 * 1024; // 16MB
+    let flush = function flush() {
+        // P-7: Concat accumulated chunks into a single buffer for parsing
+        if (bufChunks.length === 0 || rq.length === 0)
+            return;
+        let buf = bufChunks.length === 1 ? bufChunks[0] : Buffer.concat(bufChunks, bufTotalLen);
+        bufChunks = [];
+        bufTotalLen = 0;
+        while (buf.length && rq.length) {
+            let r;
+            try {
+                r = parse(buf, 0);
+            }
+            catch (err) {
+                // Parse error — reject ALL pending requests (not just the first) since
+                // the buffer is corrupted and remaining responses cannot be matched.
+                const pending = rq.splice(0);
+                for (const req of pending)
+                    req.no(err);
+                // Force reconnection to recover clean protocol state
+                if (socket)
+                    socket.destroy();
+                return;
+            }
+            if (!r)
+                break;
+            buf = r.rem;
+            rq.shift().ok(r.val);
+        }
+        // Keep remaining unparsed data for next flush
+        if (buf.length > 0) {
+            bufChunks.push(buf);
+            bufTotalLen = buf.length;
+        }
+    };
+    function parse(d, depth) {
+        if (!d.length)
+            return null;
+        if (depth > MAX_NEST_DEPTH) {
+            throw new Error("RESP array nesting too deep");
+        }
+        const t = d[0]; // byte value: '+' = 43, '-' = 45, ':' = 58, '$' = 36, '*' = 42
+        const nl = d.indexOf(CRLF[0]); // find \r
+        if (nl === -1 || nl + 1 >= d.length || d[nl + 1] !== CRLF[1])
+            return null;
+        const line = d.slice(1, nl).toString("utf8");
+        const afterCrlf = d.slice(nl + 2);
+        // Simple string
+        if (t === 0x2b)
+            return { val: line, rem: afterCrlf };
+        // Error
+        if (t === 0x2d)
+            return { val: new Error(line), rem: afterCrlf };
+        // Integer
+        if (t === 0x3a)
+            return { val: parseInt(line, 10), rem: afterCrlf };
+        // Bulk string — payload is raw Buffer
+        if (t === 0x24) {
+            const len = parseInt(line, 10);
+            if (len < -1 || len > MAX_RESP_BULK) {
+                throw new Error(`RESP bulk string length out of bounds: ${len}`);
+            }
+            if (len === -1)
+                return { val: null, rem: afterCrlf };
+            // Need len bytes + \r\n after the data
+            if (afterCrlf.length < len + 2)
+                return null;
+            const val = Buffer.from(afterCrlf.subarray(0, len));
+            return { val, rem: afterCrlf.subarray(len + 2) };
+        }
+        // Array
+        if (t === 0x2a) {
+            const cnt = parseInt(line, 10);
+            if (cnt < -1 || cnt > MAX_RESP_ARRAY) {
+                throw new Error(`RESP array count out of bounds: ${cnt}`);
+            }
+            if (cnt === -1)
+                return { val: null, rem: afterCrlf };
+            let rm = afterCrlf;
+            const a = [];
+            let totalArraySize = 0;
+            for (let i = 0; i < cnt; i++) {
+                const it = parse(rm, depth + 1);
+                if (!it)
+                    return null;
+                // Track total array element sizes
+                if (Buffer.isBuffer(it.val)) {
+                    totalArraySize += it.val.length;
+                    if (totalArraySize > MAX_RESP_BULK) {
+                        throw new Error(`RESP array total size exceeds limit: ${totalArraySize}`);
+                    }
+                }
+                a.push(it.val);
+                rm = it.rem;
+            }
+            return { val: a, rem: rm };
+        }
+        const err = new Error(`Unknown RESP type: '${String.fromCharCode(t)}' (0x${t.toString(16)})`);
+        err.code = "RESP_PARSE_ERROR";
+        throw err;
+    }
+    function cmd(...args) {
+        return new Promise((ok, no) => {
+            if (!connected)
+                return no(new Error("Redis not connected"));
+            // H-PLUGIN-4: Reject arguments containing CR/LF (command injection)
+            for (const a of args) {
+                if (!Buffer.isBuffer(a) && typeof a === "string" && /\r|\n/.test(a)) {
+                    return no(new Error("Redis command argument contains invalid characters (CR/LF)"));
+                }
+            }
+            const header = `*${args.length}\r\n`;
+            const parts = [header];
+            for (const a of args) {
+                if (Buffer.isBuffer(a)) {
+                    parts.push(`$${a.length}\r\n`);
+                    parts.push(a);
+                    parts.push("\r\n");
+                }
+                else {
+                    const s = String(a);
+                    parts.push(`$${Buffer.byteLength(s)}\r\n${s}\r\n`);
+                }
+            }
+            rq.push({ ok, no });
+            socket.cork();
+            for (const part of parts) {
+                socket.write(part);
+            }
+            socket.uncork();
+        });
+    }
+    await conn();
+    if (p.password)
+        await cmd("AUTH", p.password);
+    const db = parseInt(p.pathname?.slice(1) || "0", 10);
+    if (db > 0)
+        await cmd("SELECT", String(db));
+    ctx.logger.info("Redis connected (built-in client)", { host, port });
+    const clientRef = {
+        status: "ready",
+        get: async (k) => _bufToStr(await cmd("GET", k)),
+        set: (...a) => cmd("SET", ...a),
+        del: (...k) => cmd("DEL", ...k),
+        hget: async (k, f) => _bufToStr(await cmd("HGET", k, f)),
+        hset: (k, f, v) => cmd("HSET", k, f, v),
+        hgetall: async (k) => {
+            const a = await cmd("HGETALL", k);
+            if (!Array.isArray(a))
+                return {};
+            const o = {};
+            for (let i = 0; i < a.length; i += 2)
+                o[_bufToStr(a[i])] = _bufToStr(a[i + 1]);
+            return o;
+        },
+        keys: async (pat) => {
+            const a = await cmd("KEYS", pat);
+            return Array.isArray(a) ? a.map(_bufToStr) : a;
+        },
+        expire: (k, s) => cmd("EXPIRE", k, s),
+        ttl: (k) => cmd("TTL", k),
+        ping: () => cmd("PING"),
+        incr: (k) => cmd("INCR", k),
+        decr: (k) => cmd("DECR", k),
+        lpush: (k, ...v) => cmd("LPUSH", k, ...v),
+        rpush: (k, ...v) => cmd("RPUSH", k, ...v),
+        lrange: async (k, s, e) => {
+            const a = await cmd("LRANGE", k, String(s), String(e));
+            return Array.isArray(a) ? a.map(_bufToStr) : a;
+        },
+        sadd: (k, ...m) => cmd("SADD", k, ...m),
+        smembers: async (k) => {
+            const a = await cmd("SMEMBERS", k);
+            return Array.isArray(a) ? a.map(_bufToStr) : a;
+        },
+        publish: (ch, m) => cmd("PUBLISH", ch, m),
+        // ─── Subscription support (lazy separate connection) ───
+        _subSocket: null,
+        _subConnected: false,
+        _subBufChunks: [],
+        _subBufTotalLen: 0,
+        _subCallbacks: new Map(), // channel → Set<callback>
+        _psubCallbacks: new Map(), // pattern → Set<callback>
+        _subSubscribedChannels: new Set(),
+        _subSubscribedPatterns: new Set(),
+        _subRq: [],
+        async _ensureSubConnection() {
+            if (this._subConnected)
+                return;
+            if (subConnecting)
+                return subConnecting;
+            const subNet = await import("node:net");
+            subConnecting = new Promise((ok, no) => {
+                this._subSocket = subNet.connect({ host, port });
+                this._subSocket.on("connect", () => {
+                    this._subConnected = true;
+                    subReconnectAttempts = 0;
+                    this._subSubscribedChannels.clear();
+                    this._subSubscribedPatterns.clear();
+                    ok();
+                });
+                this._subSocket.on("error", (err) => {
+                    if (!this._subConnected)
+                        return no(err);
+                    ctx.logger.warn(`Redis sub socket error: ${err.message}`);
+                });
+                this._subSocket.on("data", (d) => {
+                    // REL-C1: Guard against unbounded sub buffer growth (same limit as main connection)
+                    if (this._subBufTotalLen + d.length > MAX_REDIS_BUFFER) {
+                        this._subSocket.destroy(new Error("Redis sub response buffer overflow"));
+                        return;
+                    }
+                    // P-8: Chunk-list pattern to avoid O(n^2) Buffer.concat
+                    this._subBufChunks.push(d);
+                    this._subBufTotalLen += d.length;
+                    this._flushSub();
+                });
+                this._subSocket.on("close", () => {
+                    this._subConnected = false;
+                    this._subSubscribedChannels.clear();
+                    this._subSubscribedPatterns.clear();
+                    const pending = this._subRq.splice(0);
+                    for (const r of pending)
+                        r.no(new Error("Redis sub connection closed"));
+                    this._subBufChunks = [];
+                    this._subBufTotalLen = 0;
+                    this._scheduleSubReconnect();
+                });
+            });
+            let connectError = null;
+            try {
+                await subConnecting;
+                // Auth and DB select on sub connection
+                if (p.password) {
+                    await this._subCmd("AUTH", p.password);
+                }
+                const subDb = parseInt(p.pathname?.slice(1) || "0", 10);
+                if (subDb > 0) {
+                    await this._subCmd("SELECT", String(subDb));
+                }
+                // Re-subscribe desired channels/patterns after reconnect.
+                for (const channel of this._subCallbacks.keys()) {
+                    if (this._subSubscribedChannels.has(channel))
+                        continue;
+                    await this._subCmd("SUBSCRIBE", channel);
+                    this._subSubscribedChannels.add(channel);
+                }
+                for (const pattern of this._psubCallbacks.keys()) {
+                    if (this._subSubscribedPatterns.has(pattern))
+                        continue;
+                    await this._subCmd("PSUBSCRIBE", pattern);
+                    this._subSubscribedPatterns.add(pattern);
+                }
+            }
+            catch (err) {
+                connectError = err;
+            }
+            finally {
+                subConnecting = null;
+            }
+            if (connectError) {
+                this._scheduleSubReconnect();
+                throw connectError;
+            }
+        },
+        _scheduleSubReconnect() {
+            if (intentionalClose)
+                return;
+            if (subReconnectTimer !== null || this._subConnected || subConnecting)
+                return;
+            if (subReconnectAttempts >= MAX_RECONNECT_RETRIES) {
+                ctx.logger.error(`Redis sub reconnect failed after ${MAX_RECONNECT_RETRIES} attempts, giving up`);
+                return;
+            }
+            const delay = Math.min(BASE_RECONNECT_DELAY * 2 ** subReconnectAttempts, MAX_RECONNECT_DELAY);
+            subReconnectAttempts++;
+            ctx.logger.warn(`Redis sub reconnecting in ${delay}ms (attempt ${subReconnectAttempts}/${MAX_RECONNECT_RETRIES})`);
+            subReconnectTimer = setTimeout(async () => {
+                subReconnectTimer = null;
+                try {
+                    await this._ensureSubConnection();
+                    ctx.logger.info("Redis sub reconnected (built-in client)", { host, port });
+                }
+                catch (err) {
+                    ctx.logger.warn(`Redis sub reconnect attempt ${subReconnectAttempts} failed: ${err.message}`);
+                    this._scheduleSubReconnect();
+                }
+            }, delay);
+            subReconnectTimer.unref?.();
+        },
+        _subCmd(...args) {
+            return new Promise((ok, no) => {
+                if (!this._subConnected)
+                    return no(new Error("Redis sub not connected"));
+                // H-PLUGIN-4: Reject arguments containing CR/LF (command injection)
+                for (const a of args) {
+                    if (!Buffer.isBuffer(a) && typeof a === "string" && /\r|\n/.test(a)) {
+                        return no(new Error("Redis command argument contains invalid characters (CR/LF)"));
+                    }
+                }
+                const header = `*${args.length}\r\n`;
+                const parts = [header];
+                for (const a of args) {
+                    const s = String(a);
+                    parts.push(`$${Buffer.byteLength(s)}\r\n${s}\r\n`);
+                }
+                this._subRq.push({ ok, no });
+                this._subSocket.cork();
+                for (const part of parts)
+                    this._subSocket.write(part);
+                this._subSocket.uncork();
+            });
+        },
+        _flushSub() {
+            // P-8: Concat accumulated chunks for parsing
+            if (this._subBufChunks.length === 0)
+                return;
+            let buf = this._subBufChunks.length === 1
+                ? this._subBufChunks[0]
+                : Buffer.concat(this._subBufChunks, this._subBufTotalLen);
+            this._subBufChunks = [];
+            this._subBufTotalLen = 0;
+            while (buf.length) {
+                let r;
+                try {
+                    r = parse(buf, 0);
+                }
+                catch {
+                    return;
+                }
+                if (!r)
+                    break;
+                buf = r.rem;
+                const val = r.val;
+                // Messages are arrays: ["message", channel, data] or ["pmessage", pattern, channel, data]
+                if (Array.isArray(val)) {
+                    const type = _bufToStr(val[0]);
+                    if (type === "message") {
+                        const ch = _bufToStr(val[1]);
+                        const data = _bufToStr(val[2]);
+                        const cbs = this._subCallbacks.get(ch);
+                        if (cbs)
+                            for (const cb of cbs)
+                                cb(data, ch);
+                        continue;
+                    }
+                    if (type === "pmessage") {
+                        const pat = _bufToStr(val[1]);
+                        const ch = _bufToStr(val[2]);
+                        const data = _bufToStr(val[3]);
+                        const cbs = this._psubCallbacks.get(pat);
+                        if (cbs)
+                            for (const cb of cbs)
+                                cb(data, ch, pat);
+                        continue;
+                    }
+                    // subscribe/psubscribe confirmations resolve pending _subRq
+                    if (type === "subscribe" || type === "psubscribe") {
+                        if (this._subRq.length)
+                            this._subRq.shift().ok(val);
+                        continue;
+                    }
+                    // unsubscribe/punsubscribe
+                    if (type === "unsubscribe" || type === "punsubscribe") {
+                        if (this._subRq.length)
+                            this._subRq.shift().ok(val);
+                        continue;
+                    }
+                }
+                // Other responses (OK from AUTH/SELECT)
+                if (this._subRq.length)
+                    this._subRq.shift().ok(val);
+            }
+            // Keep remaining unparsed data for next flush
+            if (buf.length > 0) {
+                this._subBufChunks.push(buf);
+                this._subBufTotalLen = buf.length;
+            }
+        },
+        async subscribe(channel, callback) {
+            if (!this._subCallbacks.has(channel)) {
+                this._subCallbacks.set(channel, new Set());
+            }
+            this._subCallbacks.get(channel).add(callback);
+            await this._ensureSubConnection();
+            if (!this._subSubscribedChannels.has(channel)) {
+                await this._subCmd("SUBSCRIBE", channel);
+                this._subSubscribedChannels.add(channel);
+            }
+        },
+        async psubscribe(pattern, callback) {
+            if (!this._psubCallbacks.has(pattern)) {
+                this._psubCallbacks.set(pattern, new Set());
+            }
+            this._psubCallbacks.get(pattern).add(callback);
+            await this._ensureSubConnection();
+            if (!this._subSubscribedPatterns.has(pattern)) {
+                await this._subCmd("PSUBSCRIBE", pattern);
+                this._subSubscribedPatterns.add(pattern);
+            }
+        },
+        quit: () => {
+            if (intentionalClose)
+                return Promise.resolve(); // Guard against double-call
+            // Clean up subscription connection
+            if (clientRef._subSocket) {
+                clientRef._subSocket.removeAllListeners();
+                clientRef._subSocket.destroy();
+                clientRef._subSocket = null;
+                clientRef._subConnected = false;
+                clientRef._subCallbacks.clear();
+                clientRef._psubCallbacks.clear();
+                clientRef._subSubscribedChannels.clear();
+                clientRef._subSubscribedPatterns.clear();
+                clientRef._subBufChunks = [];
+                clientRef._subBufTotalLen = 0;
+                clientRef._subRq.length = 0;
+            }
+            return new Promise((resolve) => {
+                intentionalClose = true;
+                if (reconnectTimer) {
+                    clearTimeout(reconnectTimer);
+                    reconnectTimer = null;
+                }
+                if (subReconnectTimer) {
+                    clearTimeout(subReconnectTimer);
+                    subReconnectTimer = null;
+                }
+                if (rq.length === 0) {
+                    connected = false;
+                    // C-PLUGIN-5: Clean socket shutdown on intentional close
+                    destroySocket();
+                    resolve();
+                    return;
+                }
+                // Event-based drain: resolve when response queue empties
+                const origFlush = flush;
+                flush = function drainFlush() {
+                    origFlush();
+                    if (rq.length === 0) {
+                        flush = origFlush;
+                        connected = false;
+                        destroySocket();
+                        resolve();
+                    }
+                };
+                // Safety timeout in case drain never completes
+                setTimeout(() => {
+                    flush = origFlush;
+                    // Reject all pending requests
+                    const pending = rq.splice(0);
+                    for (const r of pending) {
+                        r.no(new Error("Redis quit timeout - connection forcibly closed"));
+                    }
+                    connected = false;
+                    destroySocket();
+                    resolve();
+                }, 5000).unref();
+            });
+        },
+        disconnect: () => {
+            intentionalClose = true;
+            connected = false;
+            if (reconnectTimer) {
+                clearTimeout(reconnectTimer);
+                reconnectTimer = null;
+            }
+            if (subReconnectTimer) {
+                clearTimeout(subReconnectTimer);
+                subReconnectTimer = null;
+            }
+            // C-PLUGIN-5: Use destroySocket helper
+            destroySocket();
+        },
+    };
+    return clientRef;
+}
+/**
+ * P16: Redis connection pool for the built-in RESP client.
+ * Maintains multiple connections and round-robins commands across them
+ * to avoid head-of-line blocking on a single connection.
+ * @internal
+ */
+async function _mkRedisPool(url, ctx, size) {
+    const connections = [];
+    for (let i = 0; i < size; i++) {
+        connections.push(await _mkRedis(url, ctx));
+    }
+    let rrIndex = 0;
+    function nextConn() {
+        const conn = connections[rrIndex % connections.length];
+        rrIndex = (rrIndex + 1) % 1_000_000_000;
+        return conn;
+    }
+    // Build a pooled client that delegates to underlying connections round-robin
+    const pooled = {
+        status: "ready",
+        get _poolConnections() {
+            return connections;
+        },
+        get: (k) => nextConn().get(k),
+        set: (...a) => nextConn().set(...a),
+        del: (...k) => nextConn().del(...k),
+        hget: (k, f) => nextConn().hget(k, f),
+        hset: (k, f, v) => nextConn().hset(k, f, v),
+        hgetall: (k) => nextConn().hgetall(k),
+        keys: (pat) => nextConn().keys(pat),
+        expire: (k, s) => nextConn().expire(k, s),
+        ttl: (k) => nextConn().ttl(k),
+        ping: () => nextConn().ping(),
+        incr: (k) => nextConn().incr(k),
+        decr: (k) => nextConn().decr(k),
+        lpush: (k, ...v) => nextConn().lpush(k, ...v),
+        rpush: (k, ...v) => nextConn().rpush(k, ...v),
+        lrange: (k, s, e) => nextConn().lrange(k, s, e),
+        sadd: (k, ...m) => nextConn().sadd(k, ...m),
+        smembers: (k) => nextConn().smembers(k),
+        publish: (ch, m) => nextConn().publish(ch, m),
+        // Subscriptions use the first connection's sub support
+        subscribe: (ch, cb) => connections[0].subscribe(ch, cb),
+        psubscribe: (pat, cb) => connections[0].psubscribe(pat, cb),
+        quit: async () => {
+            pooled.status = "disconnected";
+            await Promise.allSettled(connections.map((c) => c.quit()));
+        },
+        disconnect: () => {
+            pooled.status = "disconnected";
+            for (const c of connections)
+                c.disconnect();
+        },
+        // Internal subscription fields (delegated to first connection)
+        _subSocket: null,
+        _subConnected: false,
+        _subBufChunks: [],
+        _subBufTotalLen: 0,
+        _subCallbacks: new Map(),
+        _psubCallbacks: new Map(),
+        _subSubscribedChannels: new Set(),
+        _subSubscribedPatterns: new Set(),
+        _subRq: [],
+        _ensureSubConnection: () => connections[0]._ensureSubConnection(),
+        _scheduleSubReconnect: () => connections[0]._scheduleSubReconnect(),
+        _subCmd: (...args) => connections[0]._subCmd(...args),
+        _flushSub: () => connections[0]._flushSub(),
+    };
+    ctx.logger.info(`Redis pool created (${size} connections)`, { host: new URL(url).hostname });
+    return pooled;
+}
+// ─── PostgreSQL ────────────────────────────────────────────
+export function postgres(options = {}) {
+    const url = options.url ?? process.env.DATABASE_URL;
+    return {
+        name: "postgres",
+        version: "1.0.0",
+        inject: "pg",
+        injectAs: "postgres",
+        validate() {
+            if (!url && !process.env.DATABASE_URL)
+                throw new Error("PostgreSQL plugin requires url or DATABASE_URL");
+        },
+        env() {
+            // M-6 Security: Sanitize URL before propagating to env — strip credentials
+            // to prevent exposure via /proc/<pid>/environ. Same pattern as Redis plugin.
+            // The connect() function uses the original `url` variable from closure scope.
+            if (!url)
+                return {};
+            try {
+                const parsed = new URL(url);
+                if (parsed.username || parsed.password) {
+                    parsed.username = "***";
+                    parsed.password = "***";
+                }
+                return { FORGE_PG_URL: parsed.toString() };
+            }
+            catch {
+                return { FORGE_PG_URL: url };
+            }
+        },
+        async connect(ctx) {
+            // @ts-expect-error pg may not have type declarations installed
+            const pg = await import("pg");
+            const Pool = (pg.default?.Pool ?? pg.Pool);
+            const poolMax = options.poolSize ?? 10;
+            const pool = new Pool({
+                connectionString: url ?? process.env.FORGE_PG_URL,
+                max: poolMax,
+                idleTimeoutMillis: options.idleTimeout ?? 30000,
+                connectionTimeoutMillis: 10000,
+                statement_timeout: 30000,
+            });
+            const c = await pool.connect();
+            c.release();
+            ctx.logger.info("PostgreSQL connected", { pool: poolMax });
+            // H-PLUGIN-1: Pool saturation logging (max once per 60s)
+            let _lastSaturationWarn = 0;
+            const origQuery = pool.query.bind(pool);
+            pool.query = (...args) => {
+                const now = Date.now();
+                if (now - _lastSaturationWarn > 60000) {
+                    if (pool.waitingCount > 0 || pool.idleCount < poolMax * 0.2) {
+                        _lastSaturationWarn = now;
+                        ctx.logger.warn("PostgreSQL pool saturation warning", {
+                            waiting: pool.waitingCount,
+                            idle: pool.idleCount,
+                            total: pool.totalCount,
+                            max: poolMax,
+                        });
+                    }
+                }
+                return origQuery(...args);
+            };
+            return pool;
+        },
+        async healthCheck(pool) {
+            try {
+                await pool.query("SELECT 1");
+                return { status: "ok", total: pool.totalCount, idle: pool.idleCount };
+            }
+            catch (e) {
+                return { status: "error", error: e.message };
+            }
+        },
+        async disconnect(pool) {
+            await pool.end();
+        },
+        metrics(pool) {
+            return { pool_total: pool.totalCount ?? 0, pool_idle: pool.idleCount ?? 0, pool_waiting: pool.waitingCount ?? 0 };
+        },
+        nginx() {
+            return options.pgAdminUI
+                ? {
+                    locations: [
+                        {
+                            path: "/admin/pgadmin",
+                            config: `proxy_pass http://127.0.0.1:${options.pgAdminPort ?? 5050};\nproxy_set_header Host $host;`,
+                        },
+                    ],
+                }
+                : {};
+        },
+    };
+}
+// ─── S3 ────────────────────────────────────────────────────
+// H-PLUGIN-8: S3 key validation helper
+function validateS3Key(key) {
+    if (typeof key !== "string")
+        throw new Error("S3 key must be a string");
+    if (key.length < 1 || key.length > 1024)
+        throw new Error(`S3 key length out of bounds: ${key.length}`);
+    if (key.includes(".."))
+        throw new Error('S3 key must not contain ".."');
+    if (key.startsWith("/"))
+        throw new Error('S3 key must not start with "/"');
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional — validates S3 keys have no control chars
+    if (/[\x00-\x1F\x7F]/.test(key))
+        throw new Error("S3 key must not contain control characters");
+}
+const MAX_STUB_SIZE = 100 * 1024 * 1024; // 100MB total
+const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB per file
+export function s3(options = {}) {
+    return {
+        name: "s3",
+        version: "1.0.0",
+        inject: "storage",
+        injectAs: "s3",
+        validate() {
+            if (!options.bucket)
+                throw new Error("S3 plugin requires bucket");
+        },
+        env() {
+            const e = {};
+            if (options.endpoint)
+                e.FORGE_S3_ENDPOINT = options.endpoint;
+            if (options.region)
+                e.AWS_REGION = options.region;
+            return e;
+        },
+        async connect(ctx) {
+            try {
+                // @ts-expect-error @aws-sdk/client-s3 is an optional dependency
+                const awsS3 = await import("@aws-sdk/client-s3");
+                const S3ClientClass = awsS3.S3Client;
+                const GetObjectCommand = awsS3.GetObjectCommand;
+                const PutObjectCommand = awsS3.PutObjectCommand;
+                const DeleteObjectCommand = awsS3.DeleteObjectCommand;
+                const HeadBucketCommand = awsS3.HeadBucketCommand;
+                const cfg = {
+                    region: options.region ?? "us-east-1",
+                };
+                if (options.endpoint) {
+                    cfg.endpoint = options.endpoint;
+                    cfg.forcePathStyle = true;
+                }
+                const raw = new S3ClientClass(cfg);
+                const bucket = options.bucket;
+                ctx.logger.info("S3 connected", { bucket, region: cfg.region });
+                return {
+                    _isStub: false,
+                    _raw: raw,
+                    _HeadBucketCommand: HeadBucketCommand,
+                    put: (k, b, ct) => {
+                        validateS3Key(k);
+                        return raw.send(new PutObjectCommand({ Bucket: bucket, Key: k, Body: b, ContentType: ct }));
+                    },
+                    get: async (k) => {
+                        validateS3Key(k);
+                        return (await raw.send(new GetObjectCommand({ Bucket: bucket, Key: k }))).Body;
+                    },
+                    del: (k) => {
+                        validateS3Key(k);
+                        return raw.send(new DeleteObjectCommand({ Bucket: bucket, Key: k }));
+                    },
+                    url: (k) => {
+                        validateS3Key(k);
+                        return options.endpoint
+                            ? `${options.endpoint}/${bucket}/${k}`
+                            : `https://${bucket}.s3.${cfg.region}.amazonaws.com/${k}`;
+                    },
+                    bucket,
+                };
+            }
+            catch (_importErr) {
+                if (process.env.NODE_ENV === "production") {
+                    throw new Error(`S3 plugin: @aws-sdk/client-s3 is not installed. ` +
+                        `In production, the in-memory stub is disabled to prevent data loss. ` +
+                        `Install the SDK: npm install @aws-sdk/client-s3`);
+                }
+                const store = new Map();
+                let totalSize = 0;
+                ctx.logger.warn("S3 stub active (install @aws-sdk/client-s3) — NOT safe for production");
+                return {
+                    _isStub: true,
+                    put: async (k, b) => {
+                        validateS3Key(k);
+                        const size = Buffer.isBuffer(b) ? b.length : typeof b === "string" ? Buffer.byteLength(b) : 0;
+                        if (size > MAX_FILE_SIZE)
+                            throw new Error(`S3 stub: file size ${size} exceeds limit of ${MAX_FILE_SIZE}`);
+                        // Subtract old value size if overwriting
+                        const old = store.get(k);
+                        if (old !== undefined) {
+                            const oldSize = Buffer.isBuffer(old)
+                                ? old.length
+                                : typeof old === "string"
+                                    ? Buffer.byteLength(old)
+                                    : 0;
+                            totalSize -= oldSize;
+                        }
+                        if (totalSize + size > MAX_STUB_SIZE)
+                            throw new Error(`S3 stub: total size would exceed limit of ${MAX_STUB_SIZE}`);
+                        totalSize += size;
+                        store.set(k, b);
+                    },
+                    get: async (k) => {
+                        validateS3Key(k);
+                        return store.get(k) ?? null;
+                    },
+                    del: async (k) => {
+                        validateS3Key(k);
+                        const old = store.get(k);
+                        if (old !== undefined) {
+                            const oldSize = Buffer.isBuffer(old)
+                                ? old.length
+                                : typeof old === "string"
+                                    ? Buffer.byteLength(old)
+                                    : 0;
+                            totalSize -= oldSize;
+                        }
+                        store.delete(k);
+                    },
+                    url: (k) => {
+                        validateS3Key(k);
+                        return `mem://${options.bucket}/${k}`;
+                    },
+                    bucket: options.bucket,
+                };
+            }
+        },
+        async healthCheck(s) {
+            if (s._isStub === true)
+                return { status: "degraded", bucket: s.bucket, note: "in-memory stub — data will be lost on restart" };
+            if (s._isStub === false && s._raw && s._HeadBucketCommand) {
+                try {
+                    await s._raw.send(new s._HeadBucketCommand({ Bucket: s.bucket }));
+                    return { status: "ok", bucket: s.bucket };
+                }
+                catch (err) {
+                    return { status: "error", bucket: s.bucket, error: err.message };
+                }
+            }
+            // Fallback for clients not created by connect() (e.g., in tests)
+            return { status: "ok", bucket: s.bucket };
+        },
+        async disconnect() { },
+    };
+}
+// ─── CORS ──────────────────────────────────────────────────
+export function cors(options = {}) {
+    const origins = options.origins ?? [];
+    const methods = options.methods ?? ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+    const headers = options.headers ?? ["Content-Type", "Authorization", "X-Correlation-ID"];
+    const creds = options.credentials ?? false;
+    const maxAge = options.maxAge ?? 86400;
+    if (origins.includes("*") && creds) {
+        throw new Error('CORS misconfiguration: credentials: true is incompatible with origins: ["*"]. ' +
+            "Specify explicit origins or disable credentials.");
+    }
+    return {
+        name: "cors",
+        version: "1.0.0",
+        inject: "_cors",
+        validate() {
+            if (origins.length === 0) {
+                throw new Error("CORS plugin requires explicit origins. Specify allowed origins (e.g., origins: ['https://myapp.com']) " +
+                    'or use origins: ["*"] to allow all origins (not recommended for production).');
+            }
+        },
+        async connect() {
+            return { origins, methods, headers };
+        },
+        middleware() {
+            return function corsMiddleware(req, res, next) {
+                const origin = req.headers.origin;
+                let matched = false;
+                if (origins.includes("*") && !creds) {
+                    res.setHeader("Access-Control-Allow-Origin", "*");
+                    matched = true;
+                }
+                else if (origin) {
+                    // Check exact match first
+                    if (origins.includes(origin)) {
+                        matched = true;
+                    }
+                    else {
+                        // Check wildcard subdomain patterns (e.g., *.example.com)
+                        for (const allowed of origins) {
+                            if (allowed.startsWith("*.")) {
+                                const suffix = allowed.slice(1); // e.g., ".example.com"
+                                try {
+                                    const originHost = new URL(origin).hostname.toLowerCase();
+                                    // REL-C3: *.example.com should NOT match bare example.com — wildcard
+                                    // requires at least one subdomain level. This is the standard interpretation
+                                    // per RFC 6125 and browser SAN matching.
+                                    if (originHost.endsWith(suffix)) {
+                                        // Verify the part before suffix is a valid non-empty subdomain segment
+                                        const beforeSuffix = originHost.slice(0, -suffix.length);
+                                        if (beforeSuffix && /^[a-z0-9]([a-z0-9-]*\.)*$/.test(beforeSuffix)) {
+                                            matched = true;
+                                            break;
+                                        }
+                                    }
+                                }
+                                catch {
+                                    // Invalid origin URL, skip
+                                }
+                            }
+                        }
+                    }
+                    if (matched) {
+                        res.setHeader("Access-Control-Allow-Origin", origin);
+                        if (creds)
+                            res.setHeader("Access-Control-Allow-Credentials", "true");
+                    }
+                }
+                if (matched) {
+                    res.setHeader("Access-Control-Allow-Methods", methods.join(", "));
+                    res.setHeader("Access-Control-Allow-Headers", headers.join(", "));
+                    // M-PLUGIN-3: Expose correlation and custom response headers to frontend JS
+                    res.setHeader("Access-Control-Expose-Headers", "X-Correlation-ID, X-Request-ID, X-Trace-ID");
+                    res.setHeader("Access-Control-Max-Age", String(maxAge));
+                    res.setHeader("Vary", "Origin");
+                }
+                if (req.method === "OPTIONS") {
+                    if (!matched) {
+                        res.writeHead(403);
+                        res.end();
+                        return;
+                    }
+                    res.writeHead(204);
+                    res.end();
+                    return;
+                }
+                next();
+            };
+        },
+        async disconnect() { },
+    };
+}
+// ─── Realtime (WebSocket Utilities) ────────────────────────
+const REALTIME_CHANNEL_RE = /^[a-zA-Z0-9:_-]{1,128}$/;
+const REALTIME_BACKPRESSURE_STRATEGIES = new Set(["drop", "close"]);
+function _assertRealtimeChannel(channel, allowedChannels) {
+    if (typeof channel !== "string" || channel.trim() === "") {
+        throw new Error("Realtime channel must be a non-empty string");
+    }
+    if (!REALTIME_CHANNEL_RE.test(channel)) {
+        throw new Error(`Invalid realtime channel "${channel}". Use [a-zA-Z0-9:_-] (max 128 chars)`);
+    }
+    if (allowedChannels && allowedChannels.size > 0 && !allowedChannels.has(channel)) {
+        throw new Error(`Realtime channel "${channel}" is not in allowedChannels`);
+    }
+}
+function _encodeRealtimeEnvelope(channel, payload, senderId, maxPayloadBytes) {
+    let type = "text";
+    let body = "";
+    if (Buffer.isBuffer(payload)) {
+        type = "base64";
+        body = payload.toString("base64");
+    }
+    else if (typeof payload === "string") {
+        type = "text";
+        body = payload;
+    }
+    else {
+        type = "json";
+        body = JSON.stringify(payload);
+    }
+    const size = Buffer.byteLength(body);
+    if (size > maxPayloadBytes) {
+        throw new Error(`Realtime payload exceeds maxPayloadBytes (${maxPayloadBytes})`);
+    }
+    return {
+        v: 1,
+        senderId,
+        channel,
+        type,
+        body,
+        ts: Date.now(),
+    };
+}
+function _decodeRealtimeEnvelope(envelope) {
+    if (envelope.type === "base64") {
+        return Buffer.from(envelope.body, "base64");
+    }
+    if (envelope.type === "json") {
+        return JSON.parse(envelope.body);
+    }
+    return envelope.body;
+}
+function _sendRealtimePayload(ws, payload) {
+    if (!ws || ws._closed)
+        return false;
+    if (Buffer.isBuffer(payload)) {
+        ws.sendBinary?.(payload);
+    }
+    else if (typeof payload === "string") {
+        ws.send(payload);
+    }
+    else {
+        ws.send(JSON.stringify(payload));
+    }
+    return true;
+}
+function _normalizeRealtimeDecision(decision, fallback = {}) {
+    if (decision === undefined || decision === null || decision === true) {
+        return { allow: true, ...fallback };
+    }
+    if (decision === false) {
+        return { allow: false, ...fallback };
+    }
+    if (typeof decision === "object") {
+        return {
+            ...fallback,
+            ...decision,
+            allow: decision.allow !== false,
+        };
+    }
+    return { allow: Boolean(decision), ...fallback };
+}
+function _socketBufferedBytes(ws) {
+    const sock = ws?.socket;
+    if (!sock)
+        return 0;
+    const bytes = sock.writableLength ??
+        sock.bufferSize ??
+        0;
+    return Number.isFinite(bytes) ? bytes : 0;
+}
+export function realtime(options = {}) {
+    const adapter = (options.adapter ?? (options.redisUrl ? "redis" : "memory"));
+    const busChannel = options.busChannel ?? "forge:realtime";
+    const maxPayloadBytes = options.maxPayloadBytes ?? 256 * 1024;
+    const maxConnections = options.maxConnections ?? 10_000;
+    const maxSocketBufferBytes = options.maxSocketBufferBytes ?? 512 * 1024;
+    const backpressureStrategy = options.backpressureStrategy ?? "drop";
+    const redisSubHealthcheckMs = options.redisSubHealthcheckMs ?? 2000;
+    const strictBusPublish = options.strictBusPublish ?? false;
+    const authorize = options.authorize;
+    const authorizeUpgrade = options.authorizeUpgrade;
+    const authorizeConnect = options.authorizeConnect;
+    const allowedChannels = options.allowedChannels ? new Set(options.allowedChannels) : null;
+    return {
+        name: "realtime",
+        version: "1.0.0",
+        inject: "realtime",
+        validate() {
+            if (!["memory", "redis"].includes(adapter)) {
+                throw new Error(`Realtime adapter must be "memory" or "redis", got "${adapter}"`);
+            }
+            if (!REALTIME_CHANNEL_RE.test(busChannel)) {
+                throw new Error(`Invalid realtime busChannel "${busChannel}"`);
+            }
+            if (!Number.isInteger(maxPayloadBytes) || maxPayloadBytes <= 0) {
+                throw new Error(`Realtime maxPayloadBytes must be a positive integer, got ${maxPayloadBytes}`);
+            }
+            if (!Number.isInteger(maxConnections) || maxConnections <= 0) {
+                throw new Error(`Realtime maxConnections must be a positive integer, got ${maxConnections}`);
+            }
+            if (!Number.isInteger(maxSocketBufferBytes) || maxSocketBufferBytes <= 0) {
+                throw new Error(`Realtime maxSocketBufferBytes must be a positive integer, got ${maxSocketBufferBytes}`);
+            }
+            if (!REALTIME_BACKPRESSURE_STRATEGIES.has(backpressureStrategy)) {
+                throw new Error(`Realtime backpressureStrategy must be "drop" or "close", got "${backpressureStrategy}"`);
+            }
+            if (!Number.isInteger(redisSubHealthcheckMs) || redisSubHealthcheckMs <= 0) {
+                throw new Error(`Realtime redisSubHealthcheckMs must be a positive integer, got ${redisSubHealthcheckMs}`);
+            }
+            if (authorize !== undefined && typeof authorize !== "function") {
+                throw new Error(`Realtime authorize must be a function`);
+            }
+            if (authorizeUpgrade !== undefined && typeof authorizeUpgrade !== "function") {
+                throw new Error(`Realtime authorizeUpgrade must be a function`);
+            }
+            if (authorizeConnect !== undefined && typeof authorizeConnect !== "function") {
+                throw new Error(`Realtime authorizeConnect must be a function`);
+            }
+            if (allowedChannels) {
+                for (const ch of allowedChannels)
+                    _assertRealtimeChannel(ch, null);
+            }
+            if (adapter === "redis") {
+                const url = options.redisUrl ?? process.env.FORGE_REALTIME_REDIS_URL ?? process.env.FORGE_REDIS_URL;
+                if (!url) {
+                    throw new Error('Realtime adapter "redis" requires redisUrl or FORGE_REALTIME_REDIS_URL/FORGE_REDIS_URL');
+                }
+            }
+        },
+        env() {
+            if (adapter !== "redis")
+                return {};
+            const url = options.redisUrl ?? process.env.FORGE_REALTIME_REDIS_URL ?? process.env.FORGE_REDIS_URL;
+            if (!url)
+                return {};
+            // HIGH-6: Sanitize URL before propagating to env — strip credentials
+            // to prevent exposure via /proc/<pid>/environ. The connect() function
+            // uses the original url from closure/env at runtime.
+            try {
+                const parsed = new URL(url);
+                parsed.username = "";
+                parsed.password = "";
+                return { FORGE_REALTIME_REDIS_URL: parsed.toString() };
+            }
+            catch {
+                return { FORGE_REALTIME_REDIS_URL: url };
+            }
+        },
+        async connect(ctx) {
+            const connections = new Set();
+            const socketsByChannel = new Map(); // channel -> Set<ws>
+            const channelsBySocket = new Map(); // ws -> Set<channel>
+            const socketMeta = new WeakMap(); // ws -> { req, meta }
+            const senderId = `${ctx.serviceName}:${ctx.workerId}:${process.pid}`;
+            const metrics = {
+                published: 0,
+                delivered: 0,
+                dropped: 0,
+                backpressureDropped: 0,
+                busPublishErrors: 0,
+                redisReconnects: 0,
+            };
+            // redisPub/redisSub can be either our built-in RedisClient or an ioredis instance
+            let redisPub = null;
+            let redisSub = null;
+            let usingIoRedis = false;
+            let builtInSubWatchdog = null;
+            let builtInSubProbeRunning = false;
+            let lastBackpressureLogAt = 0;
+            const shouldLogBackpressure = () => {
+                const now = Date.now();
+                if (now - lastBackpressureLogAt < 30_000)
+                    return false;
+                lastBackpressureLogAt = now;
+                return true;
+            };
+            const runAuthorizeHook = async (stage, payload) => {
+                const defaultDenied = stage === "upgrade"
+                    ? { statusCode: 403, reason: "Forbidden" }
+                    : { closeCode: 1008, closeReason: "Policy violation" };
+                const stageHook = stage === "upgrade" ? authorizeUpgrade : stage === "connect" ? authorizeConnect : undefined;
+                if (typeof stageHook === "function") {
+                    const result = await stageHook({ stage, ...payload });
+                    return _normalizeRealtimeDecision(result, defaultDenied);
+                }
+                if (typeof authorize === "function") {
+                    const result = await authorize({ stage, ...payload });
+                    return _normalizeRealtimeDecision(result, defaultDenied);
+                }
+                return { allow: true };
+            };
+            const ensureSocketTracked = (ws, req = null, meta = null) => {
+                if (!connections.has(ws)) {
+                    connections.add(ws);
+                    channelsBySocket.set(ws, new Set());
+                }
+                const prev = socketMeta.get(ws) ?? { req: null, meta: null };
+                socketMeta.set(ws, {
+                    req: req ?? prev.req ?? null,
+                    meta: meta ?? prev.meta ?? null,
+                });
+            };
+            const cleanupSocket = (ws) => {
+                const socketChannels = channelsBySocket.get(ws);
+                if (socketChannels) {
+                    for (const channel of socketChannels) {
+                        const members = socketsByChannel.get(channel);
+                        if (members) {
+                            members.delete(ws);
+                            if (members.size === 0)
+                                socketsByChannel.delete(channel);
+                        }
+                    }
+                }
+                channelsBySocket.delete(ws);
+                connections.delete(ws);
+                socketMeta.delete(ws);
+            };
+            const handleBackpressure = (ws, channel) => {
+                metrics.backpressureDropped++;
+                metrics.dropped++;
+                if (backpressureStrategy === "close") {
+                    try {
+                        ws.close?.(1013, "Backpressure");
+                    }
+                    catch { }
+                    cleanupSocket(ws);
+                }
+                if (shouldLogBackpressure()) {
+                    ctx.logger.warn("Realtime dropping message due to socket backpressure", {
+                        channel,
+                        strategy: backpressureStrategy,
+                        maxSocketBufferBytes,
+                    });
+                }
+            };
+            const deliverEnvelope = (envelope, { excludeWs = null } = {}) => {
+                const members = socketsByChannel.get(envelope.channel);
+                if (!members || members.size === 0)
+                    return 0;
+                let delivered = 0;
+                let payload;
+                try {
+                    payload = _decodeRealtimeEnvelope(envelope);
+                }
+                catch (err) {
+                    ctx.logger.warn(`Realtime decode failed`, { error: err.message, channel: envelope.channel });
+                    return 0;
+                }
+                for (const ws of members) {
+                    if (excludeWs && ws === excludeWs)
+                        continue;
+                    if (_socketBufferedBytes(ws) > maxSocketBufferBytes) {
+                        handleBackpressure(ws, envelope.channel);
+                        continue;
+                    }
+                    try {
+                        if (_sendRealtimePayload(ws, payload)) {
+                            delivered++;
+                        }
+                        else {
+                            metrics.dropped++;
+                        }
+                    }
+                    catch {
+                        metrics.dropped++;
+                    }
+                }
+                metrics.delivered += delivered;
+                return delivered;
+            };
+            const handleBusMessage = (raw) => {
+                try {
+                    const envelope = JSON.parse(raw);
+                    if (!envelope || envelope.v !== 1 || typeof envelope.channel !== "string")
+                        return;
+                    if (envelope.senderId === senderId)
+                        return; // already delivered locally
+                    deliverEnvelope(envelope);
+                }
+                catch (err) {
+                    ctx.logger.warn(`Realtime bus message parse failed`, { error: err.message });
+                }
+            };
+            const publishToBus = async (envelope) => {
+                if (adapter !== "redis")
+                    return { ok: true, skipped: true };
+                if (!redisPub)
+                    return { ok: false, skipped: true, error: new Error("Redis publisher unavailable") };
+                try {
+                    await redisPub.publish(busChannel, JSON.stringify(envelope));
+                    return { ok: true };
+                }
+                catch (err) {
+                    metrics.busPublishErrors++;
+                    ctx.logger.warn("Realtime publish to bus failed", { error: err.message, busChannel });
+                    return { ok: false, error: err };
+                }
+            };
+            if (adapter === "redis") {
+                const redisUrl = (options.redisUrl ??
+                    process.env.FORGE_REALTIME_REDIS_URL ??
+                    process.env.FORGE_REDIS_URL);
+                try {
+                    const RedisCtor = (await importModuleDynamically("ioredis")).default;
+                    const retryStrategy = (times) => Math.min(100 * 2 ** Math.min(times, 8), 5000);
+                    const ioPub = new RedisCtor(redisUrl, {
+                        lazyConnect: true,
+                        maxRetriesPerRequest: null,
+                        retryStrategy,
+                    });
+                    const ioSub = new RedisCtor(redisUrl, {
+                        lazyConnect: true,
+                        maxRetriesPerRequest: null,
+                        autoResubscribe: true,
+                        retryStrategy,
+                    });
+                    redisPub = ioPub;
+                    redisSub = ioSub;
+                    await ioPub.connect();
+                    await ioSub.connect();
+                    await ioSub.subscribe(busChannel);
+                    ioSub.on("reconnecting", () => {
+                        metrics.redisReconnects++;
+                    });
+                    ioSub.on("message", (_channel, message) => {
+                        handleBusMessage(message);
+                    });
+                    ioPub.on("error", (err) => {
+                        ctx.logger.warn("Realtime redis publisher error", { error: err.message });
+                    });
+                    ioSub.on("error", (err) => {
+                        ctx.logger.warn("Realtime redis subscriber error", { error: err.message });
+                    });
+                    usingIoRedis = true;
+                    ctx.logger.info("Realtime connected (redis adapter)", { busChannel });
+                }
+                catch {
+                    redisPub = await _mkRedis(redisUrl, ctx);
+                    redisSub = await _mkRedis(redisUrl, ctx);
+                    await redisSub.subscribe(busChannel, (message) => handleBusMessage(message));
+                    // Built-in client doesn't expose reconnect events; monitor sub connection health.
+                    builtInSubWatchdog = setInterval(async () => {
+                        if (builtInSubProbeRunning)
+                            return;
+                        if (!redisSub || redisSub._subConnected !== false)
+                            return;
+                        builtInSubProbeRunning = true;
+                        try {
+                            metrics.redisReconnects++;
+                            await redisSub._ensureSubConnection?.();
+                        }
+                        catch (err) {
+                            ctx.logger.warn("Realtime built-in redis subscriber reconnect failed", {
+                                error: err.message,
+                            });
+                        }
+                        finally {
+                            builtInSubProbeRunning = false;
+                        }
+                    }, redisSubHealthcheckMs);
+                    builtInSubWatchdog.unref?.();
+                    ctx.logger.info("Realtime connected (redis adapter, built-in client)", { busChannel });
+                }
+            }
+            else {
+                ctx.logger.info("Realtime connected (memory adapter)");
+            }
+            const client = {
+                adapter,
+                busChannel,
+                join(ws, channel) {
+                    _assertRealtimeChannel(channel, allowedChannels);
+                    ensureSocketTracked(ws);
+                    const socketChannels = channelsBySocket.get(ws);
+                    socketChannels.add(channel);
+                    if (!socketsByChannel.has(channel))
+                        socketsByChannel.set(channel, new Set());
+                    socketsByChannel.get(channel).add(ws);
+                    return true;
+                },
+                leave(ws, channel) {
+                    const socketChannels = channelsBySocket.get(ws);
+                    if (!socketChannels)
+                        return false;
+                    socketChannels.delete(channel);
+                    const members = socketsByChannel.get(channel);
+                    if (members) {
+                        members.delete(ws);
+                        if (members.size === 0)
+                            socketsByChannel.delete(channel);
+                    }
+                    return true;
+                },
+                async publish(channel, payload, opts = {}) {
+                    _assertRealtimeChannel(channel, allowedChannels);
+                    const envelope = _encodeRealtimeEnvelope(channel, payload, senderId, maxPayloadBytes);
+                    const localDelivered = deliverEnvelope(envelope, { excludeWs: opts.excludeWs ?? null });
+                    metrics.published++;
+                    const busResult = await publishToBus(envelope);
+                    if (!busResult.ok && strictBusPublish) {
+                        throw new Error(`Realtime bus publish failed: ${busResult.error?.message ?? "unknown error"}`);
+                    }
+                    return {
+                        delivered: localDelivered,
+                        busPublished: busResult.ok === true || busResult.skipped === true,
+                    };
+                },
+                async broadcast(payload, opts = {}) {
+                    const envelope = _encodeRealtimeEnvelope("__broadcast__", payload, senderId, maxPayloadBytes);
+                    const decoded = _decodeRealtimeEnvelope(envelope);
+                    let delivered = 0;
+                    for (const ws of connections) {
+                        if (opts.excludeWs && ws === opts.excludeWs)
+                            continue;
+                        if (_socketBufferedBytes(ws) > maxSocketBufferBytes) {
+                            handleBackpressure(ws, "__broadcast__");
+                            continue;
+                        }
+                        try {
+                            if (_sendRealtimePayload(ws, decoded)) {
+                                delivered++;
+                            }
+                            else {
+                                metrics.dropped++;
+                            }
+                        }
+                        catch {
+                            metrics.dropped++;
+                        }
+                    }
+                    metrics.delivered += delivered;
+                    metrics.published++;
+                    const busResult = await publishToBus(envelope);
+                    if (!busResult.ok && strictBusPublish) {
+                        throw new Error(`Realtime bus broadcast failed: ${busResult.error?.message ?? "unknown error"}`);
+                    }
+                    return {
+                        delivered,
+                        busPublished: busResult.ok === true || busResult.skipped === true,
+                    };
+                },
+                attach(ws, attachOptions = {}) {
+                    ensureSocketTracked(ws, attachOptions.req ?? null, attachOptions.meta ?? null);
+                    for (const ch of attachOptions.channels ?? []) {
+                        this.join(ws, ch);
+                    }
+                    return {
+                        join: (channel) => this.join(ws, channel),
+                        leave: (channel) => this.leave(ws, channel),
+                        publish: (channel, payload) => this.publish(channel, payload, { excludeWs: ws }),
+                        detach: () => cleanupSocket(ws),
+                    };
+                },
+                channels() {
+                    return [...socketsByChannel.keys()];
+                },
+                connectionCount() {
+                    return connections.size;
+                },
+                async _onWsUpgrade(hookCtx) {
+                    if (connections.size >= maxConnections) {
+                        return { allow: false, statusCode: 503, reason: "WebSocket capacity reached" };
+                    }
+                    const decision = await runAuthorizeHook("upgrade", hookCtx);
+                    if (!decision.allow) {
+                        return {
+                            allow: false,
+                            statusCode: decision.statusCode ?? 403,
+                            reason: decision.reason ?? "Forbidden",
+                            headers: decision.headers ?? {},
+                        };
+                    }
+                    return { allow: true };
+                },
+                async _onWsConnect(hookCtx) {
+                    const { ws, req, meta } = hookCtx ?? {};
+                    ensureSocketTracked(ws, req ?? null, meta ?? null);
+                    const decision = await runAuthorizeHook("connect", hookCtx);
+                    if (!decision.allow) {
+                        try {
+                            ws?.close?.(decision.closeCode ?? 1008, decision.closeReason ?? "Policy violation");
+                        }
+                        catch { }
+                        cleanupSocket(ws);
+                        return {
+                            allow: false,
+                            closeCode: decision.closeCode ?? 1008,
+                            closeReason: decision.closeReason ?? "Policy violation",
+                        };
+                    }
+                    return { allow: true };
+                },
+                _registerConnection(ws, req = null, meta = null) {
+                    ensureSocketTracked(ws, req, meta);
+                },
+                _cleanupConnection(ws) {
+                    cleanupSocket(ws);
+                },
+                _metrics() {
+                    return {
+                        connections: connections.size,
+                        channels: socketsByChannel.size,
+                        published: metrics.published,
+                        delivered: metrics.delivered,
+                        dropped: metrics.dropped,
+                        backpressureDropped: metrics.backpressureDropped,
+                        busPublishErrors: metrics.busPublishErrors,
+                        redisReconnects: metrics.redisReconnects,
+                    };
+                },
+                async _shutdown() {
+                    for (const ws of connections) {
+                        cleanupSocket(ws);
+                    }
+                    if (builtInSubWatchdog) {
+                        clearInterval(builtInSubWatchdog);
+                        builtInSubWatchdog = null;
+                    }
+                    if (redisSub) {
+                        if (usingIoRedis) {
+                            redisSub.removeAllListeners("message");
+                        }
+                        await redisSub.quit?.();
+                        redisSub = null;
+                    }
+                    if (redisPub) {
+                        await redisPub.quit?.();
+                        redisPub = null;
+                    }
+                },
+            };
+            return client;
+        },
+        async disconnect(client) {
+            await client._shutdown?.();
+        },
+        metrics(client) {
+            return client._metrics?.() ?? {};
+        },
+        onWsUpgrade(client, ctx) {
+            return client._onWsUpgrade?.(ctx);
+        },
+        async onWsConnect(client, ctx) {
+            return client._onWsConnect?.(ctx);
+        },
+        onWsClose(client, ctx) {
+            client._cleanupConnection?.(ctx.ws);
+        },
+    };
+}
+// ─── Cron ──────────────────────────────────────────────────
+/**
+ * Parse a single cron field into a Set of matching values.
+ * Supports: star, star-slash-N, N, N-M, N-M/S, comma-separated lists.
+ * @param {string} field - cron field string
+ * @param {number} min - minimum valid value
+ * @param {number} max - maximum valid value
+ * @returns {Set<number>}
+ */
+function _parseCronField(field, min, max) {
+    const values = new Set();
+    for (const part of field.split(",")) {
+        const trimmed = part.trim();
+        // */N or N-M/S
+        const stepMatch = trimmed.match(/^(\*|(\d+)-(\d+))\/(\d+)$/);
+        if (stepMatch) {
+            const step = parseInt(stepMatch[4], 10);
+            if (step <= 0)
+                throw new Error(`Invalid cron step: ${trimmed}`);
+            let start = min, end = max;
+            if (stepMatch[2] !== undefined) {
+                start = parseInt(stepMatch[2], 10);
+                end = parseInt(stepMatch[3], 10);
+            }
+            for (let i = start; i <= end; i += step)
+                values.add(i);
+            continue;
+        }
+        // *
+        if (trimmed === "*") {
+            for (let i = min; i <= max; i++)
+                values.add(i);
+            continue;
+        }
+        // N-M range
+        const rangeMatch = trimmed.match(/^(\d+)-(\d+)$/);
+        if (rangeMatch) {
+            const s = parseInt(rangeMatch[1], 10);
+            const e = parseInt(rangeMatch[2], 10);
+            for (let i = s; i <= e; i++)
+                values.add(i);
+            continue;
+        }
+        // Single value
+        const num = parseInt(trimmed, 10);
+        if (Number.isNaN(num) || num < min || num > max) {
+            throw new Error(`Invalid cron value "${trimmed}" (valid range: ${min}-${max})`);
+        }
+        values.add(num);
+    }
+    return values;
+}
+/**
+ * Parse a 5-field cron expression and return either:
+ * - { type: 'interval', ms } for simple periodic patterns (e.g. "* /5 * * * *")
+ * - { type: 'complex', minutes, hours, daysOfMonth, months, daysOfWeek } for complex patterns
+ */
+function parseCronExpression(expr) {
+    const parts = expr.trim().split(/\s+/);
+    if (parts.length !== 5) {
+        throw new Error(`Invalid cron expression "${expr}": expected 5 fields, got ${parts.length}`);
+    }
+    const [minF, hourF, domF, monF, dowF] = parts;
+    // Try to detect simple interval patterns for setInterval
+    if (hourF === "*" && domF === "*" && monF === "*" && dowF === "*") {
+        if (minF === "*")
+            return { type: "interval", ms: 60_000 };
+        const stepMatch = minF.match(/^\*\/(\d+)$/);
+        if (stepMatch)
+            return { type: "interval", ms: parseInt(stepMatch[1], 10) * 60_000 };
+    }
+    if (minF === "0" && domF === "*" && monF === "*" && dowF === "*") {
+        if (hourF === "*")
+            return { type: "interval", ms: 3_600_000 };
+        const stepMatch = hourF.match(/^\*\/(\d+)$/);
+        if (stepMatch)
+            return { type: "interval", ms: parseInt(stepMatch[1], 10) * 3_600_000 };
+    }
+    if (minF === "0" && hourF === "0" && monF === "*" && dowF === "*") {
+        if (domF === "*")
+            return { type: "interval", ms: 86_400_000 };
+    }
+    // Complex pattern — parse all fields
+    return {
+        type: "complex",
+        minutes: _parseCronField(minF, 0, 59),
+        hours: _parseCronField(hourF, 0, 23),
+        daysOfMonth: _parseCronField(domF, 1, 31),
+        months: _parseCronField(monF, 1, 12),
+        daysOfWeek: _parseCronField(dowF, 0, 6),
+    };
+}
+/**
+ * Calculate milliseconds until the next matching time for a complex cron schedule.
+ * Scans up to 366 days ahead.
+ */
+function _getDatePartsInTz(date, tz) {
+    const fmt = new Intl.DateTimeFormat("en-US", {
+        timeZone: tz,
+        year: "numeric",
+        month: "numeric",
+        day: "numeric",
+        hour: "numeric",
+        minute: "numeric",
+        weekday: "short",
+        hour12: false,
+    });
+    const parts = fmt.formatToParts(date);
+    const get = (t) => parts.find((p) => p.type === t)?.value ?? "0";
+    const weekdayMap = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+    return {
+        minute: parseInt(get("minute"), 10),
+        hour: parseInt(get("hour"), 10) % 24,
+        day: parseInt(get("day"), 10),
+        month: parseInt(get("month"), 10),
+        weekday: weekdayMap[get("weekday")] ?? 0,
+    };
+}
+function _nextCronTimeout(parsed, timezone = "UTC") {
+    const now = new Date();
+    const check = new Date(now.getTime() + 60_000); // start from next minute
+    check.setSeconds(0, 0);
+    const maxTs = now.getTime() + 366 * 86_400_000;
+    const MS_PER_MIN = 60_000;
+    const MS_PER_HOUR = 3_600_000;
+    const MS_PER_DAY = 86_400_000;
+    while (check.getTime() < maxTs) {
+        const { minute: m, hour: h, day: dom, month: mon, weekday: dow } = _getDatePartsInTz(check, timezone);
+        // Skip entire day if month, day-of-month, or day-of-week don't match
+        if (!parsed.months.has(mon) || !parsed.daysOfMonth.has(dom) || !parsed.daysOfWeek.has(dow)) {
+            check.setTime(check.getTime() + MS_PER_DAY);
+            // Align to start of next day in the timezone by resetting to midnight
+            const p = _getDatePartsInTz(check, timezone);
+            check.setTime(check.getTime() - p.hour * MS_PER_HOUR - p.minute * MS_PER_MIN);
+            continue;
+        }
+        // Skip to next hour if hour doesn't match
+        if (!parsed.hours.has(h)) {
+            check.setTime(check.getTime() + (60 - m) * MS_PER_MIN);
+            continue;
+        }
+        // Check minute
+        if (parsed.minutes.has(m)) {
+            return check.getTime() - now.getTime();
+        }
+        check.setTime(check.getTime() + MS_PER_MIN);
+    }
+    throw new Error("Could not find next cron run time within 366 days");
+}
+export function cron(options = {}) {
+    const leaderOnly = options.leaderOnly !== false;
+    return {
+        name: "cron",
+        version: "1.0.0",
+        inject: "cron",
+        async connect(ctx) {
+            // Leader election: workerId === 0 is the default leader.
+            // The supervisor can explicitly designate a leader via ctx._isCronLeader.
+            const isLeader = ctx.workerId === 0 || ctx._isCronLeader === true;
+            const jobs = new Map();
+            const timers = [];
+            if (leaderOnly && !isLeader && ctx.workerId !== 0) {
+                ctx.logger.info(`Cron: worker ${ctx.workerId} is not the cron leader, cron jobs will not run on this worker`);
+            }
+            return {
+                jobs,
+                schedule(name, expr, fn, options = {}) {
+                    if (leaderOnly && !isLeader)
+                        return;
+                    const parsed = parseCronExpression(expr);
+                    // Run immediately only if explicitly enabled
+                    if (options.immediate === true) {
+                        (async () => {
+                            try {
+                                ctx.logger.info(`Cron: ${name} (initial run)`);
+                                await fn();
+                            }
+                            catch (e) {
+                                ctx.logger.error(`Cron "${name}" initial run failed: ${e.message}`);
+                            }
+                        })();
+                    }
+                    let _running = false;
+                    let _lastSuccess = Date.now();
+                    const runJob = async () => {
+                        const intervalMs = parsed.type === "interval" ? parsed.ms : 60_000;
+                        const timeoutMs = Math.floor(intervalMs * 0.9);
+                        if (_running) {
+                            if (Date.now() - _lastSuccess > intervalMs * 2) {
+                                ctx.logger.warn(`Cron "${name}" appears stuck — no success for ${Math.round((Date.now() - _lastSuccess) / 1000)}s`);
+                            }
+                            return;
+                        }
+                        _running = true;
+                        let timer;
+                        try {
+                            ctx.logger.info(`Cron: ${name}`);
+                            await Promise.race([
+                                Promise.resolve(fn()).then((v) => { clearTimeout(timer); return v; }, (e) => { clearTimeout(timer); throw e; }),
+                                new Promise((_, reject) => {
+                                    timer = setTimeout(() => reject(new Error(`Cron "${name}" timed out after ${timeoutMs}ms`)), timeoutMs);
+                                }),
+                            ]);
+                            _lastSuccess = Date.now();
+                        }
+                        catch (e) {
+                            clearTimeout(timer);
+                            ctx.logger.error(`Cron "${name}" failed: ${e.message}`);
+                        }
+                        finally {
+                            _running = false;
+                        }
+                    };
+                    let t;
+                    if (parsed.type === "interval") {
+                        t = setInterval(runJob, parsed.ms);
+                        jobs.set(name, { expr, timer: t });
+                        timers.push(t);
+                        ctx.logger.info(`Cron: "${name}" every ${parsed.ms / 1000}s`);
+                    }
+                    else {
+                        // Complex pattern: use setTimeout with recalculation
+                        let active = true;
+                        function scheduleNext() {
+                            if (!active)
+                                return;
+                            const delayMs = _nextCronTimeout(parsed, options.timezone ?? "UTC");
+                            t = setTimeout(async () => {
+                                await runJob();
+                                scheduleNext();
+                            }, delayMs);
+                            jobs.set(name, {
+                                expr,
+                                timer: t,
+                                _cancelComplex() {
+                                    active = false;
+                                },
+                            });
+                            // Update the timers array entry
+                            const idx = timers.indexOf(t);
+                            if (idx === -1)
+                                timers.push(t);
+                        }
+                        scheduleNext();
+                        ctx.logger.info(`Cron: "${name}" scheduled (complex expression: ${expr})`);
+                    }
+                },
+                cancel(name) {
+                    const j = jobs.get(name);
+                    if (j) {
+                        clearInterval(j.timer);
+                        clearTimeout(j.timer);
+                        if (j._cancelComplex)
+                            j._cancelComplex();
+                        const idx = timers.indexOf(j.timer);
+                        if (idx !== -1)
+                            timers.splice(idx, 1);
+                        jobs.delete(name);
+                    }
+                },
+                listJobs: () => [...jobs.keys()],
+                _timers: timers,
+            };
+        },
+        async disconnect(c) {
+            c._timers.forEach((t) => {
+                clearInterval(t);
+                clearTimeout(t);
+            });
+            for (const j of c.jobs.values()) {
+                if (j._cancelComplex)
+                    j._cancelComplex();
+            }
+            c._timers.length = 0;
+            c.jobs.clear();
+        },
+    };
+}
+//# sourceMappingURL=index.js.map