@spfn/core 0.3.0-beta.2 → 0.3.0-beta.21

package/dist/server/index.d.ts

@@ -5,13 +5,20 @@ import { serve } from '@hono/node-server';
 import { NamedMiddleware, Router } from '@spfn/core/route';
 import { OnErrorContext, ProxyGuardConfig, RateLimitOptions } from '@spfn/core/middleware';
 import { SafeFetchPolicy } from '@spfn/core/security';
-import { c as JobRouter, e as BossOptions } from '../boss-D16fO2oG.js';
-import { b as EventRouterDef, E as EventDef } from '../token-manager-BT5EnUAR.js';
-import { d as SSEHandlerConfig, e as SSEAuthConfig } from '../types-ZQODsBft.js';
-import { W as WSRouterDef, f as WSHandlerConfig, e as WSMessageHandlers, g as WSAuthConfig } from '../types-2AbaW4Ie.js';
+import { c as JobRouter, f as BossOptions } from '../boss-BiDCbbAQ.js';
+import { E as EventRouterDef, a as EventDef } from '../router-CysBmgv3.js';
+import { d as SSEHandlerConfig, e as SSEAuthConfig } from '../types-B8zAxFsE.js';
+import { W as WSRouterDef, f as WSHandlerConfig, e as WSMessageHandlers, g as WSAuthConfig } from '../types-W4u_S0lF.js';
 import { DatabaseProvider, MigrationStatus, MigrationStatusDb } from '@spfn/core/db';
-import '@sinclair/typebox';
+import * as _sinclair_typebox from '@sinclair/typebox';
+import { Static } from '@sinclair/typebox';
+import { R as RouteDef } from '../route-builder-DRW-MSCJ.js';
+import { a as EnvRegistry } from '../registry-C2KQCh0m.js';
 import 'pg-boss';
+import '../token-manager-Ckjt2-qq.js';
+import '../define-middleware-CVKgqo8S.js';
+import 'hono/utils/http-status';
+import '../route/types.js';
 
 /**
  * @deprecated Use `loadEnv` from '@spfn/core/env/loader' instead.
@@ -22,6 +29,33 @@ import 'pg-boss';
  */
 declare function loadEnvFiles(): void;
 
+/** Stable operation identity used by separately deployed clients. */
+declare const CORE_TIME_OPERATION_ID = "core.time";
+/**
+ * Closed response shape for the server-time wire capability.
+ *
+ * Millisecond timestamps use integers throughout SPFN's external contracts.
+ */
+declare const ServerTimeResponseSchema: _sinclair_typebox.TObject<{
+    serverTimeMillis: _sinclair_typebox.TInteger;
+}>;
+type ServerTimeResponse = Static<typeof ServerTimeResponseSchema>;
+/** Injectable source of Unix epoch milliseconds. */
+interface ServerClock {
+    now(): number;
+}
+/**
+ * Build the route from a clock so tests and alternate runtimes can supply the
+ * epoch source without replacing global time.
+ */
+declare function createCoreTimeRoute(clock?: ServerClock): RouteDef<{}, {}, {
+    serverTimeMillis: number;
+}>;
+/** The production route and the public wire-contract source of truth. */
+declare const CORE_TIME_ROUTE: RouteDef<{}, {}, {
+    serverTimeMillis: number;
+}>;
+
 /**
  * Workflow router interface for @spfn/core integration
  *
@@ -202,6 +236,8 @@ interface ServerConfig {
      * Jobs defined with job()...handler() style
      * Uses pg-boss for PostgreSQL-based job queue
      *
+     * Merged across every `.jobs()` call, so this holds all of them.
+     *
      * @example
      * ```typescript
      * import { job, defineJobRouter } from '@spfn/core/job';
@@ -454,7 +490,9 @@ interface ServerConfig {
     };
     /**
      * Health check endpoint configuration
-     * Provides monitoring endpoints for Kubernetes probes and load balancers
+     *
+     * The endpoint answers at `/_core/health`, which no app route can take from
+     * it. Point Kubernetes probes and load balancers there.
      */
     healthCheck?: {
         /**
@@ -464,9 +502,19 @@ interface ServerConfig {
          */
         enabled?: boolean;
         /**
-         * Health check endpoint path
-         * @default '/health'
-         * @env HEALTH_CHECK_PATH
+         * An additional path to answer on, for a deployment whose probe path is
+         * fixed somewhere you cannot change it.
+         *
+         * BREAKING (@spfn/core 0.4): unset, the endpoint answers at
+         * `/_core/health` and nowhere else. It used to default to `/health` and
+         * swallow any app route declared there. `/health` now belongs to your
+         * app; set this to `'/health'` to have the built-in answer there again.
+         *
+         * The path is registered before app routes, so an app route on the same
+         * path will not run and the server says so at boot.
+         *
+         * @default undefined — `/_core/health` only
+         * @example '/health'
          */
         path?: string;
         /**
@@ -477,6 +525,15 @@ interface ServerConfig {
          */
         detailed?: boolean;
     };
