@beignet/core 0.0.21 → 0.0.22

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @beignet/core
 
+## 0.0.22
+
+### Patch Changes
+
+- Add app-owned readiness helpers, first-party provider health checks, generated `/api/ready` routes, and doctor readiness hints.
+
 ## 0.0.21
 
 ### Patch Changes

package/README.md

@@ -1269,6 +1269,32 @@ The public adapter contract is `HttpAdapter<NativeRequest, NativeResponse>`.
 Use it when building a runtime package beyond the first-party `@beignet/web`
 and `@beignet/next` adapters.
 
+### Health and readiness
+
+Use `createHealthHandler(...)` and `runHealthChecks(...)` from
+`@beignet/core/server` for app-owned liveness and readiness endpoints.
+Readiness checks should be cheap, bounded, and non-mutating:
+
+```ts
+import { createHealthHandler } from "@beignet/core/server";
+import { server } from "@/server";
+
+const readiness = createHealthHandler(
+  server.ports,
+  {
+    checks: {
+      database: (ports) => ports.db.checkHealth(),
+    },
+    timeoutMs: 2000,
+  },
+  "production",
+);
+```
+
+Provider checks such as `ctx.ports.db.checkHealth()` should be called from
+routes, workers, or deployment probes. Do not run migrations, drains, workers,
+or polling loops from health checks.
+
 ### Request instrumentation and tracing
 
 `createServer(...)` owns request instrumentation. For every request it

package/dist/server/health.d.ts

@@ -4,6 +4,27 @@
  */
 import type { AnyPorts } from "../ports/index.js";
 import type { HttpRequestLike, HttpResponseLike } from "./types.js";
+/**
+ * Per-dependency health detail returned by readiness checks.
+ */
+export interface HealthCheckDetail {
+    /**
+     * Whether this dependency is healthy.
+     */
+    ok: boolean;
+    /**
+     * Optional human-readable status. Avoid secrets and raw provider credentials.
+     */
+    message?: string;
+    /**
+     * Milliseconds spent running this dependency check.
+     */
+    durationMs?: number;
+    /**
+     * Optional safe metadata for operators.
+     */
+    metadata?: Record<string, unknown>;
+}
 /**
  * Health check result returned by health handlers.
  */
@@ -15,10 +36,33 @@ export interface HealthCheckResult {
     /**
      * Optional per-dependency health details.
      */
-    details?: Record<string, {
-        ok: boolean;
-        message?: string;
-    }>;
+    details?: Record<string, HealthCheckDetail>;
+}
+/**
+ * A named dependency check run by {@link runHealthChecks}.
+ */
+export type HealthCheck<Ports> = (ports: Ports) => Promise<HealthCheckDetail | boolean | undefined> | HealthCheckDetail | boolean | undefined;
+/**
+ * Named dependency checks for an app-owned readiness endpoint.
+ */
+export type HealthChecks<Ports> = Record<string, HealthCheck<Ports>>;
+/**
+ * Options for running named dependency checks.
+ */
+export interface RunHealthChecksOptions {
+    /**
+     * Maximum time to wait for each dependency check.
+     *
+     * Defaults to 2000ms.
+     */
+    timeoutMs?: number;
+    /**
+     * Include thrown error messages in dependency details.
+     *
+     * Defaults to true. Set false in production responses when provider errors
+     * may include sensitive details.
+     */
+    includeErrorDetails?: boolean;
 }
 /**
  * Health check configuration.
@@ -34,11 +78,24 @@ export interface HealthConfig<Ports> {
     suggestedPath?: string;
     /** Custom health check function */
     check?: (ports: Ports) => Promise<HealthCheckResult>;
+    /** Named dependency checks for an app-owned readiness endpoint */
+    checks?: HealthChecks<Ports>;
+    /** Per-check timeout for named dependency checks */
+    timeoutMs?: number;
 }
 /**
  * Application environment.
  */
 export type AppEnvironment = "development" | "production" | "test";
