gcb-host 0.0.3 → 0.2.0

package/lib/reload.d.ts

@@ -0,0 +1,45 @@
+/** What one file read looked like. */
+export interface ConfigFingerprint {
+    readonly digest: string;
+}
+/**
+ * Read the file and hash it.
+ *
+ * @param file - the configuration path.
+ * @returns the digest, or undefined when the file is momentarily absent (an atomic rename).
+ */
+export declare function fingerprintConfig(file: string): ConfigFingerprint | undefined;
+/** Options for {@link ConfigWatcher}. */
+export interface ConfigWatcherOptions {
+    readonly file: string;
+    /** Safety poll interval, used alongside the watch and as the fallback when it is unavailable. */
+    readonly intervalMs?: number;
+    /** How long to coalesce a burst of events. */
+    readonly debounceMs?: number;
+    /** Reload the file; throws when invalid. Returns the digest of the bytes it loaded. */
+    readonly reload: () => string;
+    /** Digest already loaded at start-up; avoids a race between load and watcher construction. */
+    readonly initialDigest?: string;
+    /** Report a failed reload; the last good snapshot stays active. */
+    readonly onError?: (error: Error) => void;
+}
+/** Poll and watch one configuration file. */
+export declare class ConfigWatcher {
+    #private;
+    constructor(options: ConfigWatcherOptions);
+    /**
+     * Start watching. A failure to establish the fast path is not fatal: polling still runs.
+     *
+     * @returns this watcher, for chaining.
+     */
+    start(): this;
+    /**
+     * Compare the file with the last accepted digest and reload when it changed.
+     *
+     * @param force - reload even when the digest is unchanged (SIGHUP).
+     */
+    check(force: boolean): void;
+    /** Stop both triggers. */
+    stop(): void;
+}
+//# sourceMappingURL=reload.d.ts.map

package/lib/reload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reload.d.ts","sourceRoot":"","sources":["../src/reload.ts"],"names":[],"mappings":"AAWA,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAS7E;AAED,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iGAAiG;IACjG,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,uFAAuF;IACvF,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;IAC9B,8FAA8F;IAC9F,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAC3C;AAED,6CAA6C;AAC7C,qBAAa,aAAa;;IAkBxB,YAAY,OAAO,EAAE,oBAAoB,EAYxC;IAED;;;;OAIG;IACH,KAAK,IAAI,IAAI,CAiBZ;IASD;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAiC1B;IAED,0BAA0B;IAC1B,IAAI,IAAI,IAAI,CAKX;CACF"}

package/lib/reload.js