+    /**
+     * Server-time capability dependencies.
+     *
+     * The endpoint is always enabled at `GET /_core/time`. Supplying a clock is
+     * primarily a deterministic test seam; production defaults to `Date.now()`.
+     */
+    serverTime?: {
+        clock?: ServerClock;
+    };
     /**
      * Migration boot gate
      *
@@ -498,20 +555,55 @@ interface ServerConfig {
          */
         allowPending?: boolean;
     };
+    /**
+     * Environment boot check
+     *
+     * Before serving, the server validates every variable of `@spfn/core`'s
+     * registry and of the registries listed here: a required variable must be
+     * set, and a set variable must pass its `validator`. On failure it logs
+     * each key with the reason — never a value — and refuses to start.
+     * `SKIP_ENV_VALIDATION` does not skip this check.
+     *
+     * @example
+     * ```typescript
+     * // src/server/config/env.config.ts
+     * export const envSchema = defineEnvSchema({ ... });
+     * export const envRegistry = createEnvRegistry(envSchema);
+     * export const env = envRegistry.validate();
+     *
+     * // src/server/server.config.ts
+     * export default defineServerConfig()
+     *     .env({ registries: [envRegistry] })
+     *     .build();
+     * ```
+     */
+    env?: {
+        /**
+         * Registries checked alongside `@spfn/core`'s: the app's own, and any
+         * package registry the app wants held to the same gate.
+         */
+        registries?: EnvRegistry<any>[];
+    };
     /**
      * Infrastructure initialization control
      * Controls automatic initialization of database and Redis
-     * @default Both enabled if credentials exist
+     *
+     * Both are initialized unless set to `false` — the credentials are not
+     * sniffed. A server that needs no database must say so, otherwise boot
+     * fails with `No database configuration found`. A component set to `false`
+     * is reported as `disabled` by the health endpoint and never degrades it.
+     *
+     * @default Both enabled
      */
     infrastructure?: {
         /**
          * Enable/disable automatic database initialization
-         * @default true if DATABASE_URL exists
+         * @default true
          */
         database?: boolean;
         /**
          * Enable/disable automatic Redis initialization
-         * @default true if REDIS_URL exists
+         * @default true
          */
         redis?: boolean;
     };
