@statorjs/stator 2.9.0 → 2.10.0-next.0

package/src/server/banner.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs'
 import { networkInterfaces } from 'node:os'
 import { logger } from './logger.ts'
+import { type ClosableServer, drainAndClose } from './shutdown.ts'
 
 /**
  * Human-facing startup/exit output for the DEV plane. Production keeps
@@ -76,11 +77,18 @@ export function printDevBanner(info: {
  * "did it start, and where" is the one thing an operator always wants, distinct
  * from the per-request logs that `warn` intentionally suppresses.
  */
-export function printStartupNotice(info: { port: number; machines: number; routes: number }): void {
+export function printStartupNotice(info: {
+  port: number
+  machines: number
+  routes: number
+  /** Whether state survives a restart. Always shown: a deploy log should not
+   *  have to infer the persistence posture from the absence of a warning. */
+  persistence?: string
+}): void {
   const v = statorVersion()
-  const inv = `${info.machines} machine${info.machines === 1 ? '' : 's'} · ${info.routes} route${
-    info.routes === 1 ? '' : 's'
-  }`
+  const inv = `${info.machines} machine${info.machines === 1 ? '' : 's'} · ${
+    info.routes
+  } route${info.routes === 1 ? '' : 's'}${info.persistence ? ` · ${info.persistence}` : ''}`
   process.stdout.write(
     `  ${c.copper(c.bold('stator'))}${v ? c.dim(` v${v}`) : ''} ${c.dim('·')} ${c.cyan(
       `http://localhost:${info.port}/`,
@@ -89,26 +97,32 @@ export function printStartupNotice(info: { port: number; machines: number; route
 }
 
 /**
- * Exit a server process like a well-mannered CLI: first signal closes
- * cleanly and exits 0 (Ctrl+C is a normal action, not a failure — without
- * this, the process dies 130 and pnpm prints an ELIFECYCLE error banner);
- * a second signal force-quits for anything that hangs in close().
+ * Exit a server process like a well-mannered CLI: first signal drains and exits
+ * 0 (Ctrl+C is a normal action, not a failure — without this, the process dies
+ * 130 and pnpm prints an ELIFECYCLE error banner); a second signal force-quits.
+ *
+ * The drain itself is `drainAndClose` — the server stops accepting, `teardown`
+ * runs (boot teardown, watchers), live connections are hung up, and in-flight
+ * requests get a bounded deadline. Waiting on `server.close()` alone would hang
+ * forever with a single live page open.
  */
-export function installGracefulShutdown(close: () => Promise<void> | void, quiet = false): void {
+export function installGracefulShutdown(
+  server: ClosableServer,
+  opts: { teardown?: () => Promise<void> | void; quiet?: boolean } = {},
+): void {
   let closing = false
-  const handler = (signal: NodeJS.Signals) => {
+  const handler = () => {
     if (closing) process.exit(130)
     closing = true
-    if (!quiet) process.stdout.write(`\n${c.dim('  stopping…')}\n`)
+    if (!opts.quiet) process.stdout.write(`\n${c.dim('  stopping…')}\n`)
     void (async () => {
       try {
-        await close()
+        await drainAndClose(server, { teardown: opts.teardown })
       } catch (err) {
         logger.warn({ err: String(err) }, 'error during shutdown')
       }
       process.exit(0)
     })()
-    void signal
   }
   process.on('SIGINT', handler)
   process.on('SIGTERM', handler)

package/src/server/create-app.ts

@@ -18,6 +18,7 @@ import { discoverMiddleware } from './middleware.ts'
 import { discoverRoutes } from './route-discovery.ts'
 import { setSessionSameSite } from './session.ts'
 import { InMemoryStore, type Store } from './store.ts'
+import { persistencePosture } from './store-intent.ts'
 
 export interface CreateAppConfig extends DeprecatedFlatConfig {
   machinesDir: string
@@ -169,7 +170,23 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
       return new Promise((resolveFn) => {
         const server = serve({ fetch: app.fetch, port, hostname: resolved.host }, async () => {
           // Always-on (level-independent) so `warn` prod still confirms boot.
-          printStartupNotice({ port, machines: defs.length, routes: routes.length })
+          // Persistence posture in the notice, and a warning for anything
+          // actually at risk. Silence about in-memory storage is the defect
+          // this closes: the app runs, looks healthy, and loses every session
+          // on restart.
+          const posture = persistencePosture({
+            session: sessionStore,
+            app: store.appStore,
+            machines: defs,
+            production: process.env.NODE_ENV === 'production',
+          })
+          printStartupNotice({
+            port,
+            machines: defs.length,
+            routes: routes.length,
+            persistence: posture.label,
+          })
+          for (const warning of posture.warnings) logger.warn({}, `stator: ${warning}`)
           // Run boot.ts once the server is up — its long-lived work (a poll, a
           // subscription) starts here, not during createApp, so tests that only
           // `app.fetch` never trigger it.
@@ -183,11 +200,9 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
             },
           })
           // Ctrl+C / SIGTERM (deploy rollover) exits 0, not 130 — quiet in prod.
-          // Boot teardown runs first (unsubscribe/clear timers), then the server.
-          installGracefulShutdown(async () => {
-            if (teardown) await teardown()
-            await new Promise<void>((done) => server.close(() => done()))
-          }, true)
+          // The server stops accepting before boot teardown runs, so nothing
+          // new arrives while its sources are being unsubscribed.
+          installGracefulShutdown(server, { teardown, quiet: true })
           resolveFn()
         })
         // Production is strict about its port (a collision is a deploy

package/src/server/dev-native.ts

@@ -589,10 +589,11 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
                   cors: resolved.cors,
                 },
               })
-              installGracefulShutdown(async () => {
-                if (teardown) await teardown()
-                await watcher.close()
-                await new Promise<void>((done) => server.close(() => done()))
+              installGracefulShutdown(server, {
+                teardown: async () => {
+                  if (teardown) await teardown()
+                  await watcher.close()
+                },
               })
               resolveFn()
             })

package/src/server/dev-vite.ts

@@ -306,10 +306,11 @@ export async function createViteDevApp(config: DevAppConfig): Promise<DevApp> {
                   cors: resolved.cors,
                 },
               })
-              installGracefulShutdown(async () => {
-                if (teardown) await teardown()
-                await vite.close()
-                await new Promise<void>((done) => server.close(() => done()))
+              installGracefulShutdown(server, {
+                teardown: async () => {
+                  if (teardown) await teardown()
+                  await vite.close()
+                },
               })
               resolveFn()
             })

package/src/server/index.ts

@@ -136,3 +136,5 @@ export {
 } from './sse.ts'
 export type { Store } from './store.ts'
 export { InMemoryStore } from './store.ts'
+export type { StoreFromEnvOptions } from './store-intent.ts'
+export { appStore, sessionStore } from './store-intent.ts'

package/src/server/shutdown.ts

@@ -0,0 +1,127 @@
+import { scopedLogger } from './logger.ts'
+import { closeLiveConnections } from './sse.ts'
+
+const log = scopedLogger('shutdown')
+
+/**
+ * Draining a Stator process, which is not the same as closing its server.
+ *
+ * `server.close()` stops accepting new connections and then resolves only when
+ * every existing connection has ended — so it can never be the gate for an app
+ * with live routes: an SSE response is a single request that lasts as long as
+ * the page is open. Waiting on it means the process hangs until the platform
+ * loses patience (systemd `TimeoutStopSec`, Kubernetes
+ * `terminationGracePeriodSeconds`, `docker stop`) and SIGKILLs it, turning an
+ * ordinary deploy rollover into a 90-second failed stop.
+ *
+ * So long-lived streams are HUNG UP, never waited on — the same conclusion Go's
+ * `http.Server.Shutdown` documents ("does not attempt to close nor wait for
+ * hijacked connections... the caller should separately notify such long-lived
+ * connections") and every Node graceful-shutdown library reaches. The deadline
+ * that remains covers real request work, which is why it is short by default.
+ *
+ * Dropping a live channel costs a re-render, not a fact: session state is in the
+ * Store, `after` timers re-arm on hydration, and a reconnecting page re-syncs
+ * from the server's baseline (or reloads, if it comes back to a newer build via
+ * the build-id handshake).
+ */
+
+/** Deadline for in-flight request work once the streams are hung up. Short on
+ *  purpose: closing live connections is immediate, so this only ever covers
+ *  real requests, and it must stay well under the platform's own kill grace
+ *  (`docker stop` allows 10s). */
+const DEFAULT_TIMEOUT_MS = 5_000
+
+/** `STATOR_SHUTDOWN_TIMEOUT_MS`, or the default. An unparseable value warns and
+ *  falls back rather than shortening the drain to zero. */
+export function shutdownTimeoutMs(): number {
+  const raw = process.env.STATOR_SHUTDOWN_TIMEOUT_MS
+  if (raw === undefined || raw === '') return DEFAULT_TIMEOUT_MS
+  const ms = Number(raw)
+  if (!Number.isFinite(ms) || ms < 0) {
+    log.warn({ value: raw }, 'ignoring invalid STATOR_SHUTDOWN_TIMEOUT_MS')
+    return DEFAULT_TIMEOUT_MS
+  }
+  return ms
+}
+
+/** What the drain needs of a listening server — structurally satisfied by
+ *  `node:http`'s `Server` and by `@hono/node-server`'s `serve()` return.
+ *  `closeIdleConnections`/`closeAllConnections` are Node ≥18.2; optional so a
+ *  non-http server (or a test double) still drains. */
+export interface ClosableServer {
+  close(callback?: (err?: Error) => void): unknown
+  closeIdleConnections?: () => void
+  closeAllConnections?: () => void
+}
+
+export interface DrainResult {
+  /** Live (SSE) connections hung up by the drain. */
+  connections: number
+  /** True when the deadline expired and the remaining sockets were destroyed. */
+  forced: boolean
+}
+
+/**
+ * Stop accepting, tear down inbound sources, hang up live connections, and wait
+ * for in-flight requests up to a deadline — then destroy whatever is left.
+ * Never exits the process: the signal handler owns that, and tests own this.
+ */
+export async function drainAndClose(
+  server: ClosableServer,
+  opts: { teardown?: () => Promise<void> | void; timeoutMs?: number } = {},
+): Promise<DrainResult> {
+  const timeoutMs = opts.timeoutMs ?? shutdownTimeoutMs()
+
+  // Stop accepting FIRST, so nothing new arrives while sources are torn down.
+  const closed = new Promise<void>((done) => server.close(() => done()))
+
+  let connections = 0
+  const drain = (async () => {
+    // Inbound sources off before the streams they feed: a boot.ts poll or
+    // subscription can raise events, and a dev watcher can rebuild, so both
+    // stop before anything is hung up. A teardown that throws must not keep the
+    // sockets open — log it and carry on closing.
+    if (opts.teardown) {
+      try {
+        await opts.teardown()
+      } catch (err) {
+        log.warn({ err: String(err) }, 'teardown failed during shutdown')
+      }
+    }
+    // The reason close() can complete at all.
+    connections = closeLiveConnections()
+    // Then reap keep-alive sockets parked between requests — on a tick, not
+    // once. A hung-up stream's socket only becomes idle a moment later, and
+    // until something closes it, `close()` stays pending for as long as the
+    // CLIENT's keep-alive timeout (undici's is 4s) — measured, and the whole
+    // reason a one-shot call here isn't enough. A socket with a request in
+    // flight is never idle, so this never cuts real work short.
+    server.closeIdleConnections?.()
+    const reaper = setInterval(() => server.closeIdleConnections?.(), 50)
+    reaper.unref?.()
+    try {
+      await closed
+    } finally {
+      clearInterval(reaper)
+    }
+  })()
+
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const expired = new Promise<'timeout'>((done) => {
+    timer = setTimeout(() => done('timeout'), timeoutMs)
+    timer.unref?.()
+  })
+  const outcome = await Promise.race([drain.then(() => 'drained' as const), expired])
+  clearTimeout(timer)
+
+  if (outcome === 'timeout') {
+    // Real request work (or a wedged teardown) outlasted the deadline. Destroy
+    // what's left rather than hand the process to the platform's SIGKILL.
+    server.closeAllConnections?.()
+    log.warn({ timeoutMs }, 'shutdown deadline expired — remaining connections destroyed')
+    return { connections, forced: true }
+  }
+  log.debug({ connections }, 'drained')
+  return { connections, forced: false }
+}

package/src/server/sse.ts

@@ -107,6 +107,21 @@ export function activeConnectionCount(): number {
   return connections.size
 }
 
+/**
+ * Hang up every open connection — the shutdown path. A live response never ends
+ * on its own, so `server.close()` cannot complete until these do; see
+ * `shutdown.ts` for why they are closed rather than waited on. Returns how many
+ * were open. Each handler's own `finally` unregisters again, harmlessly.
+ */
+export function closeLiveConnections(): number {
+  const open = [...connections.values()]
+  for (const conn of open) {
+    unregisterConnection(conn.id)
+    conn.close?.()
+  }
+  return open.length
+}
+
 /**
  * After a state-changing dispatch settles, iterate every open connection
  * whose route's `reads:` intersects `touched`, recompute against that

package/src/server/store-intent.ts

@@ -0,0 +1,175 @@
+import type { AppStore } from './app-store.ts'
+import { InMemoryAppStore } from './app-store.ts'
+import { CachedStore, type CachedStoreOptions } from './cached-store.ts'
+import { RedisAppStore, RedisStore } from './redis-store.ts'
+import { InMemoryStore, type Store } from './store.ts'
+
+/**
+ * Picking a store from the environment, without the silent downgrade.
+ *
+ * Every app that keeps state in Redis writes the same conditional: a URL from
+ * the environment, a durable store when it's there, in-memory when it isn't.
+ * That fallback is right for dev and for CI — a build machine has no business
+ * holding production credentials — and wrong in exactly one place, production,
+ * where it means the app runs, looks healthy, and quietly loses every session
+ * on restart. Written in userland the framework cannot tell that outcome from a
+ * deliberate choice, so it cannot say anything about it.
+ *
+ * Moving the conditional in here changes only that: the returned store carries
+ * whether in-memory was *chosen* or *fallen back to*, so startup can be silent
+ * in development and loud in production, naming the empty variable instead of
+ * reporting a generic posture.
+ *
+ * The environment stays in charge. A URL present means durable, wherever it
+ * comes from — so pointing CI at a test Redis is nothing special, it is just
+ * the variable being set. An empty or whitespace-only value counts as absent,
+ * which is what a CI system that defines every variable as `""` produces.
+ */
+
+/** Recorded on a fallback store so startup can tell it from a deliberate one.
+ *  Non-enumerable and internal: the value still satisfies `Store` exactly. */
+const INTENT = Symbol.for('stator.store.intent')
+
+interface StoreIntent {
+  /** What the app asked for. */
+  wanted: 'durable'
+  /** The config field that was empty, for the message. */
+  from: string
+}
+
+function mark<T extends object>(store: T, intent: StoreIntent): T {
+  Object.defineProperty(store, INTENT, { value: intent, enumerable: false })
+  return store
+}
+
+/** The recorded intent of a store, if it was built by these helpers. */
+export function storeIntent(store: unknown): StoreIntent | undefined {
+  if (store === null || typeof store !== 'object') return undefined
+  return (store as Record<symbol, StoreIntent | undefined>)[INTENT]
+}
+
+/** True for the framework's own in-memory adapters — the ones that do not
+ *  survive a restart. A store the app supplied is assumed durable; the
+ *  framework has no way to ask, and no business guessing. */
+export function isEphemeral(store: unknown): boolean {
+  return store instanceof InMemoryStore || store instanceof InMemoryAppStore
+}
+
+const blank = (url: string | undefined): boolean => url === undefined || url.trim() === ''
+
+export interface StoreFromEnvOptions {
+  /** Redis connection string, typically `process.env.REDIS_URL`. Absent, empty
+   *  or whitespace-only selects in-memory — normal in dev and CI, reported at
+   *  startup in production. */
+  redisUrl?: string
+  /** Wrap Redis in a write-through memory cache. Off by default: caching is a
+   *  performance decision, and this helper's job is the durable-or-not one. */
+  cache?: CachedStoreOptions | true
+  /** Key prefix, passed through to the Redis adapter. */
+  keyPrefix?: string
+  /** Name used in the startup report when the URL is empty. Default `REDIS_URL`. */
+  envName?: string
+}
+
+/**
+ * Session-machine storage from the environment: Redis when a URL is set,
+ * in-memory otherwise.
+ *
+ *   persistence: { session: sessionStore({ redisUrl: process.env.REDIS_URL }) }
+ *
+ * Call it with nothing (or omit `persistence.session` entirely) to choose
+ * in-memory deliberately — that is a real choice and is never reported.
+ */
+export function sessionStore(opts: StoreFromEnvOptions = {}): Store {
+  if (blank(opts.redisUrl)) {
+    // In-memory either way, but for two different reasons. Passing the key at
+    // all — `redisUrl: process.env.REDIS_URL` — says the app wants durability
+    // from the environment, so an empty value is worth reporting in production.
+    // Passing no key says in-memory was the choice, which is never reported.
+    return 'redisUrl' in opts
+      ? mark(new InMemoryStore(), { wanted: 'durable', from: opts.envName ?? 'REDIS_URL' })
+      : new InMemoryStore()
+  }
+  const redis = opts.keyPrefix
+    ? new RedisStore(opts.redisUrl as string, opts.keyPrefix)
+    : new RedisStore(opts.redisUrl as string)
+  if (!opts.cache) return redis
+  return new CachedStore(redis, opts.cache === true ? {} : opts.cache)
+}
+
+/**
+ * App-machine storage (`persist: true`) from the environment. Same rule as
+ * `sessionStore`.
+ */
+export function appStore(opts: StoreFromEnvOptions = {}): AppStore {
+  if (blank(opts.redisUrl)) {
+    return 'redisUrl' in opts
+      ? mark(new InMemoryAppStore(), { wanted: 'durable', from: opts.envName ?? 'REDIS_URL' })
+      : new InMemoryAppStore()
+  }
+  return opts.keyPrefix
+    ? new RedisAppStore(opts.redisUrl as string, opts.keyPrefix)
+    : new RedisAppStore(opts.redisUrl as string)
+}
+
+/** One machine's persistence-relevant shape. */
+export interface MachinePersistence {
+  lifecycle: string
+  persist: boolean
+}
+
+/**
+ * What to say about persistence at startup. The posture goes in the notice —
+ * printed at every level, so a deploy log always states whether state survives
+ * a restart — and anything worth alerting on comes back as a warning.
+ *
+ * Warnings fire in production only, and only when something is actually at
+ * risk: an app with no session machines has no session state to lose, and an
+ * app that deliberately chose in-memory made a real choice. Nothing here ever
+ * refuses to start; persistent storage is assumed to be wanted, never required.
+ */
+export function persistencePosture(input: {
+  session: unknown
+  app: unknown
+  machines: readonly MachinePersistence[]
+  production: boolean
+}): { label: string; warnings: string[] } {
+  const name = (store: unknown): string =>
+    isEphemeral(store)
+      ? 'in-memory'
+      : ((store as { constructor?: { name?: string } })?.constructor?.name ?? 'custom')
+
+  const sessionMachines = input.machines.filter((m) => m.lifecycle === 'session').length
+  const persistedApp = input.machines.filter((m) => m.lifecycle === 'app' && m.persist).length
+
+  let label = `sessions ${name(input.session)}`
+  if (persistedApp > 0) label += ` · app ${name(input.app)}`
+
+  const warnings: string[] = []
+  if (input.production) {
+    const sessionIntent = storeIntent(input.session)
+    if (isEphemeral(input.session) && sessionIntent) {
+      // The app configured a durable store and the variable was empty — the
+      // one case the framework can name precisely.
+      warnings.push(
+        `${sessionIntent.from} is empty, so session state is in memory and will not survive a restart`,
+      )
+    } else if (isEphemeral(input.session) && sessionMachines > 0) {
+      warnings.push(
+        `no durable session store is configured, so the state of ${sessionMachines} session machine${
+          sessionMachines === 1 ? '' : 's'
+        } will not survive a restart`,
+      )
+    }
+
+    const appIntent = storeIntent(input.app)
+    if (isEphemeral(input.app) && persistedApp > 0) {
+      warnings.push(
+        appIntent
+          ? `${appIntent.from} is empty, so ${persistedApp} persisted app machine${persistedApp === 1 ? '' : 's'} will not survive a restart`
+          : `no durable app store is configured, so ${persistedApp} persisted app machine${persistedApp === 1 ? '' : 's'} will not survive a restart`,
+      )
+    }
+  }
+  return { label, warnings }
+}