@yannelli/zoomies 0.0.0

package/dist/server/reload/atomic-write.js

@@ -0,0 +1,151 @@
+import { open, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { NotFoundError } from '../domain/errors.js';
+/**
+ * Suffix appended to the target path for the temp file inside the atomic
+ * write/rename dance. Kept predictable (not random) — if two writers race
+ * on the same path that is the orchestrator's problem to serialize.
+ */
+const NEW_SUFFIX = '.new';
+/**
+ * Read the current contents and mode of `path`, returning a snapshot we can
+ * later restore. Distinguishes "file did not exist" from "file existed and
+ * was empty" — both are valid prior states with very different rollbacks.
+ */
+async function snapshot(path) {
+    try {
+        const [contents, info] = await Promise.all([readFile(path), stat(path)]);
+        return { existed: true, contents, mode: info.mode };
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return { existed: false };
+        }
+        throw err;
+    }
+}
+/**
+ * `fsync` the directory that contains `path` so the rename we just did is
+ * durable across power loss. POSIX semantics: a successful `rename` is only
+ * guaranteed to survive a crash once the parent directory has been synced.
+ *
+ * On Windows opening a directory for fsync fails — Linux/macOS are the real
+ * targets for this control plane, so we catch and ignore the error rather
+ * than make the utility unusable for local dev on Windows.
+ */
+async function fsyncDir(path) {
+    const dir = dirname(path);
+    try {
+        const handle = await open(dir, 'r');
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        // Best-effort durability. Don't mask the caller's success on Windows.
+    }
+}
+/**
+ * Write `contents` to `${path}.new`, fsync it, then rename it over `path`,
+ * then fsync the parent directory. This is the core atomic-write dance used
+ * for both the initial write and the rollback restore.
+ *
+ * The `.new` file is always in the same directory as the target so that
+ * `rename` is an in-filesystem operation (atomic on POSIX). If a previous
+ * crashed run left a stale `${path}.new`, `writeFile` overwrites it.
+ *
+ * `mode` is forwarded to `writeFile` so we can preserve the prior file's
+ * permissions when restoring on rollback.
+ */
+async function atomicReplace(path, contents, mode) {
+    const tmp = `${path}${NEW_SUFFIX}`;
+    await writeFile(tmp, contents, mode === undefined ? undefined : { mode });
+    const handle = await open(tmp, 'r+');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await rename(tmp, path);
+    await fsyncDir(path);
+}
+/**
+ * Atomically write `contents` to `path`, returning a rollback handle that
+ * can restore the prior state.
+ *
+ * Algorithm:
+ *   1. Snapshot the prior state of `path` (contents + mode, or "didn't
+ *      exist") into memory.
+ *   2. Write `contents` to `${path}.new` in the same directory.
+ *   3. fsync the `.new` file so its data is durable before rename.
+ *   4. `rename(${path}.new, path)` — atomic on POSIX same-filesystem.
+ *   5. fsync the parent directory so the rename itself is durable.
+ *
+ * Rollback (`restore()`):
+ *   - If the prior state was "didn't exist", `unlink(path)`.
+ *   - Otherwise run the same atomic-replace dance with the stashed bytes
+ *     and mode.
+ *   - Idempotent: a second `restore()` call is a no-op.
+ */
+export async function writeAtomic(path, contents) {
+    const prior = await snapshot(path);
+    await atomicReplace(path, contents);
+    let restored = false;
+    return {
+        async restore() {
+            if (restored) {
+                return;
+            }
+            restored = true;
+            if (!prior.existed) {
+                try {
+                    await unlink(path);
+                }
+                catch (err) {
+                    if (err.code === 'ENOENT') {
+                        return;
+                    }
+                    throw err;
+                }
+                await fsyncDir(path);
+                return;
+            }
+            await atomicReplace(path, prior.contents, prior.mode);
+        },
+    };
+}
+/**
+ * Atomically delete `path`, returning a rollback handle that restores the
+ * file byte-exact (including its mode).
+ *
+ * Throws {@link NotFoundError} if the target path does not exist — unlike
+ * `writeAtomic`, delete is meaningless against an absent file and the
+ * orchestrator should treat that as a precondition failure.
+ *
+ * Rollback (`restore()`):
+ *   - Atomically re-creates the file with the stashed contents and mode.
+ *   - Idempotent: a second `restore()` is a no-op.
+ */
+export async function deleteAtomic(path) {
+    const prior = await snapshot(path);
+    if (!prior.existed) {
+        throw new NotFoundError(`cannot delete: file does not exist at ${path}`);
+    }
+    await unlink(path);
+    await fsyncDir(path);
+    let restored = false;
+    return {
+        async restore() {
+            if (restored) {
+                return;
+            }
+            restored = true;
+            await atomicReplace(path, prior.contents, prior.mode);
+        },
+    };
+}
+//# sourceMappingURL=atomic-write.js.map

