@c9up/ream 0.2.4 → 0.2.6

package/src/Application.ts

@@ -13,6 +13,7 @@
  * @implements FR17, FR20
  */
 
+import { readFileSync } from 'node:fs'
 import { join, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { ConfigStore } from './ConfigLoader.js'
@@ -29,17 +30,45 @@ import { callProviderPhase } from './Provider.js'
  */
 export type ApplicationMode = 'run' | 'warmup'
 
+/**
+ * What the process is running as (AdonisJS `AppEnvironments`).
+ *
+ * Providers and preloads are filtered on it — a console-only provider must not
+ * boot inside an HTTP request. `repl` is absent because ream has no REPL; it
+ * belongs here the day one exists, not before.
+ */
+export type AppEnvironment = 'web' | 'console' | 'test' | 'unknown'
+
+/**
+ * Where the application is in its lifecycle (AdonisJS `ApplicationStates`).
+ *
+ * Read it rather than inferring from a boolean: "not booted" covers both
+ * "starting up" and "already shut down", and code that guards on the wrong one
+ * runs at exactly the wrong moment.
+ */
+export type ApplicationState =
+  | 'created'
+  | 'initiated'
+  | 'booted'
+  | 'ready'
+  | 'terminating'
+  | 'terminated'
+
 export class Application implements AppContext {
   readonly container: Container
   readonly config: ConfigStore
   #appRoot?: URL
   #directories: DirectoriesNode = { ...defaultDirectories }
-  private providers: ProviderContract[] = []
-  private _booted = false
+  #providers: ProviderContract[] = []
+  #booted = false
+  #environment: AppEnvironment = 'unknown'
+  #state: ApplicationState = 'created'
+  #packageJsonRead = false
+  #packageJsonCache: { name?: string; version?: string } | undefined
   #mode: ApplicationMode = 'run'
-  private _bootingHooks: Array<() => Promise<void> | void> = []
-  private _bootedHooks: Array<() => Promise<void> | void> = []
-  private _shutdownHooks: Array<() => Promise<void> | void> = []
+  #bootingHooks: Array<() => Promise<void> | void> = []
+  #bootedHooks: Array<() => Promise<void> | void> = []
+  #shutdownHooks: Array<() => Promise<void> | void> = []
 
   constructor() {
     this.container = new Container()
@@ -69,7 +98,7 @@ export class Application implements AppContext {
    * otherwise would leave the app half-started.
    */
   setMode(mode: ApplicationMode): this {
-    if (this._booted) {
+    if (this.#booted) {
       throw new Error(`Cannot switch to '${mode}' mode: the application is already booted.`)
     }
     this.#mode = mode
@@ -313,7 +342,7 @@ export class Application implements AppContext {
    * Like AdonisJS app.booting().
    */
   booting(callback: () => Promise<void> | void): void {
-    this._bootingHooks.push(callback)
+    this.#bootingHooks.push(callback)
   }
 
   /**
@@ -321,7 +350,7 @@ export class Application implements AppContext {
    * Like AdonisJS app.booted().
    */
   booted(callback: () => Promise<void> | void): void {
-    if (this._booted) {
+    if (this.#booted) {
       // Already booted — run immediately. Invoke callback() INSIDE the
       // promise chain (not as `Promise.resolve(callback())`, which
       // evaluates callback() eagerly and lets a synchronous throw
@@ -334,7 +363,7 @@ export class Application implements AppContext {
         })
       return
     }
-    this._bootedHooks.push(callback)
+    this.#bootedHooks.push(callback)
   }
 
   // ─── Signal handling ──────────────────────────────────────
@@ -354,6 +383,166 @@ export class Application implements AppContext {
     process.on(signal, callback)
   }
 
+  /**
+   * What the process is running as (AdonisJS `getEnvironment`).
+   *
+   * Lives on the application, not on the Ignitor, because that is where a
+   * provider reads it: `if (app.getEnvironment() !== 'web') return`.
+   */
+  getEnvironment(): AppEnvironment {
+    return this.#environment
+  }
+
+  /**
+   * Declare what the process is running as (AdonisJS `setEnvironment`).
+   *
+   * Refused after boot: providers and preloads were already filtered on the
+   * old value, so changing it afterwards would describe an application that
+   * was never assembled.
+   */
+  setEnvironment(environment: AppEnvironment): this {
+    if (this.#booted) {
+      throw new Error(
+        `Cannot switch to the '${environment}' environment: the application is already booted.`,
+      )
+    }
+    this.#environment = environment
+    return this
+  }
+
+  /** `process.env.NODE_ENV`, or `'unknown'` (AdonisJS `nodeEnvironment`). */
+  get nodeEnvironment(): string {
+    return process.env.NODE_ENV ?? 'unknown'
+  }
+
+  /** Where the application is in its lifecycle (AdonisJS `getState`). */
+  getState(): ApplicationState {
+    return this.#state
+  }
+
+  /** True once boot and every ready hook have completed (AdonisJS `isReady`). */
+  get isReady(): boolean {
+    return this.#state === 'ready'
+  }
+
+  /** True while shutdown hooks are running (AdonisJS `isTerminating`). */
+  get isTerminating(): boolean {
+    return this.#state === 'terminating'
+  }
+
+  /** True once shutdown has completed (AdonisJS `isTerminated`). */
+  get isTerminated(): boolean {
+    return this.#state === 'terminated'
+  }
+
+  /** The name from the app's `package.json`, when it could be read. */
+  get appName(): string | undefined {
+    return this.#packageJson()?.name
+  }
+
+  /** The version from the app's `package.json`, when it could be read. */
+  get version(): string | undefined {
+    return this.#packageJson()?.version
+  }
+
+  /**
+   * A snapshot of the application, for a health endpoint or a bug report
+   * (AdonisJS `toJSON`).
+   */
+  toJSON(): {
+    appName: string | undefined
+    version: string | undefined
+    environment: AppEnvironment
+    nodeEnvironment: string
+    state: ApplicationState
+    isReady: boolean
+    isTerminating: boolean
+  } {
+    return {
+      appName: this.appName,
+      version: this.version,
+      environment: this.#environment,
+      nodeEnvironment: this.nodeEnvironment,
+      state: this.#state,
+      isReady: this.isReady,
+      isTerminating: this.isTerminating,
+    }
+  }
+
+  /**
+   * Listen for a signal, then stop listening (AdonisJS `listenOnce`).
+   *
+   * Registered through {@link listen} so the handler is still removed by
+   * `terminate()` when the signal never arrives — otherwise a stopped app
+   * would leave a listener behind, and the next real signal would run the
+   * handlers of every app instance that ever existed.
+   */
+  listenOnce(signal: NodeJS.Signals, callback: () => void): void {
+    const once = (): void => {
+      process.removeListener(signal, once)
+      callback()
+    }
+    this.listen(signal, once)
+  }
+
+  /** {@link listenOnce}, only when `condition` holds (AdonisJS `listenOnceIf`). */
+  listenOnceIf(condition: boolean, signal: NodeJS.Signals, callback: () => void): void {
+    if (condition) this.listenOnce(signal, callback)
+  }
+
+  /**
+   * Tell the process supervisor the app reached a state (AdonisJS `notify`).
+   *
+   * A no-op unless something is listening — systemd's `NOTIFY_SOCKET`, or a
+   * parent process. Silent by design: an app should not fail to start because
+   * nothing was there to hear it.
+   */
+  notify(message: string): void {
+    process.send?.({ type: 'ream:notify', message })
+  }
+
+  /**
+   * Import a module and return its default export (AdonisJS `importDefault`).
+   *
+   * Throws when there is none, naming the file: a preload or provider entry
+   * without a default export otherwise fails later, as `undefined is not a
+   * constructor`, far from the file at fault.
+   */
+  async importDefault<T = unknown>(importFn: () => Promise<unknown>, label?: string): Promise<T> {
+    const module = await importFn()
+    if (module === null || typeof module !== 'object' || !('default' in module)) {
+      throw new Error(
+        `Missing default export${label ? ` in "${label}"` : ''}. ` +
+          'Export the value as `export default`, or import the named export directly.',
+      )
+    }
+    // The caller declares what it expects to find, the same contract as
+    // `container.make<T>()` over a dynamic import.
+    return module.default as T
+  }
+
+  /** The app's `package.json`, read once and cached; `undefined` when absent. */
+  #packageJson(): { name?: string; version?: string } | undefined {
+    if (this.#packageJsonRead) return this.#packageJsonCache
+    this.#packageJsonRead = true
+    try {
+      const path = this.makePath('package.json')
+      const raw = readFileSync(path, 'utf8')
+      const parsed: unknown = JSON.parse(raw)
+      if (parsed !== null && typeof parsed === 'object') {
+        const name = 'name' in parsed && typeof parsed.name === 'string' ? parsed.name : undefined
+        const version =
+          'version' in parsed && typeof parsed.version === 'string' ? parsed.version : undefined
+        this.#packageJsonCache = { name, version }
+      }
+    } catch {
+      // No app root, no package.json, unreadable, or malformed — every one of
+      // those means "we do not know the name", not "fail to boot".
+      this.#packageJsonCache = undefined
+    }
+    return this.#packageJsonCache
+  }
+
   /**
    * Conditionally listen for a process signal.
    * Like AdonisJS app.listenIf(app.managedByPm2, 'SIGINT', ...).
@@ -377,7 +566,7 @@ export class Application implements AppContext {
 
   /** Register a provider instance. */
   register(provider: ProviderContract): void {
-    this.providers.push(provider)
+    this.#providers.push(provider)
     if (typeof provider.register === 'function') {
       provider.register()
     }
@@ -385,26 +574,32 @@ export class Application implements AppContext {
 
   /** Boot all registered providers. Runs booting/booted hooks. */
   async boot(): Promise<void> {
-    if (this._booted) return
+    if (this.#booted) return
 
     // Run booting hooks
-    for (const hook of this._bootingHooks) {
+    for (const hook of this.#bootingHooks) {
       await hook()
     }
 
     // Boot providers. `callProviderPhase` skips providers that don't
     // declare the phase — duck-typed packages (spectrum, warden, etc.)
     // implement only what they need.
-    for (const provider of this.providers) {
+    for (const provider of this.#providers) {
       await callProviderPhase(provider, 'boot')
     }
 
-    this._booted = true
+    this.#booted = true
+    this.#state = 'booted'
 
     // Run booted hooks
-    for (const hook of this._bootedHooks) {
+    for (const hook of this.#bootedHooks) {
       await hook()
     }
+
+    // Ready only once the booted hooks have run: they are where an app wires
+    // the things a request will need, so reporting ready before them would
+    // green a health check on an application that cannot serve yet.
+    this.#state = 'ready'
   }
 
   /**
@@ -414,8 +609,9 @@ export class Application implements AppContext {
    */
   async shutdown(): Promise<void> {
     const errors: unknown[] = []
+    this.#state = 'terminating'
 
-    for (const hook of this._shutdownHooks) {
+    for (const hook of this.#shutdownHooks) {
       try {
         await hook()
       } catch (err) {
@@ -423,7 +619,7 @@ export class Application implements AppContext {
       }
     }
 
-    for (const provider of [...this.providers].reverse()) {
+    for (const provider of [...this.#providers].reverse()) {
       try {
         await callProviderPhase(provider, 'shutdown')
       } catch (err) {
@@ -437,7 +633,11 @@ export class Application implements AppContext {
     }
     this.#signalHandlers = []
 
-    this._booted = false
+    this.#booted = false
+    // Terminated even when a hook threw: the hooks and providers have all been
+    // given their turn, so the application IS down. Reporting anything else
+    // would leave a supervisor waiting on a shutdown that already happened.
+    this.#state = 'terminated'
     if (errors.length === 1) throw errors[0]
     if (errors.length > 1) {
       throw new AggregateError(errors, 'Application.shutdown() completed with errors')
@@ -446,14 +646,14 @@ export class Application implements AppContext {
 
   /** Register a shutdown hook. */
   onShutdown(callback: () => Promise<void> | void): void {
-    this._shutdownHooks.push(callback)
+    this.#shutdownHooks.push(callback)
   }
 
   get isBooted(): boolean {
-    return this._booted
+    return this.#booted
   }
 
   get providerCount(): number {
-    return this.providers.length
+    return this.#providers.length
   }
 }

package/src/ErrorBoundary.ts

@@ -33,20 +33,20 @@ export type ErrorEmitter = (event: ErrorEvent) => void
  * - In dev mode, also logs to console
  */
 export class ErrorBoundary {
-  private emitter: ErrorEmitter
-  private devMode: boolean
-  private installed = false
-  private rejectionHandler?: (reason: unknown) => void
-  private exceptionHandler?: (error: Error) => void
+  #emitter: ErrorEmitter
+  #devMode: boolean
+  #installed = false
+  #rejectionHandler?: (reason: unknown) => void
+  #exceptionHandler?: (error: Error) => void
 
   constructor(emitter: ErrorEmitter, devMode = false) {
-    this.emitter = emitter
-    this.devMode = devMode
+    this.#emitter = emitter
+    this.#devMode = devMode
   }
 
   /** Install global error handlers. */
   install(): void {
-    if (this.installed) return
+    if (this.#installed) return
 
     // Skip global install under vitest — each test instantiates its own
     // Ignitor and rarely calls `.stop()`, so per-test listeners pile up on
@@ -55,42 +55,42 @@ export class ErrorBoundary {
     // `handleError`/`serviceError` calls; only the Node-level signal
     // bridging is suppressed.
     if (process.env.VITEST === 'true' || process.env.NODE_ENV === 'test') {
-      this.installed = true
+      this.#installed = true
       return
     }
 
-    this.rejectionHandler = (reason) => {
-      this.handleError('system.fatal', 'UnhandledRejection', reason)
+    this.#rejectionHandler = (reason) => {
+      this.#handleError('system.fatal', 'UnhandledRejection', reason)
     }
 
-    this.exceptionHandler = (error) => {
-      this.handleError('system.fatal', 'UncaughtException', error)
+    this.#exceptionHandler = (error) => {
+      this.#handleError('system.fatal', 'UncaughtException', error)
       // Node.js is in undefined state after uncaughtException — must exit
       process.exit(1)
     }
 
-    process.on('unhandledRejection', this.rejectionHandler)
-    process.on('uncaughtException', this.exceptionHandler)
+    process.on('unhandledRejection', this.#rejectionHandler)
+    process.on('uncaughtException', this.#exceptionHandler)
 
-    this.installed = true
+    this.#installed = true
   }
 
   /** Uninstall global error handlers (for testing). Only removes OUR handlers. */
   uninstall(): void {
-    if (this.rejectionHandler) {
-      process.removeListener('unhandledRejection', this.rejectionHandler)
+    if (this.#rejectionHandler) {
+      process.removeListener('unhandledRejection', this.#rejectionHandler)
     }
-    if (this.exceptionHandler) {
-      process.removeListener('uncaughtException', this.exceptionHandler)
+    if (this.#exceptionHandler) {
+      process.removeListener('uncaughtException', this.#exceptionHandler)
     }
-    this.rejectionHandler = undefined
-    this.exceptionHandler = undefined
-    this.installed = false
+    this.#rejectionHandler = undefined
+    this.#exceptionHandler = undefined
+    this.#installed = false
   }
 
   /** Emit a service error (handler failure). */
   serviceError(source: string, error: unknown, correlationId?: string): void {
-    this.handleError('service.error', source, error, correlationId)
+    this.#handleError('service.error', source, error, correlationId)
   }
 
   /** Emit a security rejection. */
@@ -103,15 +103,15 @@ export class ErrorBoundary {
       correlationId,
       timestamp: new Date().toISOString(),
     }
-    this.emit(event)
+    this.#emit(event)
   }
 
   /** Emit a system error (infrastructure failure). */
   systemError(source: string, error: unknown, correlationId?: string): void {
-    this.handleError('system.error', source, error, correlationId)
+    this.#handleError('system.error', source, error, correlationId)
   }
 
-  private handleError(
+  #handleError(
     type: ErrorEvent['type'],
     source: string,
     error: unknown,
@@ -131,12 +131,12 @@ export class ErrorBoundary {
       timestamp: new Date().toISOString(),
     }
 
-    this.emit(event)
+    this.#emit(event)
   }
 
-  private emit(event: ErrorEvent): void {
+  #emit(event: ErrorEvent): void {
     try {
-      this.emitter(event)
+      this.#emitter(event)
     } catch {
       // If the emitter itself fails, log to stderr as last resort
       process.stderr.write(`[ErrorBoundary] Failed to emit: ${JSON.stringify(event)}\n`)
@@ -150,7 +150,7 @@ export class ErrorBoundary {
     // boundary would turn each forgotten `await` from a loud crash into
     // nothing at all, which is the opposite of what it is for. A duplicated
     // line when a listener also logs it is a much smaller price.
-    if (this.devMode || event.type === 'system.fatal') {
+    if (this.#devMode || event.type === 'system.fatal') {
       const prefix =
         event.type === 'system.fatal'
           ? '✗ FATAL'

package/src/HttpKernel.ts

@@ -19,7 +19,7 @@ import type {
   MiddlewareRegistry,
   RuntimeValidator,
 } from './middleware/Pipeline.js'
-import { compose } from './middleware/Pipeline.js'
+import { composeMiddleware } from './middleware/Pipeline.js'
 import type { AnyConstructor, RouteDefinition, Router } from './router/Router.js'
 import type { CookieSigner } from './security/CookieSigner.js'
 import type { SignedUrl } from './security/SignedUrl.js'
@@ -318,7 +318,7 @@ export function createHttpKernel(
       // HttpContext ALS so HttpContext.get()/getOrFail() reach this request
       // anywhere down the call stack (AdonisJS parity) — transparent to the
       // pipeline itself.
-      const fullPipeline = compose([...serverMw, coreHandler])
+      const fullPipeline = composeMiddleware([...serverMw, coreHandler])
       await HttpContext.run(ctx, () => fullPipeline(ctx, async () => {}))
 
       ctx.events?.emit('http:response', {