@poolzin/pool-bot 2026.2.24 → 2026.2.26

package/dist/infra/restart.js

@@ -1,15 +1,109 @@
 import { spawnSync } from "node:child_process";
 import { resolveGatewayLaunchAgentLabel, resolveGatewaySystemdServiceName, } from "../daemon/constants.js";
+import { createSubsystemLogger } from "../logging/subsystem.js";
 const SPAWN_TIMEOUT_MS = 2000;
 const SIGUSR1_AUTH_GRACE_MS = 5000;
+const DEFAULT_DEFERRAL_POLL_MS = 500;
+const DEFAULT_DEFERRAL_MAX_WAIT_MS = 30_000;
+const RESTART_COOLDOWN_MS = 30_000;
+const restartLog = createSubsystemLogger("restart");
 let sigusr1AuthorizedCount = 0;
 let sigusr1AuthorizedUntil = 0;
 let sigusr1ExternalAllowed = false;
+let preRestartCheck = null;
+let restartCycleToken = 0;
+let emittedRestartToken = 0;
+let consumedRestartToken = 0;
+let lastRestartEmittedAt = 0;
+let pendingRestartTimer = null;
+let pendingRestartDueAt = 0;
+let pendingRestartReason;
+function hasUnconsumedRestartSignal() {
+    return emittedRestartToken > consumedRestartToken;
+}
+function clearPendingScheduledRestart() {
+    if (pendingRestartTimer) {
+        clearTimeout(pendingRestartTimer);
+    }
+    pendingRestartTimer = null;
+    pendingRestartDueAt = 0;
+    pendingRestartReason = undefined;
+}
+function summarizeChangedPaths(paths, maxPaths = 6) {
+    if (!Array.isArray(paths) || paths.length === 0) {
+        return null;
+    }
+    if (paths.length <= maxPaths) {
+        return paths.join(",");
+    }
+    const head = paths.slice(0, maxPaths).join(",");
+    return `${head},+${paths.length - maxPaths} more`;
+}
+function formatRestartAudit(audit) {
+    const actor = typeof audit?.actor === "string" && audit.actor.trim() ? audit.actor.trim() : null;
+    const deviceId = typeof audit?.deviceId === "string" && audit.deviceId.trim() ? audit.deviceId.trim() : null;
+    const clientIp = typeof audit?.clientIp === "string" && audit.clientIp.trim() ? audit.clientIp.trim() : null;
+    const changed = summarizeChangedPaths(audit?.changedPaths);
+    const fields = [];
+    if (actor) {
+        fields.push(`actor=${actor}`);
+    }
+    if (deviceId) {
+        fields.push(`device=${deviceId}`);
+    }
+    if (clientIp) {
+        fields.push(`ip=${clientIp}`);
+    }
+    if (changed) {
+        fields.push(`changedPaths=${changed}`);
+    }
+    return fields.length > 0 ? fields.join(" ") : "actor=<unknown>";
+}
+/**
+ * Register a callback that scheduleGatewaySigusr1Restart checks before emitting SIGUSR1.
+ * The callback should return the number of pending items (0 = safe to restart).
+ */
+export function setPreRestartDeferralCheck(fn) {
+    preRestartCheck = fn;
+}
+/**
+ * Emit an authorized SIGUSR1 gateway restart, guarded against duplicate emissions.
+ * Returns true if SIGUSR1 was emitted, false if a restart was already emitted.
+ * Both scheduleGatewaySigusr1Restart and the config watcher should use this
+ * to ensure only one restart fires.
+ */
+export function emitGatewayRestart() {
+    if (hasUnconsumedRestartSignal()) {
+        clearPendingScheduledRestart();
+        return false;
+    }
+    clearPendingScheduledRestart();
+    const cycleToken = ++restartCycleToken;
+    emittedRestartToken = cycleToken;
+    authorizeGatewaySigusr1Restart();
+    try {
+        if (process.listenerCount("SIGUSR1") > 0) {
+            process.emit("SIGUSR1");
+        }
+        else {
+            process.kill(process.pid, "SIGUSR1");
+        }
+    }
+    catch {
+        // Roll back the cycle marker so future restart requests can still proceed.
+        emittedRestartToken = consumedRestartToken;
+        return false;
+    }
+    lastRestartEmittedAt = Date.now();
+    return true;
+}
 function resetSigusr1AuthorizationIfExpired(now = Date.now()) {
-    if (sigusr1AuthorizedCount <= 0)
+    if (sigusr1AuthorizedCount <= 0) {
         return;
-    if (now <= sigusr1AuthorizedUntil)
+    }
+    if (now <= sigusr1AuthorizedUntil) {
         return;
+    }
     sigusr1AuthorizedCount = 0;
     sigusr1AuthorizedUntil = 0;
 }