package/dist/server/reload/atomic-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.js","sourceRoot":"","sources":["../../../src/server/reload/atomic-write.ts"],"names":[],"mappings":"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"}

package/dist/server/reload/health-probe.d.ts

@@ -0,0 +1,62 @@
+/**
+ * HTTP health probe with exponential backoff.
+ *
+ * Used by the reload orchestrator to confirm NGINX is still serving traffic
+ * after a config reload. Failures are returned as a result object rather than
+ * thrown: the orchestrator decides whether a failed probe triggers a
+ * rollback, and we don't want a thrown error to short-circuit cleanup paths.
+ *
+ * The implementation uses native `fetch` (Node 22+) and `AbortSignal.timeout`
+ * so there is no runtime dependency to add.
+ */
+/**
+ * Caller-supplied configuration for {@link probeHealth}.
+ *
+ * The defaults are tuned for a freshly-reloaded NGINX: five attempts with
+ * exponential backoff starting at 200ms gives roughly 6.2 seconds of total
+ * wall-clock budget, which comfortably exceeds the time NGINX needs to
+ * finish reloading worker processes on a healthy host.
+ */
+export interface HealthProbeOptions {
+    /** Target URL — typically `http://127.0.0.1/healthz` or similar. */
+    url: string;
+    /** Maximum number of HTTP attempts. Defaults to 5. */
+    maxAttempts?: number;
+    /**
+     * Base delay (ms) for the exponential backoff between attempts. The actual
+     * delay before attempt `n` (1-indexed) is `baseDelayMs * 2^(n - 1)`.
+     * Defaults to 200ms (so: 200, 400, 800, 1600, 3200 with the default
+     * `maxAttempts`).
+     */
+    baseDelayMs?: number;
+    /** Per-attempt timeout (ms). Defaults to 2000. */
+    timeoutMs?: number;
+    /**
+     * Predicate that decides whether a response is healthy. Defaults to "any
+     * 2xx". The orchestrator can override this for endpoints that return e.g.
+     * 204 on success.
+     */
+    acceptStatus?: (status: number) => boolean;
+}
+/**
+ * Outcome of a probe run. `ok` is the only field the orchestrator needs to
+ * branch on — the other fields exist so failures can be surfaced to
+ * operators with enough context to debug.
+ */
+export interface HealthProbeResult {
+    ok: boolean;
+    attempts: number;
+    lastStatus?: number;
+    lastError?: string;
+}
+/**
+ * Probes an HTTP endpoint until it returns an acceptable status or
+ * `maxAttempts` is exhausted.
+ *
+ * The function never throws — transport errors, aborts, and non-acceptable
+ * statuses are all reported via the returned {@link HealthProbeResult}.
+ * Backoff uses the formula `baseDelayMs * 2^(attempt - 1)` and is skipped
+ * after the final attempt (no point waiting if we're not retrying).
+ */
+export declare function probeHealth(opts: HealthProbeOptions): Promise<HealthProbeResult>;
+//# sourceMappingURL=health-probe.d.ts.map

package/dist/server/reload/health-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-probe.d.ts","sourceRoot":"","sources":["../../../src/server/reload/health-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAoBH;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;CAC5C;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAqBD;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAsDtF"}

package/dist/server/reload/health-probe.js

