@arki/dot 0.1.4 → 0.3.0

package/src/signals.ts

@@ -0,0 +1,134 @@
+/**
+ * Signal wiring for graceful shutdown.
+ *
+ * `hookSignals(app)` connects OS termination signals to the app's
+ * lifecycle: on the first SIGTERM/SIGINT the app is disposed (which
+ * cascades `stop()` when started — transitions are serialized, so a
+ * signal racing a slow `start()` still ends in `disposed`), then the
+ * signal is re-raised with the default handler restored so the process
+ * terminates with conventional signal semantics.
+ *
+ * Design points:
+ *
+ *  - **First signal drains, second signal kills.** All handlers are
+ *    removed the moment the first signal fires, so an impatient second
+ *    Ctrl-C hits the runtime default (immediate termination) instead of
+ *    a stuck drain.
+ *  - **Bounded.** `timeoutMs` caps the drain. On timeout or dispose
+ *    failure the process still terminates — exit code reflects the
+ *    failure via the re-raised signal; the error is logged on
+ *    `arki:dot:signals`.
+ *  - **No `process.exit()`.** The signal is re-raised via
+ *    `proc.kill(proc.pid, signal)` so the exit status is the standard
+ *    128+n signal encoding — supervisors (systemd, Docker, Coolify)
+ *    read it correctly.
+ */
+
+import { Logger } from '@arki/log';
+
+/**
+ * The slice of `process` the signal hook touches. Injectable so tests can
+ * drive signals through a fake without terminating the test runner —
+ * defaults to the real `process`.
+ */
+export type SignalTarget = {
+  readonly pid: number;
+  once(event: string, listener: (...args: never[]) => void): unknown;
+  off(event: string, listener: (...args: never[]) => void): unknown;
+  kill(pid: number, signal?: string): unknown;
+};
+
+export type HookSignalsOptions = {
+  /** Signals to intercept. Default: `['SIGTERM', 'SIGINT']`. */
+  readonly signals?: readonly string[];
+  /**
+   * Maximum time the drain (`dispose()`) may take before the process is
+   * terminated anyway. Default: 10 000 ms.
+   */
+  readonly timeoutMs?: number;
+  /** Test seam — a process-like target. Default: the real `process`. */
+  readonly proc?: SignalTarget;
+};
+
+/** The app surface the hook needs — satisfied by any `DotApp`. */
+export type Disposable = {
+  readonly name: string;
+  dispose(): Promise<void>;
+};
+
+/**
+ * Wire termination signals to `app.dispose()`. Returns an unhook function
+ * that removes the handlers without disposing — call it if the app is
+ * torn down through another path first.
+ *
+ * ```ts
+ * const app = await defineApp('shop').use(...).start();
+ * hookSignals(app);                          // SIGTERM/SIGINT → drain → exit
+ * hookSignals(app, { timeoutMs: 30_000 });   // slower drain budget
+ * ```
+ */
+export function hookSignals(app: Disposable, options: HookSignalsOptions = {}): () => void {
+  const signals = options.signals ?? ['SIGTERM', 'SIGINT'];
+  const timeoutMs = options.timeoutMs ?? 10_000;
+  const proc: SignalTarget = options.proc ?? (process as unknown as SignalTarget);
+  const logger = new Logger('arki:dot:signals', { 'dot.app.name': app.name });
+
+  const handlers = new Map<string, () => void>();
+
+  const unhook = (): void => {
+    for (const [signal, handler] of handlers) proc.off(signal, handler);
+    handlers.clear();
+  };
+
+  for (const signal of signals) {
+    const handler = (): void => {
+      // First signal wins; the rest fall through to runtime defaults.
+      unhook();
+      logger.info('signal received — draining', { 'dot.signal': signal, 'dot.drain.timeout.ms': timeoutMs });
+      void drainAndReraise({ app, signal, timeoutMs, proc, logger });
+    };
+    handlers.set(signal, handler);
+    proc.once(signal, handler);
+  }
+
+  return unhook;
+}
+
+/** Dispose with a timeout cap, then re-raise the signal for default handling. */
+async function drainAndReraise(args: {
+  app: Disposable;
+  signal: string;
+  timeoutMs: number;
+  proc: SignalTarget;
+  logger: Logger;
+}): Promise<void> {
+  const { app, signal, timeoutMs, proc, logger } = args;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<'timeout'>(resolve => {
+    timer = setTimeout(() => {
+      resolve('timeout');
+    }, timeoutMs);
+    // A pending drain timer must never keep an otherwise-finished process alive.
+    if (typeof timer === 'object' && 'unref' in timer) timer.unref();
+  });
+
+  try {
+    const outcome = await Promise.race([app.dispose().then(() => 'disposed' as const), timedOut]);
+    if (outcome === 'timeout') {
+      logger.error('drain timed out — terminating without a clean dispose', {
+        'dot.signal': signal,
+        'dot.drain.timeout.ms': timeoutMs,
+      });
+    } else {
+      logger.info('drain complete', { 'dot.signal': signal });
+    }
+  } catch (error) {
+    logger.error('dispose failed during drain — terminating', {
+      'dot.signal': signal,
+      'dot.error.message': error instanceof Error ? error.message : String(error),
+    });
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    proc.kill(proc.pid, signal);
+  }
+}