@@ -0,0 +1,149 @@
+/**
+ * Watch the configuration file for a change, with a poll as the safety net.
+ *
+ * `fs.watch` is the low-latency trigger. Events can be missed (network filesystems and bind mounts
+ * have been observed dropping them), so a 5-second digest poll runs alongside it; a digest that has
+ * not changed costs one read and no reload.
+ */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Read the file and hash it.
+ *
+ * @param file - the configuration path.
+ * @returns the digest, or undefined when the file is momentarily absent (an atomic rename).
+ */
+export function fingerprintConfig(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    return { digest: createHash('sha256').update(text).digest('hex') };
+}
+/** Poll and watch one configuration file. */
+export class ConfigWatcher {
+    #file;
+    #intervalMs;
+    #debounceMs;
+    #reload;
+    #onError;
+    #last;
+    /** A SIGHUP arrived while the file was absent; honour it when the file returns. */
+    #forcePending = false;
+    /** The (digest, reason) already reported, so a deterministic failure is not logged every tick. */
+    #failedReport;
+    /** The read error already reported, so a permanently unreadable file is not logged every tick. */
+    #readError;
+    #timer;
+    #watch;
+    #debounce;
+    #stopped = false;
+    constructor(options) {
+        this.#file = options.file;
+        this.#intervalMs = options.intervalMs ?? 5_000;
+        this.#debounceMs = options.debounceMs ?? 300;
+        this.#reload = options.reload;
+        this.#onError = options.onError ?? (() => { });
+        try {
+            this.#last = options.initialDigest ?? fingerprintConfig(this.#file)?.digest;
+        }
+        catch {
+            // An unreadable file at start-up is reported by the first check, not thrown from the constructor.
+            this.#last = options.initialDigest;
+        }
+    }
+    /**
+     * Start watching. A failure to establish the fast path is not fatal: polling still runs.
+     *
+     * @returns this watcher, for chaining.
+     */
+    start() {
+        this.#startPolling();
+        try {
+            this.#watch = fs.watch(path.dirname(this.#file), { persistent: false }, (_event, name) => {
+                if (name !== null && name !== path.basename(this.#file))
+                    return;
+                if (this.#debounce !== undefined)
+                    clearTimeout(this.#debounce);
+                this.#debounce = setTimeout(() => this.check(false), this.#debounceMs);
+                this.#debounce.unref();
+            });
+            this.#watch.on('error', () => {
+                this.#watch?.close();
+                this.#watch = undefined;
+            });
+        }
+        catch {
+            // The safety poll is already running; an unavailable watch must not stop the daemon.
+        }
+        return this;
+    }
+    /** Start the safety poll once; the watch is the primary, low-latency trigger. */
+    #startPolling() {
+        if (this.#stopped || this.#timer !== undefined)
+            return;
+        this.#timer = setInterval(() => this.check(false), this.#intervalMs);
+        this.#timer.unref();
+    }
+    /**
+     * Compare the file with the last accepted digest and reload when it changed.
+     *
+     * @param force - reload even when the digest is unchanged (SIGHUP).
+     */
+    check(force) {
+        if (this.#stopped)
+            return;
+        if (force)
+            this.#forcePending = true;
+        let next;
+        try {
+            next = fingerprintConfig(this.#file);
+        }
+        catch (error) {
+            const message = error.message;
+            if (message !== this.#readError) {
+                this.#readError = message;
+                this.#onError(error);
+            }
+            return;
+        }
+        this.#readError = undefined;
+        if (next === undefined)
+            return;
+        if (!this.#forcePending && next.digest === this.#last)
+            return;
+        try {
+            this.#last = this.#reload();
+            this.#failedReport = undefined;
+            this.#forcePending = false;
+        }
+        catch (error) {
+            // Keep the last good snapshot. Clearing the digest retries the same bytes on the next tick, for
+            // a transient cause; report only once per distinct bad content so a typo does not flood the
+            // audit log and the container log every five seconds.
+            this.#last = undefined;
+            this.#forcePending = false;
+            const report = `${next.digest}\0${error.message}`;
+            if (report !== this.#failedReport) {
+                this.#failedReport = report;
+                this.#onError(error);
+            }
+        }
+    }
+    /** Stop both triggers. */
+    stop() {
+        this.#stopped = true;
+        if (this.#timer !== undefined)
+            clearInterval(this.#timer);
+        if (this.#debounce !== undefined)
+            clearTimeout(this.#debounce);
+        this.#watch?.close();
+    }
+}
+//# sourceMappingURL=reload.js.map

package/lib/reload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reload.js","sourceRoot":"","sources":["../src/reload.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAO7B;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACzE,MAAM,KAAK,CAAC;IACd,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AACrE,CAAC;AAiBD,6CAA6C;AAC7C,MAAM,OAAO,aAAa;IACf,KAAK,CAAS;IACd,WAAW,CAAS;IACpB,WAAW,CAAS;IACpB,OAAO,CAAe;IACtB,QAAQ,CAAyB;IAC1C,KAAK,CAAqB;IAC1B,mFAAmF;IACnF,aAAa,GAAG,KAAK,CAAC;IACtB,kGAAkG;IAClG,aAAa,CAAqB;IAClC,kGAAkG;IAClG,UAAU,CAAqB;IAC/B,MAAM,CAA6B;IACnC,MAAM,CAA2B;IACjC,SAAS,CAA6B;IACtC,QAAQ,GAAG,KAAK,CAAC;IAEjB,YAAY,OAA6B;QACvC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;QAC1B,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,UAAU,IAAI,KAAK,CAAC;QAC/C,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,UAAU,IAAI,GAAG,CAAC;QAC7C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC9C,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,aAAa,IAAI,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAC9E,CAAC;QAAC,MAAM,CAAC;YACP,kGAAkG;YAClG,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,aAAa,CAAC;QACrC,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,IAAI,CAAC,aAAa,EAAE,CAAC;QACrB,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE;gBACvF,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;oBAAE,OAAO;gBAChE,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;oBAAE,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBAC/D,IAAI,CAAC,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;gBACvE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;YACzB,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;gBAC3B,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;gBACrB,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;YAC1B,CAAC,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,qFAAqF;QACvF,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,iFAAiF;IACjF,aAAa;QACX,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO;QACvD,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QACrE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAc;QAClB,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,KAAK;YAAE,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QACrC,IAAI,IAAmC,CAAC;QACxC,IAAI,CAAC;YACH,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAI,KAAe,CAAC,OAAO,CAAC;YACzC,IAAI,OAAO,KAAK,IAAI,CAAC,UAAU,EAAE,CAAC;gBAChC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC;gBAC1B,IAAI,CAAC,QAAQ,CAAC,KAAc,CAAC,CAAC;YAChC,CAAC;YACD,OAAO;QACT,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO;QAC/B,IAAI,CAAC,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,KAAK;YAAE,OAAO;QAC9D,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;YAC5B,IAAI,CAAC,aAAa,GAAG,SAAS,CAAC;YAC/B,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;QAC7B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,gGAAgG;YAChG,4FAA4F;YAC5F,sDAAsD;YACtD,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;YACvB,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;YAC3B,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC;YAC7D,IAAI,MAAM,KAAK,IAAI,CAAC,aAAa,EAAE,CAAC;gBAClC,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC;gBAC5B,IAAI,CAAC,QAAQ,CAAC,KAAc,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;IACH,CAAC;IAED,0BAA0B;IAC1B,IAAI;QACF,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1D,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;YAAE,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC/D,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;IACvB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcb-host",
-  "version": "0.0.3",
+  "version": "0.2.0",
   "description": "Host-side gcb broker, configuration, providers and administration commands.",
   "license": "MIT",
   "author": "JounQin <admin@1stg.me>",
@@ -27,7 +27,7 @@
     }
   },
   "dependencies": {
-    "gcb-core": "0.0.3",
+    "gcb-core": "0.2.0",
     "node-fetch-native": "^1.6.7",
     "x-fetch": "^0.3.0",
     "yaml": "^2.9.1"