@@ -0,0 +1,105 @@
+/**
+ * HTTP health probe with exponential backoff.
+ *
+ * Used by the reload orchestrator to confirm NGINX is still serving traffic
+ * after a config reload. Failures are returned as a result object rather than
+ * thrown: the orchestrator decides whether a failed probe triggers a
+ * rollback, and we don't want a thrown error to short-circuit cleanup paths.
+ *
+ * The implementation uses native `fetch` (Node 22+) and `AbortSignal.timeout`
+ * so there is no runtime dependency to add.
+ */
+/** Default `acceptStatus` — any 2xx is treated as a healthy response. */
+function isTwoXx(status) {
+    return status >= 200 && status < 300;
+}
+/**
+ * Sleeps for the given number of milliseconds.
+ *
+ * Wraps `setTimeout` in a Promise so that callers can `await` it. We avoid
+ * pulling in `timers/promises` so the implementation stays trivial and is
+ * easy to control from tests via Vitest's fake timers.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * Extracts a string message from an unknown thrown value. `fetch` and
+ * `AbortSignal` throw a mix of `DOMException`, `TypeError`, and `Error`
+ * subclasses; we normalize so `lastError` is always a useful string.
+ */
+function describeError(err) {
+    if (err instanceof Error) {
+        // `AbortError` / `TimeoutError` thrown by `AbortSignal.timeout` are
+        // DOMException subclasses on some runtimes — their `name` is the
+        // discriminator. Surface both name and message so timeouts are
+        // distinguishable from generic network errors.
+        if (err.name === 'TimeoutError' || err.name === 'AbortError') {
+            return `${err.name}: ${err.message || 'request aborted'}`;
+        }
+        return err.message;
+    }
+    return String(err);
+}
+/**
+ * Probes an HTTP endpoint until it returns an acceptable status or
+ * `maxAttempts` is exhausted.
+ *
+ * The function never throws — transport errors, aborts, and non-acceptable
+ * statuses are all reported via the returned {@link HealthProbeResult}.
+ * Backoff uses the formula `baseDelayMs * 2^(attempt - 1)` and is skipped
+ * after the final attempt (no point waiting if we're not retrying).
+ */
+export async function probeHealth(opts) {
+    const maxAttempts = opts.maxAttempts ?? 5;
+    const baseDelayMs = opts.baseDelayMs ?? 200;
+    const timeoutMs = opts.timeoutMs ?? 2000;
+    const acceptStatus = opts.acceptStatus ?? isTwoXx;
+    let lastStatus;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        // `AbortSignal.timeout` ties the per-attempt deadline to a fresh signal
+        // each iteration so a slow attempt cannot bleed its abort into the next
+        // one. On Node 22 the underlying timer is unref'd, which is the
+        // behaviour we want — a hung probe must not keep the process alive.
+        const signal = AbortSignal.timeout(timeoutMs);
+        try {
+            const response = await fetch(opts.url, { signal });
+            lastStatus = response.status;
+            lastError = undefined;
+            if (acceptStatus(response.status)) {
+                const result = {
+                    ok: true,
+                    attempts: attempt,
+                    lastStatus: response.status,
+                };
+                return result;
+            }
+            // Non-acceptable status falls through to the retry path.
+        }
+        catch (err) {
+            lastError = describeError(err);
+            // Network failures / aborts also fall through to retry.
+        }
+        // Skip backoff after the final attempt — we're about to return failure
+        // either way, so the sleep would just delay the bad news.
+        if (attempt < maxAttempts) {
+            const delay = baseDelayMs * 2 ** (attempt - 1);
+            await sleep(delay);
+        }
+    }
+    const failure = {
+        ok: false,
+        attempts: maxAttempts,
+    };
+    if (lastStatus !== undefined) {
+        failure.lastStatus = lastStatus;
+    }
+    if (lastError !== undefined) {
+        failure.lastError = lastError;
+    }
+    return failure;
+}
+//# sourceMappingURL=health-probe.js.map

package/dist/server/reload/health-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-probe.js","sourceRoot":"","sources":["../../../src/server/reload/health-probe.ts"],"names":[],"mappings":"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"}

