@c9up/ream 0.2.15 → 0.2.17

package/dist/session/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/session/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAaH,MAAM,UAAU,YAAY,CAAC,MAA0B;IACrD,OAAO,MAAM,CAAA;AACf,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/ream",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "Ream — Rust-powered Node.js application framework",
   "license": "MIT",
   "type": "module",
@@ -187,6 +187,14 @@
     "./swcrc.app.json": "./swcrc.app.json",
     "./tsconfig.package.json": "./tsconfig.package.json",
     "./tsconfig.client.json": "./tsconfig.client.json",
+    "./session/config": {
+      "types": "./dist/session/config.d.ts",
+      "import": "./dist/session/config.js"
+    },
+    "./bodyparser/config": {
+      "types": "./dist/bodyparser/config.d.ts",
+      "import": "./dist/bodyparser/config.js"
+    },
     "./session_middleware": {
       "types": "./dist/session/SessionMiddleware.d.ts",
       "import": "./dist/session/SessionMiddleware.js"
@@ -231,6 +239,7 @@
     "@biomejs/biome": "2.5.12",
     "@c9up/comet": "^0.1.0",
     "@types/node": "^22.19.15",
+    "@vitest/coverage-v8": "^4.1.6",
     "mime-db": "^1.54.0",
     "mime-types": "^3.0.2",
     "typescript": "^6.0.2",
@@ -254,7 +263,7 @@
     "build:napi": "pnpm build:rust && pnpm build:napi-types && node scripts/copy-napi.mjs",
     "test": "vitest run",
     "test:rust": "cargo test --all",
-    "lint": "biome check src/",
+    "lint": "biome check src/ tests/",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
     "typecheck:tests": "tsc --noEmit -p tsconfig.tests.json"

package/src/Application.ts

@@ -56,11 +56,26 @@ export type ApplicationState =
   | 'terminating'
   | 'terminated'
 
+/**
+ * What the application keeps of the rc file.
+ *
+ * Structurally a subset of `ReamrcConfig`, declared here rather than imported:
+ * that type lives in `Ignitor.ts`, which imports this module, and naming it
+ * from here would close the cycle. Only the keys something reads back through
+ * `app.rcFile` are spelt out; the rest rides along untouched.
+ */
+export interface ReamrcContents {
+  directories?: Partial<DirectoriesNode>
+  /** `app/modules/**` auto-loading — opt-in, and scoped to named files. */
+  modules?: { path?: string; autoload?: string[] }
+}
+
 export class Application implements AppContext {
   readonly container: Container
   readonly config: ConfigStore
   #appRoot?: URL
   #directories: DirectoriesNode = { ...defaultDirectories }
+  #rcFile: ReamrcContents = {}
   #providers: ProviderContract[] = []
   #booted = false
   #environment: AppEnvironment = 'unknown'
@@ -68,6 +83,10 @@ export class Application implements AppContext {
   #packageJsonRead = false
   #packageJsonCache: { name?: string; version?: string } | undefined
   #mode: ApplicationMode = 'run'
+  /** Hooks that run — in reverse — when `terminate()` begins. */
+  #terminatingHooks: Array<() => Promise<void> | void> = []
+  /** Re-entrancy guard: two signals must terminate the application once. */
+  #terminating = false
   #bootingHooks: Array<() => Promise<void> | void> = []
   #bootedHooks: Array<() => Promise<void> | void> = []
   #shutdownHooks: Array<() => Promise<void> | void> = []
@@ -161,14 +180,27 @@ export class Application implements AppContext {
     return this.#directories
   }
 
+  /**
+   * The parsed rc file (AdonisJS `app.rcFile`).
+   *
+   * Kept whole, not just the keys this class acts on. A console command has the
+   * application and nothing else, so anything it needs to explain itself — why
+   * `app/modules/**` loaded nothing, say — has to be reachable from here. Empty
+   * until `rcContents()` has run.
+   */
+  get rcFile(): ReamrcContents {
+    return this.#rcFile
+  }
+
   /**
    * Feed the loaded rc file to the application (AdonisJS `rcContents`).
    *
-   * Today it reads one key, `directories`, merged over the defaults; the rest
-   * of the rc file is consumed by the Ignitor and the CLI, which own providers,
-   * preloads, commands and test suites.
+   * `directories` is merged over the defaults; the rest is stored as-is and
+   * read back through {@link rcFile}. Providers, preloads, commands and test
+   * suites are still consumed by the Ignitor and the CLI, which own them.
    */
-  rcContents(value: { directories?: Partial<DirectoriesNode> }): this {
+  rcContents(value: ReamrcContents): this {
+    this.#rcFile = value
     if (value.directories) {
       // Skip the undefined entries a `Partial` may carry: spreading them would
       // blank a default rather than leave it alone.
@@ -576,12 +608,56 @@ export class Application implements AppContext {
   }
 
   /**
-   * Graceful shutdown — stop all providers and exit.
-   * Like AdonisJS app.terminate().
+   * Register a hook that runs when the application begins to terminate
+   * (AdonisJS `app.terminating`).
+   *
+   * This is how the HTTP server closes on a signal: whoever opened the socket
+   * registers a hook that closes it, and `terminate()` runs them in reverse —
+   * last opened, first closed. Upstream's HTTP process does exactly this.
+   */
+  terminating(callback: () => Promise<void> | void): void {
+    this.#terminatingHooks.push(callback)
+  }
+
+  /**
+   * Graceful shutdown (AdonisJS `app.terminate()`).
+   *
+   * Runs the `terminating` hooks in reverse, then shuts the providers down.
+   * Two things it deliberately does NOT do:
+   *
+   * - It does not close the HTTP server itself. Whoever opened the socket
+   *   registers a `terminating` hook for it; the application does not know
+   *   what a server is. Terminating without one used to skip the close, the
+   *   error boundary and the service locators entirely.
+   * - It does not call `process.exit()`. Exiting from here cut the shutdown
+   *   short whenever a second path was already draining the server — and the
+   *   documented signal wiring set up exactly that race. The process ends when
+   *   nothing is left holding the loop, which is what "graceful" means.
+   *
+   * Re-entrant calls are ignored, so a SIGTERM handler and a crash handler
+   * firing together terminate once.
    */
   async terminate(): Promise<void> {
-    await this.shutdown()
-    process.exit(0)
+    if (this.#terminating) return
+    this.#terminating = true
+    const errors: unknown[] = []
+    for (const hook of [...this.#terminatingHooks].reverse()) {
+      try {
+        await hook()
+      } catch (err) {
+        errors.push(err)
+      }
+    }
+    this.#terminatingHooks = []
+    try {
+      await this.shutdown()
+    } catch (err) {
+      errors.push(err)
+    }
+    if (errors.length === 1) throw errors[0]
+    if (errors.length > 1) {
+      throw new AggregateError(errors, 'Application.terminate() completed with errors')
+    }
   }
 
   // ─── Provider lifecycle ───────────────────────────────────
@@ -640,6 +716,11 @@ export class Application implements AppContext {
    * from closing their resources (DB pools, queues). Errors are aggregated.
    */
   async shutdown(): Promise<void> {
+    // Idempotent: `terminate()` runs the `terminating` hooks and one of them is
+    // the Ignitor's `stop()`, which shuts the application down on its way. The
+    // second pass must not call every provider's `shutdown()` again — a pool
+    // closed twice, a socket destroyed twice.
+    if (this.#state === 'terminated') return
     const errors: unknown[] = []
     this.#state = 'terminating'
 

package/src/Ignitor.ts

@@ -210,6 +210,15 @@ export interface HyperServerLike {
 }
 
 export interface IgnitorConfig {
+  /**
+   * Bind port. Falls back to `process.env.PORT`, then to `3000`. Prefer the
+   * environment: the fallback is read when the server binds, AFTER `booting()`
+   * has loaded `#start/env`, whereas a value passed here is fixed at
+   * construction — before `.env` has been read at all.
+   *
+   * It stays available because a test harness booting several applications in
+   * one process needs to hand each one an ephemeral port it has already picked.
+   */
   port?: number
   /**
    * Bind address of the HTTP server. Falls back to `process.env.HOST`, then to
@@ -690,12 +699,31 @@ export class Ignitor {
     this.#phase = 'started'
   }
 
+  /**
+   * Whether this process should bind an HTTP server.
+   *
+   * Not the same question as "is the environment 'web'". A test harness needs
+   * the HTTP surface — it passes a `serverFactory` precisely to get one — but
+   * it also needs to declare itself as `test`, because that is what an
+   * environment-scoped provider entry reads. Tying the two together forced a
+   * test bootstrap to call `httpServer()`, which set the environment to
+   * `'web'`, so `{ environment: ['web'] }` excluded nothing from a test run and
+   * a scheduled task fired in the middle of the suite.
+   *
+   * A test process that passes no factory still gets no server, and no error.
+   */
+  #servesHttp(): boolean {
+    const environment = this.#app.getEnvironment()
+    if (environment === 'web') return true
+    return environment === 'test' && this.#config.serverFactory !== undefined
+  }
+
   async #phaseReady(): Promise<void> {
     // Boot the Server (resolves lazy error handler etc.)
     await this.#server.boot()
 
-    // Start HTTP server if in web mode
-    if (this.#app.getEnvironment() === 'web' && this.#config.serverFactory) {
+    // Start HTTP server if this process serves one
+    if (this.#servesHttp() && this.#config.serverFactory) {
       // Build the HttpKernel with server middleware + router middleware.
       // The streaming backend is resolved lazily — the HyperServer is
       // created a few lines down, after the kernel — so the kernel
@@ -737,7 +765,18 @@ export class Ignitor {
         },
       })
 
-      const desiredPort = this.#config.port ?? 3000
+      // Read HERE, not at construction: `#start/env` runs in `booting()`, so a
+      // PORT living in `.env` does not exist in `process.env` until this point.
+      // Reading it early bound 3000 while every later reader — the boot banner
+      // included — saw 3007 and said so. Same lazy rule as `host` below.
+      const desiredPort = this.#config.port ?? Number(process.env.PORT || 3000)
+      if (!Number.isInteger(desiredPort) || desiredPort < 0 || desiredPort > 65535) {
+        throw new ReamError(
+          'E_IGNITOR_INVALID_PORT',
+          `PORT must be an integer between 0 and 65535, received '${process.env.PORT}'.`,
+          { hint: 'Set PORT in .env, or pass { port } to the Ignitor.' },
+        )
+      }
       // Port-scan fallback (+1..+19) is a DEV convenience only. In production
       // a silent drift to :3001 while the LB targets :3000 is an outage —
       // bind the configured port and let EADDRINUSE fail loudly. The probe
@@ -760,15 +799,24 @@ export class Ignitor {
       }
       await this.#_httpServer.listen()
 
+      // Whoever opened the socket closes it. `app.terminate()` runs the
+      // `terminating` hooks in reverse before shutting the providers down, so
+      // an application terminated by ANY path — this Ignitor's signal handler,
+      // an `app.listen('SIGTERM', () => app.terminate())` the entry point wired
+      // itself, a crash handler — drains the HTTP server. It used to skip it:
+      // `terminate()` shut the providers down and called `process.exit(0)`,
+      // which could win the race against a drain already in progress.
+      this.#app.terminating(() => this.stop())
+
       // Wire OS-signal graceful shutdown. Without it the process never closes
       // the HTTP server on SIGTERM/SIGINT, so live keep-alive / SSE sockets keep
       // the event loop alive — a `ream dev` restart or Ctrl+C ends in a watcher
       // force-kill, and an orchestrator's rolling deploy drops in-flight work.
-      // onShutdown = this.stop(), which closes the port (aborting connections),
-      // shuts providers down (DB pools), and releases the locators.
+      // It terminates the APPLICATION rather than stopping this Ignitor, so
+      // there is one authority however the shutdown was triggered.
       if (this.#config.gracefulShutdown !== false) {
         this.#shutdownHandle = installGracefulShutdown({
-          onShutdown: () => this.stop(),
+          onShutdown: () => this.#app.terminate(),
           logger: {
             info: (message) => this.#emitSystemInfo('GracefulShutdown', message, 'info'),
             error: (message) => this.#emitSystemInfo('GracefulShutdown', message, 'error'),

package/src/bodyparser/BodyParserMiddleware.ts

@@ -6,6 +6,7 @@
  * Configured via config/bodyparser.ts.
  */
 
+import { readModuleConfig } from '../config/moduleConfig.js'
 import { Exception } from '../http/Exception.js'
 import type { HttpContext } from '../http/HttpContext.js'
 import { hydrateMultipartPayload } from './MultipartFile.js'
@@ -98,7 +99,17 @@ const DEFAULT_CONFIG: ResolvedBodyParserConfig = {
 export default class BodyParserMiddleware {
   #config: ResolvedBodyParserConfig
 
-  constructor(config?: BodyParserConfig) {
+  constructor(explicitConfig: BodyParserConfig | undefined = undefined) {
+    // The default value is load-bearing: an OPTIONAL parameter still counts
+    // toward `Function.length`, and the container refuses to auto-construct a
+    // class that declares parameters it has no metadata for. A parameter with a
+    // default counts for nothing, which is what lets
+    // `router.use([() => import('…')])` build this middleware.
+    // Nothing is passed when the container builds this middleware from
+    // `router.use([() => import('@c9up/ream/bodyparser_middleware')])`, so the
+    // settings come from `config/bodyparser.ts` — the file this class's own
+    // documentation has always named.
+    const config = explicitConfig ?? readModuleConfig<BodyParserConfig>('bodyparser')
     assertNoEnabledFlag(config)
     this.#config = {
       allowedMethods: config?.allowedMethods ?? DEFAULT_CONFIG.allowedMethods,

package/src/bodyparser/config.ts

@@ -0,0 +1,18 @@
+/**
+ * `config/bodyparser.ts` — body-parsing limits and types, in the file the
+ * config loader reads (`config/<name>.ts` → `config.get('<name>')`).
+ *
+ * @example
+ *   // config/bodyparser.ts
+ *   import { defineConfig } from '@c9up/ream/bodyparser/config'
+ *
+ *   export default defineConfig({
+ *     multipart: { limit: '20mb' },
+ *   })
+ */
+
+import type { BodyParserConfig } from './BodyParserMiddleware.js'
+
+export function defineConfig(config: BodyParserConfig): BodyParserConfig {
+  return config
+}

package/src/commands/ScheduleList.ts

@@ -33,6 +33,9 @@ export default class ScheduleList extends BaseCommand {
     const tasks = scheduler.listTasks()
     if (tasks.length === 0) {
       this.logger.info('No scheduled tasks registered.')
+      for (const line of whyNothingWasFound(this.app.rcFile.modules)) {
+        this.logger.info(`  ${line}`)
+      }
       return
     }
 
@@ -64,3 +67,30 @@ export default class ScheduleList extends BaseCommand {
     }
   }
 }
+
+/**
+ * Why an empty list is empty.
+ *
+ * Discovery walks the IoC service registry, and a class the process never
+ * imported is not in it. `@Schedule` in `app/modules/**` therefore depends on
+ * the module auto-loader having imported the file, and that has two conditions
+ * a reader of the folder-structure guide would not expect. Saying "no tasks"
+ * and stopping leaves them to find both by reading the Ignitor.
+ */
+function whyNothingWasFound(modules: { path?: string; autoload?: string[] } | undefined): string[] {
+  if (modules?.path === undefined) {
+    return [
+      'A @Schedule is only found once something has imported the class that declares it.',
+      'reamrc.ts has no `modules.path`, so nothing under app/modules/ is auto-loaded at all.',
+      "Either add `modules: { path: './app/modules', autoload: ['routes', 'events'] }`,",
+      'or import the file from a preload — which is explicit, and works anywhere.',
+    ]
+  }
+  const autoload = modules.autoload ?? ['routes', 'events']
+  return [
+    'A @Schedule is only found once something has imported the class that declares it.',
+    `modules.autoload is [${autoload.map((f) => `'${f}'`).join(', ')}], so app/modules/<name>/<file>.ts`,
+    'is imported only under one of those names. Add the file name to that list,',
+    'or import it from a preload — which is explicit, and works anywhere.',
+  ]
+}

package/src/config/moduleConfig.ts

@@ -0,0 +1,24 @@
+/**
+ * Reading a module's own `config/<name>.ts` entry without demanding one.
+ *
+ * A middleware constructed by the container gets nothing passed to it — the
+ * resolver calls `make(Class)`, which is what makes `router.use([() =>
+ * import('…/session_middleware')])` possible. The configuration therefore has
+ * to come from the config store, the way it does everywhere else.
+ *
+ * The read is deliberately forgiving. The same classes are also constructed
+ * directly (`new BodyParserMiddleware()`) in tests and in embedding hosts that
+ * never boot an Application, and there the store does not exist. Throwing there
+ * would trade a working default for a crash.
+ */
+
+import { getApp } from '../services/app.js'
+
+export function readModuleConfig<T extends object>(key: string): T | undefined {
+  const store = getApp()?.config
+  if (store === undefined || !store.has(key)) return undefined
+  const value = store.get<T>(key)
+  // A config file exporting something that is not an object (a stray
+  // `export default 42`) is ignored rather than spread over the defaults.
+  return typeof value === 'object' && value !== null ? value : undefined
+}

package/src/console/cliui.ts

@@ -750,7 +750,8 @@ function pad(text: string, width: number): string {
   return text + ' '.repeat(Math.max(0, width - visibleWidth(text)))
 }
 
-function stripAnsi(text: string): string {
+/** Removes the SGR escape sequences `colors` writes, leaving the visible text. */
+export function stripAnsi(text: string): string {
   // biome-ignore lint/suspicious/noControlCharactersInRegex: matching ANSI escapes is the point
   return text.replace(/\u001B\[[0-9;]*m/g, '')
 }

package/src/index.ts

@@ -378,4 +378,4 @@ export {
   StatsTracker,
 } from './scheduler/index.js'
 
-export const VERSION = '0.2.15'
+export const VERSION = '0.2.17'

package/src/scheduler/ScheduleProvider.ts

@@ -10,7 +10,8 @@
  *     throws, tasks 1..N-1 registered in the same boot are unregistered
  *     before the error propagates, so the scheduler is never left in a
  *     half-registered state.
- *   - `start()` — launches the Rust tick loop.
+ *   - `ready()` — discovers the tasks `app/modules/**` declared, then
+ *     launches the Rust tick loop.
  *   - `shutdown()` — cancels the Rust tick loop.
  *
  * The registered callback resolves the service **at invocation time**
@@ -86,26 +87,35 @@ export class ScheduleProvider extends Provider {
   }
 
   /**
-   * Discovery runs at START, not at boot, and that is the whole point.
+   * The pass that matters runs at READY, and the ordering is the reason.
    *
-   * `app/modules/**` is auto-loaded during the start phase — after every
-   * provider has booted. A `@Service()` carrying `@Schedule` there, which is
-   * where one naturally lives, was therefore registered into the service
-   * registry AFTER this had already read it. The task was never registered,
-   * and nothing said so: no error, no warning, the application started
-   * normally and the task simply never fired.
+   * A `@Service()` carrying `@Schedule` naturally lives in `app/modules/**`,
+   * which the application auto-loads at the END of the start phase — after
+   * every provider's `start()`. Discovering in `start()` therefore read the
+   * service registry before the modules had put anything in it: the task was
+   * never registered, and nothing said so. No error, no warning, the
+   * application started normally and the task simply never fired. `ready()`
+   * runs after the autoload, which is what makes the second pass real.
    *
-   * Reading the registry once the modules are in place is what fixes it. A
-   * service declared anywhere earlier — a provider, a preload — is in the
-   * registry by then too, so nothing is lost by waiting.
+   * The earlier passes are kept because they cost nothing and shorten the gap:
+   * a service declared by a provider or a preload is registered as soon as it
+   * is seen. `#discover()` is idempotent, so a task found twice is registered
+   * once.
    */
   override async boot(): Promise<void> {
     // Anything already in the registry — declared by a provider, or imported
-    // by one. The rest is caught at start().
+    // by one. The rest is caught later.
     this.#discover()
   }
 
   override async start(): Promise<void> {
+    // Preloads have not run yet either; this catches whatever the boot phase
+    // added. The ticker deliberately does NOT start here.
+    this.#discover()
+  }
+
+  override async ready(): Promise<void> {
+    // The pass after `app/modules/**`.
     this.#discover()
     if (activeProvider !== undefined && activeProvider !== this) {
       // A previous app's scheduler is still running — stop it before this one

package/src/session/SessionMiddleware.ts

@@ -6,9 +6,11 @@
  */
 
 import { randomBytes } from 'node:crypto'
+import { readModuleConfig } from '../config/moduleConfig.js'
 import { currentNodeEnv } from '../env/nodeEnv.js'
 import { durationToSeconds } from '../helpers/duration.js'
 import type { HttpContext } from '../http/HttpContext.js'
+import type { SessionConfigInput } from './config.js'
 import { CookieDriver } from './drivers/CookieDriver.js'
 import { DatabaseDriver, type SessionDbConnection } from './drivers/DatabaseDriver.js'
 import { FileDriver } from './drivers/FileDriver.js'
@@ -16,7 +18,7 @@ import { MemoryDriver } from './drivers/MemoryDriver.js'
 import { RedisDriver } from './drivers/RedisDriver.js'
 import { quasarConnection } from './quasar.js'
 import { ReadOnlyValuesStore, type ValuePath } from './ReadOnlyValuesStore.js'
-import type { SessionConfig, SessionDriver } from './Session.js'
+import type { SessionDriver } from './Session.js'
 import { Session } from './Session.js'
 
 interface ResolvedSessionConfig {
@@ -42,7 +44,18 @@ export default class SessionMiddleware {
   #cookieDriver: CookieDriver | null = null
   #config: ResolvedSessionConfig
 
-  constructor(config?: SessionConfig & { secret?: string }) {
+  constructor(explicitConfig: SessionConfigInput | undefined = undefined) {
+    // The default value is load-bearing: an OPTIONAL parameter still counts
+    // toward `Function.length`, and the container refuses to auto-construct a
+    // class that declares parameters it has no metadata for. A parameter with a
+    // default counts for nothing, which is what lets
+    // `router.use([() => import('…')])` build this middleware.
+    // Nothing is passed when the container builds this middleware from
+    // `router.use([() => import('@c9up/ream/session_middleware')])`, which is
+    // the registration shape the framework documents. `config/session.ts` is
+    // where the settings live in that case — the same file the config loader
+    // already reads into `config.get('session')`.
+    const config = explicitConfig ?? readModuleConfig<SessionConfigInput>('session')
     // `store` + `stores` (AdonisJS) and `driver` (ream) name the same thing.
     // A named store supplies the driver and its own options, so
     // `{ store: 'redis', stores: { redis: { driver: 'redis' } } }` works.

package/src/session/config.ts

@@ -0,0 +1,29 @@
+/**
+ * `config/session.ts` — the session store's configuration, in the file the
+ * config loader reads (`config/<name>.ts` → `config.get('<name>')`).
+ *
+ * @example
+ *   // config/session.ts
+ *   import env from '#start/env.js'
+ *   import { defineConfig } from '@c9up/ream/session/config'
+ *
+ *   export default defineConfig({
+ *     store: 'cookie',
+ *     secret: env.get('APP_KEY'),
+ *   })
+ */
+
+import type { SessionConfig } from './Session.js'
+
+/** What a session config file may declare. */
+export type SessionConfigInput = SessionConfig & {
+  /**
+   * Signs the session cookie. Required by the cookie store, which carries the
+   * data itself and would otherwise hand the client something it could edit.
+   */
+  secret?: string
+}
+
+export function defineConfig(config: SessionConfigInput): SessionConfigInput {
+  return config
+}