+/**
+ * Run named dependency health checks in parallel and aggregate the result.
+ *
+ * This is intended for app-owned readiness endpoints. Checks should be cheap,
+ * bounded, non-mutating probes such as `SELECT 1`, Redis `PING`, or provider
+ * health endpoints. Do not start workers, drains, migrations, or polling loops
+ * from readiness checks.
+ */
+export declare function runHealthChecks<Ports extends AnyPorts>(ports: Ports, checks: HealthChecks<Ports>, options?: RunHealthChecksOptions): Promise<HealthCheckResult>;
 /**
  * Create a framework-neutral health check handler.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/server/health.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,EAAE,EAAE,OAAO,CAAC;IACZ;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7D;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,KAAK;IACjC,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mCAAmC;IACnC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACtD;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,YAAY,GAAG,MAAM,CAAC;AAEnE;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,SAAS,QAAQ,EACxD,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,SAAS,EAC7C,GAAG,EAAE,cAAc,GAClB,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAoCrD"}
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/server/health.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,EAAE,EAAE,OAAO,CAAC;IACZ;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,EAAE,EAAE,OAAO,CAAC;IACZ;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC7C;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,KAAK,IAAI,CAC/B,KAAK,EAAE,KAAK,KAEV,OAAO,CAAC,iBAAiB,GAAG,OAAO,GAAG,SAAS,CAAC,GAChD,iBAAiB,GACjB,OAAO,GACP,SAAS,CAAC;AAEd;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,KAAK;IACjC,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mCAAmC;IACnC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACrD,kEAAkE;IAClE,MAAM,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IAC7B,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,YAAY,GAAG,MAAM,CAAC;AAyDnE;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,KAAK,SAAS,QAAQ,EAC1D,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,EAC3B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,iBAAiB,CAAC,CA6C5B;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,SAAS,QAAQ,EACxD,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,SAAS,EAC7C,GAAG,EAAE,cAAc,GAClB,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAyCrD"}

package/dist/server/health.js

@@ -2,6 +2,84 @@
  * Health check handler
  * Health check handler for Beignet server adapters.
  */