package/dist/server/reload/reload.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Reload orchestrator — the single chokepoint that turns a freshly rendered
+ * bundle into a live NGINX configuration.
+ *
+ * The orchestrator is the only place in the codebase allowed to mutate the
+ * managed sites directory or send a signal to NGINX. It is deliberately
+ * dependency-injected: every external side effect (validate, write, delete,
+ * reload, probe, listdir) is exposed via {@link ReloadDeps} so tests can drive
+ * each failure path without touching the real filesystem or nginx binary.
+ *
+ * Flow (each step short-circuits on failure with a labeled {@link ApplyResult}):
+ *
+ *   1. Validate the candidate via `nginx -t` — pure check, no disk writes.
+ *   2. Diff disk against `rendered` to compute the writes + orphan deletes.
+ *   3. Apply writes/deletes, accumulating rollback handles in order.
+ *   4. SIGHUP NGINX. If it refuses, roll back everything and reload again.
+ *   5. Probe the configured health URL. If it fails, roll back + reload again.
+ *   6. Success: discard rollback handles.
+ *
+ * On any step that triggers a rollback we re-run the reload so NGINX matches
+ * the disk we just restored. If that second reload also fails, we log both
+ * stderrs and still return the original failure — operator intervention is
+ * needed anyway, and recursing would hide the real cause.
+ */
+import { type ValidationResult } from '../validator/validate.js';
+import { deleteAtomic as deleteAtomicImpl, writeAtomic as writeAtomicImpl } from './atomic-write.js';
+import { type HealthProbeOptions, type HealthProbeResult } from './health-probe.js';
+/**
+ * Minimal subset of `execa`'s result we care about. We only need to know
+ * whether the call succeeded and what NGINX wrote to stderr so we can surface
+ * it on failure. Keeping the shape narrow lets tests construct fakes without
+ * pretending to be the full execa contract.
+ */
+export interface NginxReloadResult {
+    exitCode: number | null;
+    stderr: string;
+}
+/**
+ * Dependency-injection seam. Production code constructs the defaults inside
+ * {@link applyDesiredState} when `opts.deps` is omitted; tests pass an
+ * exhaustive object so the orchestrator's behaviour is fully observable.
+ *
+ * `listManagedFiles` returns absolute paths of the `*.conf` files currently
+ * sitting in `sitesDir`. The default implementation handles ENOENT (treating
+ * it as an empty directory) so the first run before the operator has created
+ * the directory does not fail.
+ */
+export interface ReloadDeps {
+    validate: (text: string) => Promise<ValidationResult>;
+    reload: (bin: string, args: readonly string[]) => Promise<NginxReloadResult>;
+    probe: (opts: HealthProbeOptions) => Promise<HealthProbeResult>;
+    listManagedFiles: (sitesDir: string) => Promise<string[]>;
+    writeAtomic: typeof writeAtomicImpl;
+    deleteAtomic: typeof deleteAtomicImpl;
+}
+/**
+ * Caller-supplied configuration for {@link applyDesiredState}. The required
+ * fields are the two paths/URLs the orchestrator cannot know on its own;
+ * everything else is either a defaulted knob or a test seam.
+ */
+export interface ApplyDesiredStateOptions {
+    sitesDir: string;
+    healthCheckUrl: string;
+    healthCheckOptions?: Partial<Omit<HealthProbeOptions, 'url'>>;
+    /** Default: `['-s', 'reload']`. */
+    nginxReloadArgs?: readonly string[];
+    /** Test seam — production code never passes this. */
+    deps?: Partial<ReloadDeps>;
+}
+/**
+ * Discriminator for {@link ApplyResult}. Names match the flow steps above so
+ * an operator reading a log line can see exactly where the apply stopped.
+ * `success` is the only positive value.
+ */
+export type ApplyStep = 'validate' | 'write' | 'reload' | 'probe' | 'success';
+/**
+ * Outcome of a single `applyDesiredState` call.
+ *
+ * - On success: `{ ok: true, step: 'success' }`.
+ * - On failure: `{ ok: false, step: <where it stopped>, ... }` with whichever
+ *   contextual fields the failing step produced (e.g. the failed
+ *   {@link ValidationResult} or {@link HealthProbeResult}).
+ *
+ * The orchestrator never throws on operational failures — Route Handlers and
+ * the CLI both need a predictable result object to map onto HTTP statuses /
+ * exit codes. Programmer errors (e.g. a bad rollback) are still propagated.
+ */
+export interface ApplyResult {
+    ok: boolean;
+    step: ApplyStep;
+    message?: string;
+    validation?: ValidationResult;
+    probe?: HealthProbeResult;
+}
+/**
+ * Apply a freshly rendered bundle to the managed sites directory.
+ *
+ * Contract:
+ *   - `rendered` is the output of `renderBundle`: a map from site id to the
+ *     NGINX `server { ... }` snippet for that site. Site ids are presumed
+ *     safe (UUIDs per Phase 1); we do not sanitize them against `..`.
+ *   - `opts.sitesDir` is the absolute path of the directory Zoomies owns.
+ *     Anything `*.conf` in there that is not a current site id is an orphan
+ *     and will be deleted.
+ *   - `opts.healthCheckUrl` is the post-reload smoke test target.
+ *
+ * Behaviour:
+ *   - Pure validation failure -> no disk side effects.
+ *   - Disk-apply failure -> rolled back to the pre-call state, no reload.
+ *   - Reload or probe failure -> rolled back AND a second reload kicks NGINX
+ *     back to the pre-call state. If that second reload also fails the
+ *     result still reports the original step (reload/probe) — operator
+ *     intervention is required either way.
+ *
+ * Returns an {@link ApplyResult}. Never throws on operational failures.
+ */
+export declare function applyDesiredState(rendered: ReadonlyMap<string, string>, opts: ApplyDesiredStateOptions): Promise<ApplyResult>;
+//# sourceMappingURL=reload.d.ts.map

package/dist/server/reload/reload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reload.d.ts","sourceRoot":"","sources":["../../../src/server/reload/reload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAOH,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjF,OAAO,EAEL,YAAY,IAAI,gBAAgB,EAChC,WAAW,IAAI,eAAe,EAC/B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAe,MAAM,mBAAmB,CAAC;AAEjG;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACtD,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC7E,KAAK,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAChE,gBAAgB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1D,WAAW,EAAE,OAAO,eAAe,CAAC;IACpC,YAAY,EAAE,OAAO,gBAAgB,CAAC;CACvC;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC,CAAC;IAC9D,mCAAmC;IACnC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,qDAAqD;IACrD,IAAI,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AA8HD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACrC,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,WAAW,CAAC,CA8EtB"}