package/src/test-harness.ts

@@ -26,7 +26,7 @@
  */
 
 import type { DotApp, DotAppBuilder } from './define-app.js';
-import type { AnyPip, EmptyShape, ServiceRecord } from './pip-contract.js';
+import type { AnyPip, EmptyShape, Pip, ServiceRecord, Token } from './pip-contract.js';
 import { defineApp } from './define-app.js';
 
 export type TestAppOptions = {
@@ -70,3 +70,142 @@ export async function bootTestApp<TServices extends ServiceRecord = EmptyShape>(
 ): Promise<DotApp<TServices>> {
   return testApp<TServices>(pips, options).boot();
 }
+
+/**
+ * Rest-tuple guard for {@link TestPipBuilder.boot} — the same trick the app
+ * builder's `UseGuard` uses. While any need is still unprovided, `boot()`
+ * demands an impossible second argument, so the call site fails with
+ * "Expected 2 arguments, but got 1" and the error payload names the
+ * missing wire keys and their types.
+ */
+type TestPipBootGuard<TRemaining extends ServiceRecord> = keyof TRemaining extends never
+  ? readonly []
+  : readonly [
+      needs: {
+        readonly 'DOT-TEST: pip needs still unprovided — call .provide() for each': {
+          readonly [K in keyof TRemaining]: TRemaining[K];
+        };
+      },
+    ];
+
+/**
+ * Typed unit-test builder for a single pip — see {@link testPip}.
+ *
+ * `TRemaining` tracks the wire keys not yet covered by `.provide()`;
+ * `TServices` accumulates what the booted app will expose (the fakes plus
+ * the pip's own provides).
+ */
+export type TestPipBuilder<TRemaining extends ServiceRecord, TServices extends ServiceRecord> = {
+  /**
+   * Satisfy one need directly with a fake. Token form — the token names
+   * the wire key and carries the type:
+   *
+   * ```ts
+   * testPip(reports).provide(Db, fakeDb)
+   * ```
+   */
+  provide<K extends keyof TRemaining & string, T extends TRemaining[K]>(
+    token: Token<T, K>,
+    value: T,
+  ): TestPipBuilder<Omit<TRemaining, K>, TServices & Readonly<Record<K, T>>>;
+  /**
+   * Satisfy one need directly with a fake. Key form — for anonymous
+   * `service<T>()` needs, where the wire key is the property name:
+   *
+   * ```ts
+   * testPip(billing).provide('db', fakeDb)
+   * ```
+   */
+  provide<K extends keyof TRemaining & string>(
+    key: K,
+    value: TRemaining[K],
+  ): TestPipBuilder<Omit<TRemaining, K>, TServices & Readonly<Record<K, TRemaining[K]>>>;
+  /** Boot the pip against the provided fakes. Compile error until every need is provided. */
+  boot(...guard: TestPipBootGuard<TRemaining>): Promise<DotApp<TServices>>;
+  /** Boot + start. Same guard as {@link TestPipBuilder.boot}. */
+  start(...guard: TestPipBootGuard<TRemaining>): Promise<DotApp<TServices>>;
+};
+
+/** Internal accumulating state for {@link testPip}. */
+type TestPipState = {
+  readonly pip: AnyPip;
+  readonly fakes: Readonly<Record<string, unknown>>;
+  readonly options: TestAppOptions;
+};
+
+/**
+ * Unit-test a single pip with **typed overrides** — the compile-checked
+ * counterpart to {@link testApp}'s erased arrays.
+ *
+ * Each `.provide()` satisfies one of the pip's needs directly (no real
+ * provider pip, no dependency chain) and removes it from the builder's
+ * remaining-needs type. `boot()` only compiles once every need is covered,
+ * and a fake of the wrong shape fails at the `.provide()` call site:
+ *
+ * ```ts
+ * import { testPip } from '@arki/dot/test-harness';
+ *
+ * const app = await testPip(catalog)
+ *   .provide(Db, fakeDb)          // token need
+ *   .provide('cache', fakeKv)     // anonymous need — wire key is the alias
+ *   .boot();
+ *
+ * expect(app.services.catalog.list()).toEqual([]);
+ * await app.dispose();
+ * ```
+ *
+ * `service.lazy<T>()` needs accept either a plain `T` fake (the kernel
+ * lifts it) or a `Lazy<T>` handle (`lazyOf(value)` is handy here).
+ * Lifecycle semantics are the real kernel's — the fakes are published by a
+ * synthetic first pip, so reverse-order teardown and lazy auto-dispose
+ * behave exactly as in production.
+ */
+export function testPip<TNeeds extends ServiceRecord, TProvides extends ServiceRecord>(
+  pip: Pip<TNeeds, TProvides>,
+  options: TestAppOptions = {},
+): TestPipBuilder<TNeeds, TProvides> {
+  // Erasure seam — same boundary as `makeBuilder` in define-app.ts: the
+  // runtime impl is untyped, the type parameters do all the guarding.
+  return makeTestPipBuilder({ pip: pip as AnyPip, fakes: {}, options }) as TestPipBuilder<TNeeds, TProvides>;
+}
+
+/**
+ * Erased implementation behind {@link testPip}. Mirrors `makeBuilder` in
+ * `define-app.ts`: the runtime is untyped, the single cast at the return
+ * is the seam, and the type parameters do all the guarding.
+ */
+function makeTestPipBuilder(state: TestPipState): TestPipBuilder<ServiceRecord, ServiceRecord> {
+  const bootApp = async (): Promise<DotApp<ServiceRecord>> => {
+    const pips: AnyPip[] = [];
+    if (Object.keys(state.fakes).length > 0) {
+      const fakes = { ...state.fakes };
+      pips.push({
+        name: `test:fakes(${state.pip.name})`,
+        needs: {},
+        renames: {},
+        hooks: { boot: () => fakes },
+      });
+    }
+    pips.push(state.pip);
+    return testApp<ServiceRecord>(pips, {
+      name: state.options.name ?? `test:${state.pip.name}`,
+      ...(state.options.config === undefined ? {} : { config: state.options.config }),
+    }).boot();
+  };
+
+  const impl = {
+    provide(tokenOrKey: Token<unknown, string> | string, value: unknown) {
+      const key = typeof tokenOrKey === 'string' ? tokenOrKey : tokenOrKey.key;
+      return makeTestPipBuilder({ ...state, fakes: { ...state.fakes, [key]: value } });
+    },
+    async boot(..._guard: readonly unknown[]) {
+      return bootApp();
+    },
+    async start(..._guard: readonly unknown[]) {
+      const app = await bootApp();
+      await app.start();
+      return app;
+    },
+  };
+  return impl as TestPipBuilder<ServiceRecord, ServiceRecord>;
+}