@@ -19,7 +113,7 @@ export function setGatewaySigusr1RestartPolicy(opts) {
 export function isGatewaySigusr1RestartExternallyAllowed() {
     return sigusr1ExternalAllowed;
 }
-export function authorizeGatewaySigusr1Restart(delayMs = 0) {
+function authorizeGatewaySigusr1Restart(delayMs = 0) {
     const delay = Math.max(0, Math.floor(delayMs));
     const expiresAt = Date.now() + delay + SIGUSR1_AUTH_GRACE_MS;
     sigusr1AuthorizedCount += 1;
@@ -29,24 +123,87 @@ export function authorizeGatewaySigusr1Restart(delayMs = 0) {
 }
 export function consumeGatewaySigusr1RestartAuthorization() {
     resetSigusr1AuthorizationIfExpired();
-    if (sigusr1AuthorizedCount <= 0)
+    if (sigusr1AuthorizedCount <= 0) {
         return false;
+    }
     sigusr1AuthorizedCount -= 1;
     if (sigusr1AuthorizedCount <= 0) {
         sigusr1AuthorizedUntil = 0;
     }
     return true;
 }
+/**
+ * Mark the currently emitted SIGUSR1 restart cycle as consumed by the run loop.
+ * This explicitly advances the cycle state instead of resetting emit guards inside
+ * consumeGatewaySigusr1RestartAuthorization().
+ */
+export function markGatewaySigusr1RestartHandled() {
+    if (hasUnconsumedRestartSignal()) {
+        consumedRestartToken = emittedRestartToken;
+    }
+}
+/**
+ * Poll pending work until it drains (or times out), then emit one restart signal.
+ * Shared by both the direct RPC restart path and the config watcher path.
+ */
+export function deferGatewayRestartUntilIdle(opts) {
+    const pollMsRaw = opts.pollMs ?? DEFAULT_DEFERRAL_POLL_MS;
+    const pollMs = Math.max(10, Math.floor(pollMsRaw));
+    const maxWaitMsRaw = opts.maxWaitMs ?? DEFAULT_DEFERRAL_MAX_WAIT_MS;
+    const maxWaitMs = Math.max(pollMs, Math.floor(maxWaitMsRaw));
+    let pending;
+    try {
+        pending = opts.getPendingCount();
+    }
+    catch (err) {
+        opts.hooks?.onCheckError?.(err);
+        emitGatewayRestart();
+        return;
+    }
+    if (pending <= 0) {
+        opts.hooks?.onReady?.();
+        emitGatewayRestart();
+        return;
+    }
+    opts.hooks?.onDeferring?.(pending);
+    const startedAt = Date.now();
+    const poll = setInterval(() => {
+        let current;
+        try {
+            current = opts.getPendingCount();
+        }
+        catch (err) {
+            clearInterval(poll);
+            opts.hooks?.onCheckError?.(err);
+            emitGatewayRestart();
+            return;
+        }
+        if (current <= 0) {
+            clearInterval(poll);
+            opts.hooks?.onReady?.();
+            emitGatewayRestart();
+            return;
+        }
+        const elapsedMs = Date.now() - startedAt;
+        if (elapsedMs >= maxWaitMs) {
+            clearInterval(poll);
+            opts.hooks?.onTimeout?.(current, elapsedMs);
+            emitGatewayRestart();
+        }
+    }, pollMs);
+}
 function formatSpawnDetail(result) {
     const clean = (value) => {
         const text = typeof value === "string" ? value : value ? value.toString() : "";
         return text.replace(/\s+/g, " ").trim();
     };
     if (result.error) {
-        if (result.error instanceof Error)
+        if (result.error instanceof Error) {
             return result.error.message;
-        if (typeof result.error === "string")
+        }
+        if (typeof result.error === "string") {
             return result.error;
+        }
         try {
             return JSON.stringify(result.error);
         }
@@ -55,13 +212,16 @@ function formatSpawnDetail(result) {
         }
     }
     const stderr = clean(result.stderr);
-    if (stderr)
+    if (stderr) {
         return stderr;
+    }
     const stdout = clean(result.stdout);
-    if (stdout)
+    if (stdout) {
         return stdout;
-    if (typeof result.status === "number")
+    }
+    if (typeof result.status === "number") {
         return `exit ${result.status}`;
+    }
     return "unknown error";
 }
 function normalizeSystemdUnit(raw, profile) {
@@ -138,29 +298,66 @@ export function scheduleGatewaySigusr1Restart(opts) {
     const reason = typeof opts?.reason === "string" && opts.reason.trim()
         ? opts.reason.trim().slice(0, 200)
         : undefined;
-    authorizeGatewaySigusr1Restart(delayMs);
-    const pid = process.pid;
-    const hasListener = process.listenerCount("SIGUSR1") > 0;
-    setTimeout(() => {
-        try {
-            if (hasListener) {
-                process.emit("SIGUSR1");
-            }
-            else {
-                process.kill(pid, "SIGUSR1");
-            }
+    const mode = process.listenerCount("SIGUSR1") > 0 ? "emit" : "signal";
+    const nowMs = Date.now();
+    const cooldownMsApplied = Math.max(0, lastRestartEmittedAt + RESTART_COOLDOWN_MS - nowMs);
+    const requestedDueAt = nowMs + delayMs + cooldownMsApplied;
+    if (hasUnconsumedRestartSignal()) {
+        restartLog.warn(`restart request coalesced (already in-flight) reason=${reason ?? "unspecified"} ${formatRestartAudit(opts?.audit)}`);
+        return {
+            ok: true,
+            pid: process.pid,
+            signal: "SIGUSR1",
+            delayMs: 0,
+            reason,
+            mode,
+            coalesced: true,
+            cooldownMsApplied,
+        };
+    }
+    if (pendingRestartTimer) {
+        const remainingMs = Math.max(0, pendingRestartDueAt - nowMs);
+        const shouldPullEarlier = requestedDueAt < pendingRestartDueAt;
+        if (shouldPullEarlier) {
+            restartLog.warn(`restart request rescheduled earlier reason=${reason ?? "unspecified"} pendingReason=${pendingRestartReason ?? "unspecified"} oldDelayMs=${remainingMs} newDelayMs=${Math.max(0, requestedDueAt - nowMs)} ${formatRestartAudit(opts?.audit)}`);
+            clearPendingScheduledRestart();
         }
-        catch {
-            /* ignore */
+        else {
+            restartLog.warn(`restart request coalesced (already scheduled) reason=${reason ?? "unspecified"} pendingReason=${pendingRestartReason ?? "unspecified"} delayMs=${remainingMs} ${formatRestartAudit(opts?.audit)}`);
+            return {
+                ok: true,
+                pid: process.pid,
+                signal: "SIGUSR1",
+                delayMs: remainingMs,
+                reason,
+                mode,
+                coalesced: true,
+                cooldownMsApplied,
+            };
+        }
+    }
+    pendingRestartDueAt = requestedDueAt;
+    pendingRestartReason = reason;
+    pendingRestartTimer = setTimeout(() => {
+        pendingRestartTimer = null;
+        pendingRestartDueAt = 0;
+        pendingRestartReason = undefined;
+        const pendingCheck = preRestartCheck;
+        if (!pendingCheck) {
+            emitGatewayRestart();
+            return;
         }
-    }, delayMs);
+        deferGatewayRestartUntilIdle({ getPendingCount: pendingCheck });
+    }, Math.max(0, requestedDueAt - nowMs));
     return {
         ok: true,
-        pid,
+        pid: process.pid,
         signal: "SIGUSR1",
-        delayMs,
+        delayMs: Math.max(0, requestedDueAt - nowMs),
         reason,
-        mode: hasListener ? "emit" : "signal",
+        mode,
+        coalesced: false,
+        cooldownMsApplied,
     };
 }
 export const __testing = {
@@ -168,5 +365,11 @@ export const __testing = {
         sigusr1AuthorizedCount = 0;
         sigusr1AuthorizedUntil = 0;
         sigusr1ExternalAllowed = false;
+        preRestartCheck = null;
+        restartCycleToken = 0;
+        emittedRestartToken = 0;
+        consumedRestartToken = 0;
+        lastRestartEmittedAt = 0;
+        clearPendingScheduledRestart();
     },
 };

package/dist/infra/retry-policy.js

@@ -1,4 +1,5 @@
 import { RateLimitError } from "@buape/carbon";
+import { createSubsystemLogger } from "../logging/subsystem.js";
 import { formatErrorMessage } from "./errors.js";
 import { resolveRetryConfig, retryAsync } from "./retry.js";
 export const DISCORD_RETRY_DEFAULTS = {
@@ -13,6 +14,7 @@ export const TELEGRAM_RETRY_DEFAULTS = {
     maxDelayMs: 30_000,
     jitter: 0.1,
 };
+const log = createSubsystemLogger("retry-policy");
 const TELEGRAM_RETRY_RE = /429|timeout|connect|reset|closed|unavailable|temporarily/i;
 function getTelegramRetryAfterMs(err) {
     if (!err || typeof err !== "object")
@@ -43,7 +45,7 @@ export function createDiscordRetryRunner(params) {
             ? (info) => {
                 const labelText = info.label ?? "request";
                 const maxRetries = Math.max(1, info.maxAttempts - 1);
-                console.warn(`discord ${labelText} rate limited, retry ${info.attempt}/${maxRetries} in ${info.delayMs}ms`);
+                log.warn(`discord ${labelText} rate limited, retry ${info.attempt}/${maxRetries} in ${info.delayMs}ms`);
             }
             : undefined,
     });
@@ -64,7 +66,7 @@ export function createTelegramRetryRunner(params) {
         onRetry: params.verbose
             ? (info) => {
                 const maxRetries = Math.max(1, info.maxAttempts - 1);
-                console.warn(`telegram send retry ${info.attempt}/${maxRetries} for ${info.label ?? label ?? "request"} in ${info.delayMs}ms: ${formatErrorMessage(info.err)}`);
+                log.warn(`telegram send retry ${info.attempt}/${maxRetries} for ${info.label ?? label ?? "request"} in ${info.delayMs}ms: ${formatErrorMessage(info.err)}`);
             }
             : undefined,
     });

package/dist/infra/retry.js

@@ -1,15 +1,16 @@
+import { sleep } from "../utils.js";
 const DEFAULT_RETRY_CONFIG = {
     attempts: 3,
     minDelayMs: 300,
     maxDelayMs: 30_000,
     jitter: 0,
 };
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 const asFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
 const clampNumber = (value, fallback, min, max) => {
     const next = asFiniteNumber(value);
-    if (next === undefined)
+    if (next === undefined) {
         return fallback;
+    }
     const floor = typeof min === "number" ? min : Number.NEGATIVE_INFINITY;
     const ceiling = typeof max === "number" ? max : Number.POSITIVE_INFINITY;
     return Math.min(Math.max(next, floor), ceiling);
@@ -22,8 +23,9 @@ export function resolveRetryConfig(defaults = DEFAULT_RETRY_CONFIG, overrides) {
     return { attempts, minDelayMs, maxDelayMs, jitter };
 }
 function applyJitter(delayMs, jitter) {
-    if (jitter <= 0)
+    if (jitter <= 0) {
         return delayMs;
+    }
     const offset = (Math.random() * 2 - 1) * jitter;
     return Math.max(0, Math.round(delayMs * (1 + offset)));
 }
@@ -37,8 +39,9 @@ export async function retryAsync(fn, attemptsOrOptions = 3, initialDelayMs = 300
             }
             catch (err) {
                 lastErr = err;
-                if (i === attempts - 1)
+                if (i === attempts - 1) {
                     break;
+                }
                 const delay = initialDelayMs * 2 ** i;
                 await sleep(delay);
             }
@@ -61,8 +64,9 @@ export async function retryAsync(fn, attemptsOrOptions = 3, initialDelayMs = 300
         }
         catch (err) {
             lastErr = err;
-            if (attempt >= maxAttempts || !shouldRetry(err, attempt))
+            if (attempt >= maxAttempts || !shouldRetry(err, attempt)) {
                 break;
+            }
             const retryAfterMs = options.retryAfterMs?.(err);
             const hasRetryAfter = typeof retryAfterMs === "number" && Number.isFinite(retryAfterMs);
             const baseDelay = hasRetryAfter

package/dist/infra/scp-host.js

@@ -0,0 +1,54 @@
+const SSH_TOKEN = /^[A-Za-z0-9._-]+$/;
+const BRACKETED_IPV6 = /^\[[0-9A-Fa-f:.%]+\]$/;
+const WHITESPACE = /\s/;
+function hasControlOrWhitespace(value) {
+    for (const char of value) {
+        const code = char.charCodeAt(0);
+        if (code <= 0x1f || code === 0x7f || WHITESPACE.test(char)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function normalizeScpRemoteHost(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    if (hasControlOrWhitespace(trimmed)) {
+        return undefined;
+    }
+    if (trimmed.startsWith("-") || trimmed.includes("/") || trimmed.includes("\\")) {
+        return undefined;
+    }
+    const firstAt = trimmed.indexOf("@");
+    const lastAt = trimmed.lastIndexOf("@");
+    let user;
+    let host = trimmed;
+    if (firstAt !== -1) {
+        if (firstAt !== lastAt || firstAt === 0 || firstAt === trimmed.length - 1) {
+            return undefined;
+        }
+        user = trimmed.slice(0, firstAt);
+        host = trimmed.slice(firstAt + 1);
+        if (!SSH_TOKEN.test(user)) {
+            return undefined;
+        }
+    }
+    if (!host || host.startsWith("-") || host.includes("@")) {
+        return undefined;
+    }
+    if (host.includes(":") && !BRACKETED_IPV6.test(host)) {
+        return undefined;
+    }
+    if (!SSH_TOKEN.test(host) && !BRACKETED_IPV6.test(host)) {
+        return undefined;
+    }
+    return user ? `${user}@${host}` : host;
+}
+export function isSafeScpRemoteHost(value) {
+    return normalizeScpRemoteHost(value) !== undefined;
+}