@checkstack/backend-api 0.14.0 → 0.14.1

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # @checkstack/backend-api
 
+## 0.14.1
+
+### Patch Changes
+
+- 302cd3f: fix: resilient startup routing + /health and /ready endpoints
+
+  Three fixes that together eliminate startup-race errors during boot and
+  hot-reload, plus a new readiness API for plugins.
+
+  1. **TrieRouter swap (root cause).** Hono's default `SmartRouter` freezes
+     its matcher on the first request — any later `app.add()` throws
+     `MESSAGE_MATCHER_IS_ALREADY_BUILT`. Plugins register routes during
+     `init()` (and at runtime via `loadSinglePlugin`), so an early request
+     during boot would silently lock the matcher with only the module-load
+     routes, and every later route registration would fail. The backend
+     now uses `TrieRouter`, which is incremental — routes can be added at
+     any time, including after thousands of requests have been served.
+     This also future-proofs runtime plugin install.
+
+  2. **Init gating + fail-loud.** Non-bypass requests now `await` an
+     `initPromise` (with a 30s timeout that returns 503 + Retry-After) so
+     no traffic reaches Hono before plugins finish registering routes.
+     Init failures crash the process via `process.exit(1)` so docker/k8s
+     restart cleanly instead of silently serving a half-initialized
+     backend.
+
+  3. **`/assets/*` fall-through.** The production frontend asset handler
+     now calls `next()` instead of `c.notFound()` on miss, so
+     plugin-asset routes registered later (`/assets/plugins/:pluginName/*`)
+     actually get a chance to match.
+
+  ### New: platform endpoints under `/.checkstack/*`
+
+  - `GET /.checkstack/health` — liveness, always 200 once the process is up.
+  - `GET /.checkstack/ready` — readiness, 503 until init completes and all
+    critical probes pass; 200 otherwise. Returns `{ ready, checks: [...] }`
+    with per-probe status, message/error and duration.
+
+  The leading `.checkstack/` prefix namespaces platform-level endpoints
+  away from plugin `/api/*`, runtime frontend assets, and the SPA wildcard,
+  leaving room for additional operator endpoints in the future.
+
+  ### New: plugin readiness API
+
+  Plugins can contribute readiness probes via the new
+  `coreServices.readinessRegistry` service:
+
+  ```ts
+  registerInit({
+    deps: { readiness: coreServices.readinessRegistry },
+    async init({ readiness }) {
+      readiness.register({
+        name: "queue.connected",
+        critical: true,
+        check: async () => ({
+          ok: pool.isConnected(),
+          message: pool.isConnected() ? undefined : "queue pool not connected",
+        }),
+      });
+    },
+  });
+  ```
+
+  Probes run in parallel, throwing probes are reported as `ok: false`,
+  and non-critical probes don't block readiness.
+
+  - @checkstack/cache-api@0.2.3
+  - @checkstack/queue-api@0.2.17
+  - @checkstack/common@0.7.0
+  - @checkstack/healthcheck-common@1.0.0
+  - @checkstack/signal-common@0.2.0
+
 ## 0.14.0
 
 ### Minor Changes

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@checkstack/backend-api",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "type": "module",
   "main": "./src/index.ts",
   "scripts": {
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo -b",
     "lint": "bun run lint:code",
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
     "@checkstack/common": "0.7.0",
-    "@checkstack/healthcheck-common": "0.13.0",
-    "@checkstack/cache-api": "0.2.1",
-    "@checkstack/queue-api": "0.2.15",
+    "@checkstack/healthcheck-common": "1.0.0",
+    "@checkstack/cache-api": "0.2.2",
+    "@checkstack/queue-api": "0.2.16",
     "@checkstack/signal-common": "0.2.0",
     "@orpc/client": "^1.13.14",
     "@orpc/contract": "^1.13.14",

package/src/core-services.ts

@@ -19,6 +19,7 @@ import {
 } from "./types";
 import type { EventBus } from "./event-bus-types";
 import type { WebSocketRouteRegistry } from "./ws-registry";
+import type { ReadinessRegistry } from "./readiness-registry";
 
 export * from "./types";
 
@@ -53,4 +54,7 @@ export const coreServices = {
     "core.cachePluginRegistry",
   ),
   cacheManager: createServiceRef<CacheManager>("core.cacheManager"),
+  readinessRegistry: createServiceRef<ReadinessRegistry>(
+    "core.readinessRegistry",
+  ),
 };

package/src/index.ts

@@ -28,3 +28,4 @@ export * from "./collector-registry";
 export * from "./incremental-aggregation";
 export * from "./aggregated-result";
 export * from "./ws-registry";
+export * from "./readiness-registry";

package/src/readiness-registry.ts

@@ -0,0 +1,53 @@
+/**
+ * Result of a single readiness probe.
+ */
+export interface ReadinessCheckResult {
+  ok: boolean;
+  /** Optional human-readable detail (shown verbatim in the /ready response). */
+  message?: string;
+}
+
+/**
+ * Single readiness check. The platform calls these in parallel from `/ready`.
+ *
+ * Implementations should return quickly (target < 1s). Long-running probes
+ * should cache their last result and refresh in the background — the
+ * `/ready` endpoint is hit by orchestrators (k8s, docker-compose) on a tight
+ * loop and slow probes will produce false-negative restarts.
+ */
+export interface ReadinessCheck {
+  /** Probe name (e.g. "database", "queue", "auth-strategy-loaded"). */
+  name: string;
+  /** True if this probe should block startup. False = informational only. */
+  critical?: boolean;
+  check: () => Promise<ReadinessCheckResult>;
+}
+
+/**
+ * Plugin-facing API for contributing readiness probes to the `/ready` endpoint.
+ *
+ * The core platform always contributes a "core.init" probe that flips ready
+ * once `init()` has resolved. Plugins may add their own (e.g. "queue.connected",
+ * "auth.strategy-registered") to gate the platform from accepting traffic until
+ * their preconditions are met.
+ *
+ * @example
+ * ```ts
+ * registerInit({
+ *   deps: { readiness: coreServices.readinessRegistry },
+ *   async init({ readiness }) {
+ *     readiness.register({
+ *       name: "queue.connected",
+ *       critical: true,
+ *       check: async () => ({
+ *         ok: pool.isConnected(),
+ *         message: pool.isConnected() ? undefined : "queue pool not connected",
+ *       }),
+ *     });
+ *   },
+ * });
+ * ```
+ */
+export interface ReadinessRegistry {
+  register(check: ReadinessCheck): void;
+}

package/tsconfig.json

@@ -2,5 +2,22 @@
   "extends": "@checkstack/tsconfig/backend.json",
   "include": [
     "src"
+  ],
+  "references": [
+    {
+      "path": "../cache-api"
+    },
+    {
+      "path": "../common"
+    },
+    {
+      "path": "../healthcheck-common"
+    },
+    {
+      "path": "../queue-api"
+    },
+    {
+      "path": "../signal-common"
+    }
   ]
-}
+}