+const DEFAULT_HEALTH_TIMEOUT_MS = 2000;
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function assertTimeout(timeoutMs) {
+    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+        throw new Error("Health check timeoutMs must be a positive integer.");
+    }
+}
+function normalizeHealthDetail(result) {
+    if (typeof result === "boolean")
+        return { ok: result };
+    return result ?? { ok: true };
+}
+function redactHealthDetail(detail, includeErrorDetails) {
+    if (includeErrorDetails || detail.ok || detail.message === undefined) {
+        return detail;
+    }
+    return {
+        ...detail,
+        message: "Health check failed",
+    };
+}
+function withTimeout(promise, timeoutMs, name) {
+    let timeout;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeout = setTimeout(() => {
+            reject(new Error(`Health check "${name}" did not complete within ${timeoutMs}ms.`));
+        }, timeoutMs);
+    });
+    return Promise.race([promise, timeoutPromise]).finally(() => {
+        if (timeout)
+            clearTimeout(timeout);
+    });
+}
+/**
+ * Run named dependency health checks in parallel and aggregate the result.
+ *
+ * This is intended for app-owned readiness endpoints. Checks should be cheap,
+ * bounded, non-mutating probes such as `SELECT 1`, Redis `PING`, or provider
+ * health endpoints. Do not start workers, drains, migrations, or polling loops
+ * from readiness checks.
+ */
+export async function runHealthChecks(ports, checks, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_HEALTH_TIMEOUT_MS;
+    assertTimeout(timeoutMs);
+    const includeErrorDetails = options.includeErrorDetails ?? true;
+    const entries = await Promise.all(Object.entries(checks).map(async ([name, check]) => {
+        const startedAt = Date.now();
+        try {
+            const detail = redactHealthDetail(normalizeHealthDetail(await withTimeout(Promise.resolve(check(ports)), timeoutMs, name)), includeErrorDetails);
+            return [
+                name,
+                {
+                    ...detail,
+                    durationMs: Date.now() - startedAt,
+                },
+            ];
+        }
+        catch (error) {
+            return [
+                name,
+                {
+                    ok: false,
+                    message: includeErrorDetails
+                        ? errorMessage(error)
+                        : "Health check failed",
+                    durationMs: Date.now() - startedAt,
+                },
+            ];
+        }
+    }));
+    const details = Object.fromEntries(entries);
+    return {
+        ok: Object.values(details).every((detail) => detail.ok),
+        details,
+    };
+}
 /**
  * Create a framework-neutral health check handler.
  *
@@ -35,6 +113,12 @@ export function createHealthHandler(ports, healthConfig, env) {
                 };
             }
         }
+        else if (healthConfig?.checks) {
+            result = await runHealthChecks(ports, healthConfig.checks, {
+                timeoutMs: healthConfig.timeoutMs,
+                includeErrorDetails: env !== "production",
+            });
+        }
         else {
             result = { ok: true };
         }

package/dist/server/health.js.map

@@ -1 +1 @@
-{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/server/health.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAwCH;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAY,EACZ,YAA6C,EAC7C,GAAmB;IAEnB,OAAO,KAAK,EAAE,IAAqB,EAA6B,EAAE;QAChE,IAAI,MAAyB,CAAC;QAC9B,IAAI,YAAY,EAAE,KAAK,EAAE,CAAC;YACxB,IAAI,CAAC;gBACH,MAAM,GAAG,MAAM,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC3C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,mDAAmD;gBACnD,iFAAiF;gBACjF,MAAM,mBAAmB,GAAG,GAAG,KAAK,aAAa,IAAI,GAAG,KAAK,MAAM,CAAC;gBACpE,MAAM,GAAG;oBACP,EAAE,EAAE,KAAK;oBACT,OAAO,EAAE;wBACP,KAAK,EAAE;4BACL,EAAE,EAAE,KAAK;4BACT,OAAO,EAAE,mBAAmB;gCAC1B,CAAC,CAAC,KAAK,YAAY,KAAK;oCACtB,CAAC,CAAC,KAAK,CAAC,OAAO;oCACf,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;gCACjB,CAAC,CAAC,qBAAqB;yBAC1B;qBACF;iBACF,CAAC;YACJ,CAAC;QACH,CAAC;aAAM,CAAC;YACN,MAAM,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;QACxB,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;QAErC,OAAO;YACL,MAAM;YACN,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;SAChD,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/server/health.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beignet/core",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "type": "module",
   "description": "Core framework primitives for Beignet",
   "exports": {

package/src/server/health.ts

@@ -6,6 +6,28 @@
 import type { AnyPorts } from "../ports/index.js";
 import type { HttpRequestLike, HttpResponseLike } from "./types.js";
 
+/**
+ * Per-dependency health detail returned by readiness checks.
+ */
+export interface HealthCheckDetail {
+  /**
+   * Whether this dependency is healthy.
+   */
+  ok: boolean;
+  /**
+   * Optional human-readable status. Avoid secrets and raw provider credentials.
+   */
+  message?: string;
+  /**
+   * Milliseconds spent running this dependency check.
+   */
+  durationMs?: number;
+  /**
+   * Optional safe metadata for operators.
+   */
+  metadata?: Record<string, unknown>;
+}
+
 /**
  * Health check result returned by health handlers.
  */
@@ -17,7 +39,42 @@ export interface HealthCheckResult {
   /**
    * Optional per-dependency health details.
    */
-  details?: Record<string, { ok: boolean; message?: string }>;
+  details?: Record<string, HealthCheckDetail>;
+}
+
+/**
+ * A named dependency check run by {@link runHealthChecks}.
+ */
+export type HealthCheck<Ports> = (
+  ports: Ports,
+) =>
+  | Promise<HealthCheckDetail | boolean | undefined>
+  | HealthCheckDetail
+  | boolean
+  | undefined;
+
+/**
+ * Named dependency checks for an app-owned readiness endpoint.
+ */
+export type HealthChecks<Ports> = Record<string, HealthCheck<Ports>>;
+
+/**
+ * Options for running named dependency checks.
+ */
+export interface RunHealthChecksOptions {
+  /**
+   * Maximum time to wait for each dependency check.
+   *
+   * Defaults to 2000ms.
+   */
+  timeoutMs?: number;
+  /**
+   * Include thrown error messages in dependency details.
+   *
+   * Defaults to true. Set false in production responses when provider errors
+   * may include sensitive details.
+   */
+  includeErrorDetails?: boolean;
 }
 
 /**
@@ -34,6 +91,10 @@ export interface HealthConfig<Ports> {
   suggestedPath?: string;
   /** Custom health check function */
   check?: (ports: Ports) => Promise<HealthCheckResult>;