@@ -710,6 +802,43 @@ declare module 'hono' {
  */
 declare function createServer(config?: ServerConfig): Promise<Hono>;
 
+/**
+ * The paths `@spfn/core` registers for itself.
+ *
+ * Its own module because both `create-server.ts` (which registers them) and
+ * `helpers.ts` (which reports them in the startup banner) need them, and
+ * `create-server.ts` already imports `helpers.ts` — putting them in either file
+ * would close a cycle, which `pnpm check:circular` fails the build on.
+ *
+ * @module server/namespace
+ */
+/**
+ * The path prefix `@spfn/core` registers its own endpoints under.
+ *
+ * An app declaring a route in here is declaring something it does not own, and
+ * the route will not run — core's endpoints are registered before app routes.
+ * `@spfn/auth` (`/_auth/`) and ops routes (`/_ops/`) follow the same convention,
+ * and neither has ever had a shadowing defect.
+ */
+declare const CORE_NAMESPACE = "/_core";
+/**
+ * Where the built-in health endpoint always answers.
+ *
+ * Point a readiness probe, a Dockerfile `HEALTHCHECK` or an uptime monitor here
+ * rather than at `/health`: no app route can claim this path, so the answer does
+ * not depend on what the app happens to declare. A probe's path is fixed in
+ * places this repository cannot change — a GitOps manifest, a Dockerfile, a load
+ * balancer console — and a version bump migrates none of them.
+ */
+declare const CORE_HEALTH_PATH = "/_core/health";
+/**
+ * Where clients obtain the server's current Unix epoch in milliseconds.
+ *
+ * This endpoint is registered before application routes and application auth
+ * middleware so a client can call it before it has a proof or session.
+ */
+declare const CORE_TIME_PATH = "/_core/time";
+
 /**
  * Start SPFN Server
  *
@@ -720,6 +849,8 @@ declare function createServer(config?: ServerConfig): Promise<Hono>;
  * Start SPFN server
  *
  * Automatically loads server.config.ts if exists
+ * Validates the environment (core's registry + `config.env.registries`) and
+ * exits with code 1 when a variable is missing or invalid
  * Automatically initializes Database and Redis from environment
  * Sets up graceful shutdown handlers for SIGTERM and SIGINT
  *
@@ -863,6 +994,9 @@ declare function getShutdownManager(): ShutdownManager;
  *   - does NOT run seed/RBAC provisioning per cold start — that moves to a
  *     deploy-time step, see {@link provisionInfrastructure}.
  *
+ * Like {@link startServer}, it runs the environment boot check before building
+ * the app; a failure rejects the returned promise instead of exiting.
+ *
  * `startServer()` / `spfn start` (the always-on path) is unchanged by this module.
  */
 
@@ -1049,6 +1183,20 @@ declare class ServerConfigBuilder {
     /**
      * Register background jobs router
      *
+     * May be called once per domain router: repeated calls **merge** into one
+     * router, the way `.routes()` composes. Calling it several times used to
+     * keep only the last router and register nothing else, without warning.
+     *
+     * The pg-boss `config` is per server, so pass it on one call only.
+     *
+     * Two names can collide, and both fail loudly:
+     * - a router **key** present in two calls throws here, at config time;
+     * - two jobs sharing a **`job.name`** (the pg-boss queue name) throw in
+     *   `registerJobs()` at boot, before any queue or worker is created.
+     *
+     * @throws if a router key was already registered by an earlier call
+     * @throws if `config` is given when an earlier call already gave one
+     *
      * @example
      * ```typescript
      * import { job, defineJobRouter } from '@spfn/core/job';
@@ -1061,7 +1209,8 @@ declare class ServerConfigBuilder {
      *
      * export default defineServerConfig()
      *   .routes(appRouter)
-     *   .jobs(jobRouter)
+     *   .jobs(jobRouter, { clearOnStart: isDev })   // config on one call only
+     *   .jobs(billingJobRouter)                     // merged, not replaced
      *   .build();
      * ```
      */
@@ -1149,6 +1298,12 @@ declare class ServerConfigBuilder {
      * Configure health check endpoint
      */
     healthCheck(healthCheck: ServerConfig['healthCheck']): this;
+    /**
+     * Supply the clock used by the built-in `GET /_core/time` capability.
+     * Production servers normally keep the default `Date.now()` clock; this is
+     * exposed so tests can assert an exact wire value without replacing globals.
+     */
+    serverTime(serverTime: ServerConfig['serverTime']): this;
     /**
      * Configure infrastructure initialization
      */
@@ -1165,6 +1320,22 @@ declare class ServerConfigBuilder {
      * ```
      */
     migrations(migrations: ServerConfig['migrations']): this;
+    /**
+     * Hand the app's env registries to the boot check
+     *
+     * `@spfn/core`'s own registry is always checked; the registries given here
+     * are checked with it, before the server listens.
+     *
+     * @example
+     * ```typescript
+     * import { envRegistry } from '@/server/config/env.config';
+     *
+     * export default defineServerConfig()
+     *     .env({ registries: [envRegistry] })
+     *     .build();
+     * ```
+     */
+    env(env: ServerConfig['env']): this;
     /**
      * Register workflow router for workflow orchestration
      *
@@ -1225,4 +1396,4 @@ declare class ServerConfigBuilder {
  */
 declare function defineServerConfig(): ServerConfigBuilder;
 
-export { type AppFactory, type MigrationSnapshot, PendingMigrationsError, type ServerConfig, type ServerInstance, type ShutdownHookOptions, createServer, createServerlessApp, defineServerConfig, getMigrationSnapshot, getShutdownManager, loadEnvFiles, provisionInfrastructure, resetMigrationSnapshot, resetServerlessApp, startServer };
+export { type AppFactory, CORE_HEALTH_PATH, CORE_NAMESPACE, CORE_TIME_OPERATION_ID, CORE_TIME_PATH, CORE_TIME_ROUTE, type MigrationSnapshot, PendingMigrationsError, type ServerClock, type ServerConfig, type ServerInstance, type ServerTimeResponse, ServerTimeResponseSchema, type ShutdownHookOptions, createCoreTimeRoute, createServer, createServerlessApp, defineServerConfig, getMigrationSnapshot, getShutdownManager, loadEnvFiles, provisionInfrastructure, resetMigrationSnapshot, resetServerlessApp, startServer };