@arki/dot 0.1.4 → 0.2.0

package/src/kernel/app-instance.ts

@@ -104,6 +104,8 @@ export type DotAppInternalConfig = {
    * happen before there's a public seam to call `subscribe()` on.
    */
   observers?: readonly DotLifecycleObserver[];
+  /** Per-hook watchdog budget in ms — see `defineApp`'s option of the same name. */
+  hookTimeoutMs?: number;
 };
 
 /**
@@ -122,6 +124,9 @@ export class DotAppImpl {
   /** Macro-state of the app. */
   #state: DotLifecycleState = 'defined';
 
+  /** Per-hook watchdog budget (ms); `undefined` = no watchdog. */
+  readonly #hookTimeoutMs: number | undefined;
+
   /** Manifest finalised after `configure`. */
   #manifest: DotAppManifest;
 
@@ -180,6 +185,7 @@ export class DotAppImpl {
   constructor(config: DotAppInternalConfig) {
     this.#appName = config.appName;
     this.#appVersion = config.appVersion;
+    this.#hookTimeoutMs = config.hookTimeoutMs;
     this.#config = Object.freeze({ ...config.config });
     this.#logger = new Logger('arki:dot:lifecycle', { 'dot.app.name': config.appName });
     this.#observers = new Set(config.observers);
@@ -675,6 +681,44 @@ export class DotAppImpl {
     return ctx;
   }
 
+  /**
+   * Race one hook invocation against the app's `hookTimeoutMs` watchdog.
+   * No budget configured → plain pass-through. On timeout the returned
+   * promise rejects with `DOT_LIFECYCLE_E015` naming the pip and hook,
+   * and the call site's existing catch path applies the phase's normal
+   * failure rules (boot rollback, start cascade, teardown aggregation).
+   * The hook's own promise cannot be cancelled — the watchdog makes a
+   * hang visible and bounded; it does not kill the hung work.
+   */
+  async #withHookBudget<T>(pipName: string, hook: DotLifecycleHook, run: () => Promise<T> | T): Promise<T> {
+    const budget = this.#hookTimeoutMs;
+    if (budget === undefined) return run();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const watchdog = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => {
+        reject(
+          new DotLifecycleError({
+            code: DotLifecycleErrorCode.HookTimeout,
+            phase: hook,
+            pip: pipName,
+            message:
+              `${hook} hook of pip "${pipName}" exceeded the ${budget.toString()}ms hookTimeoutMs watchdog. ` +
+              `The kernel treats the hook as failed and applies its normal rollback/aggregation rules, but ` +
+              `cannot cancel the hook's promise — find the hang (a missing await? a connection that never ` +
+              `settles?) or raise the budget in defineApp(name, { hookTimeoutMs }).`,
+          }),
+        );
+      }, budget);
+      // A pending watchdog must never keep an otherwise-finished process alive.
+      timer.unref?.();
+    });
+    try {
+      return await Promise.race([Promise.resolve(run()), watchdog]);
+    } finally {
+      if (timer !== undefined) clearTimeout(timer);
+    }
+  }
+
   /**
    * Inner boot loop. Separated from `#runBoot` so the phase span wrapper
    * stays thin and the loop body — which orchestrates rollback on
@@ -770,26 +814,33 @@ export class DotAppImpl {
       this.#emitHook('boot', pip.name, record.order, 'starting');
       let result: ServiceRecord | void;
       try {
-        result = await withPipHookSpan(
-          {
-            appName: this.#appName,
-            pipName: pip.name,
-            pipVersion: pip.version,
-            hook: 'boot',
-            order: record.order,
-            logger: pipLogger,
-          },
-          // Erasure boundary: hooks are stored as `(ctx: never) => ...`;
-          // the kernel is the one caller allowed to cross it.
-          () => pip.hooks.boot!(ctx as never),
+        result = await this.#withHookBudget(pip.name, 'boot', () =>
+          withPipHookSpan(
+            {
+              appName: this.#appName,
+              pipName: pip.name,
+              pipVersion: pip.version,
+              hook: 'boot',
+              order: record.order,
+              logger: pipLogger,
+            },
+            // Erasure boundary: hooks are stored as `(ctx: never) => ...`;
+            // the kernel is the one caller allowed to cross it.
+            () => pip.hooks.boot!(ctx as never),
+          ),
         );
       } catch (error) {
+        const timedOut = error instanceof DotLifecycleError && error.code === DotLifecycleErrorCode.HookTimeout;
         return fail({
           record,
-          code: DotLifecycleErrorCode.BootFailed,
-          message: `boot hook threw for pip "${pip.name}": ${stringifyError(error)}`,
-          remediation: `Fix the error in the boot() hook of "${pip.name}". If boot opens partial resources before throwing, clean them up locally — DOT only disposes pips whose boot completed.`,
-          docsAnchor: 'boot-failed',
+          code: timedOut ? DotLifecycleErrorCode.HookTimeout : DotLifecycleErrorCode.BootFailed,
+          message: timedOut
+            ? error.message
+            : `boot hook threw for pip "${pip.name}": ${stringifyError(error)}`,
+          remediation: timedOut
+            ? `Find the hang in the boot() hook of "${pip.name}" — a missing await or a connection that never settles — or raise defineApp's hookTimeoutMs.`
+            : `Fix the error in the boot() hook of "${pip.name}". If boot opens partial resources before throwing, clean them up locally — DOT only disposes pips whose boot completed.`,
+          docsAnchor: timedOut ? 'hook-timeout' : 'boot-failed',
           durationMs: performance.now() - started,
           cause: error,
           rollback: bootedRecords,
@@ -917,25 +968,32 @@ export class DotAppImpl {
       const startedAt = performance.now();
       this.#emitHook('start', pip.name, record.order, 'starting');
       try {
-        await withPipHookSpan(
-          {
-            appName: this.#appName,
-            pipName: pip.name,
-            pipVersion: pip.version,
-            hook: 'start',
-            order: record.order,
-            logger: pipLogger,
-          },
-          () => pip.hooks.start!(ctx as never),
+        await this.#withHookBudget(pip.name, 'start', () =>
+          withPipHookSpan(
+            {
+              appName: this.#appName,
+              pipName: pip.name,
+              pipVersion: pip.version,
+              hook: 'start',
+              order: record.order,
+              logger: pipLogger,
+            },
+            () => pip.hooks.start!(ctx as never),
+          ),
         );
       } catch (error) {
         const durationMs = performance.now() - startedAt;
+        const timedOut = error instanceof DotLifecycleError && error.code === DotLifecycleErrorCode.HookTimeout;
         const issue = makeIssue({
-          code: DotLifecycleErrorCode.StartFailed,
+          code: timedOut ? DotLifecycleErrorCode.HookTimeout : DotLifecycleErrorCode.StartFailed,
           pip: pip.name,
-          message: `start hook threw for pip "${pip.name}": ${stringifyError(error)}`,
-          remediation: `Fix the error in the start() hook of "${pip.name}". DOT will stop all already-started pips and dispose all booted pips in reverse order.`,
-          docsAnchor: 'start-failed',
+          message: timedOut
+            ? error.message
+            : `start hook threw for pip "${pip.name}": ${stringifyError(error)}`,
+          remediation: timedOut
+            ? `Find the hang in the start() hook of "${pip.name}" — or raise defineApp's hookTimeoutMs. DOT rolls back as for any start failure.`
+            : `Fix the error in the start() hook of "${pip.name}". DOT will stop all already-started pips and dispose all booted pips in reverse order.`,
+          docsAnchor: timedOut ? 'hook-timeout' : 'start-failed',
         });
         record.issues.push(issue);
         record.lifecycleDiagnostics.push({
@@ -958,7 +1016,7 @@ export class DotAppImpl {
         this.#manifest = this.#buildManifest();
         const failures = [...stopFailures, ...disposeFailures];
         throw new DotLifecycleError({
-          code: DotLifecycleErrorCode.StartFailed,
+          code: timedOut ? DotLifecycleErrorCode.HookTimeout : DotLifecycleErrorCode.StartFailed,
           phase: 'start',
           pip: pip.name,
           message: issue.message,
@@ -1053,16 +1111,18 @@ export class DotAppImpl {
       const startedAt = performance.now();
       this.#emitHook('stop', record.pip.name, record.order, 'starting');
       try {
-        await withPipHookSpan(
-          {
-            appName: this.#appName,
-            pipName: record.pip.name,
-            pipVersion: record.pip.version,
-            hook: 'stop',
-            order: record.order,
-            logger: pipLogger,
-          },
-          () => record.pip.hooks.stop!(ctx as never),
+        await this.#withHookBudget(record.pip.name, 'stop', () =>
+          withPipHookSpan(
+            {
+              appName: this.#appName,
+              pipName: record.pip.name,
+              pipVersion: record.pip.version,
+              hook: 'stop',
+              order: record.order,
+              logger: pipLogger,
+            },
+            () => record.pip.hooks.stop!(ctx as never),
+          ),
         );
         record.started = false;
         const durationMs = performance.now() - startedAt;
@@ -1265,16 +1325,18 @@ export class DotAppImpl {
       const startedAt = performance.now();
       this.#emitHook('dispose', record.pip.name, record.order, 'starting');
       try {
-        await withPipHookSpan(
-          {
-            appName: this.#appName,
-            pipName: record.pip.name,
-            pipVersion: record.pip.version,
-            hook: 'dispose',
-            order: record.order,
-            logger: pipLogger,
-          },
-          () => record.pip.hooks.dispose!(ctx as never),
+        await this.#withHookBudget(record.pip.name, 'dispose', () =>
+          withPipHookSpan(
+            {
+              appName: this.#appName,
+              pipName: record.pip.name,
+              pipVersion: record.pip.version,
+              hook: 'dispose',
+              order: record.order,
+              logger: pipLogger,
+            },
+            () => record.pip.hooks.dispose!(ctx as never),
+          ),
         );
         record.booted = false;
         const durationMs = performance.now() - startedAt;

package/src/lifecycle.ts

@@ -76,6 +76,8 @@ export const DotLifecycleErrorCode = {
   ServiceCollision: 'DOT_LIFECYCLE_E013',
   /** A needs alias, publish key, or rename target uses the reserved `$` prefix. */
   ReservedServiceKey: 'DOT_LIFECYCLE_E014',
+  /** A lifecycle hook exceeded the app's `hookTimeoutMs` watchdog. */
+  HookTimeout: 'DOT_LIFECYCLE_E015',
 } as const;
 
 export type DotLifecycleErrorCodeValue = (typeof DotLifecycleErrorCode)[keyof typeof DotLifecycleErrorCode];

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>;
+}