+  /** Named dependency checks for an app-owned readiness endpoint */
+  checks?: HealthChecks<Ports>;
+  /** Per-check timeout for named dependency checks */
+  timeoutMs?: number;
 }
 
 /**
@@ -41,6 +102,120 @@ export interface HealthConfig<Ports> {
  */
 export type AppEnvironment = "development" | "production" | "test";
 
+const DEFAULT_HEALTH_TIMEOUT_MS = 2000;
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function assertTimeout(timeoutMs: number): void {
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new Error("Health check timeoutMs must be a positive integer.");
+  }
+}
+
+function normalizeHealthDetail(
+  result: HealthCheckDetail | boolean | undefined,
+): HealthCheckDetail {
+  if (typeof result === "boolean") return { ok: result };
+  return result ?? { ok: true };
+}
+
+function redactHealthDetail(
+  detail: HealthCheckDetail,
+  includeErrorDetails: boolean,
+): HealthCheckDetail {
+  if (includeErrorDetails || detail.ok || detail.message === undefined) {
+    return detail;
+  }
+
+  return {
+    ...detail,
+    message: "Health check failed",
+  };
+}
+
+function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  name: string,
+): Promise<T> {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeout = setTimeout(() => {
+      reject(
+        new Error(
+          `Health check "${name}" did not complete within ${timeoutMs}ms.`,
+        ),
+      );
+    }, timeoutMs);
+  });
+
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    if (timeout) clearTimeout(timeout);
+  });
+}
+
+/**
+ * Run named dependency health checks in parallel and aggregate the result.
+ *
+ * This is intended for app-owned readiness endpoints. Checks should be cheap,
+ * bounded, non-mutating probes such as `SELECT 1`, Redis `PING`, or provider
+ * health endpoints. Do not start workers, drains, migrations, or polling loops
+ * from readiness checks.
+ */
+export async function runHealthChecks<Ports extends AnyPorts>(
+  ports: Ports,
+  checks: HealthChecks<Ports>,
+  options: RunHealthChecksOptions = {},
+): Promise<HealthCheckResult> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_HEALTH_TIMEOUT_MS;
+  assertTimeout(timeoutMs);
+
+  const includeErrorDetails = options.includeErrorDetails ?? true;
+  const entries = await Promise.all(
+    Object.entries(checks).map(async ([name, check]) => {
+      const startedAt = Date.now();
+
+      try {
+        const detail = redactHealthDetail(
+          normalizeHealthDetail(
+            await withTimeout(Promise.resolve(check(ports)), timeoutMs, name),
+          ),
+          includeErrorDetails,
+        );
+
+        return [
+          name,
+          {
+            ...detail,
+            durationMs: Date.now() - startedAt,
+          },
+        ] as const;
+      } catch (error) {
+        return [
+          name,
+          {
+            ok: false,
+            message: includeErrorDetails
+              ? errorMessage(error)
+              : "Health check failed",
+            durationMs: Date.now() - startedAt,
+          },
+        ] as const;
+      }
+    }),
+  );
+
+  const details = Object.fromEntries(entries);
+
+  return {
+    ok: Object.values(details).every((detail) => detail.ok),
+    details,
+  };
+}
+
 /**
  * Create a framework-neutral health check handler.
  *
@@ -76,6 +251,11 @@ export function createHealthHandler<Ports extends AnyPorts>(
           },
         };
       }
+    } else if (healthConfig?.checks) {
+      result = await runHealthChecks(ports, healthConfig.checks, {
+        timeoutMs: healthConfig.timeoutMs,
+        includeErrorDetails: env !== "production",
+      });
     } else {
       result = { ok: true };
     }