@c9up/ream 0.1.33 → 0.2.0

package/src/health/checks/MemoryHeapCheck.ts

@@ -0,0 +1,68 @@
+import v8 from 'node:v8'
+import { BaseCheck } from '../BaseCheck.js'
+import type { HealthCheckResult } from '../types.js'
+import { assertPercentage, parseByteThreshold, runMemoryCheck } from './memory.js'
+
+/**
+ * Watches the V8 heap (AdonisJS `MemoryHeapCheck`).
+ */
+export class MemoryHeapCheck extends BaseCheck {
+  #warnThresholdBytes: number | null = 250 * 1024 ** 2
+  #failThresholdBytes: number | null = 300 * 1024 ** 2
+  #warnThresholdPercentage: number | null = null
+  #failThresholdPercentage: number | null = null
+  #computeFn: () => NodeJS.MemoryUsage = () => process.memoryUsage()
+
+  name = 'Memory heap check'
+
+  /** Warn above this size — `'300 mb'` or a byte count. Clears any percentage. */
+  warnWhenExceeds(value: string | number): this {
+    this.#warnThresholdBytes = parseByteThreshold(value, 'warnWhenExceeds')
+    this.#warnThresholdPercentage = null
+    return this
+  }
+
+  /** Fail above this size. Clears any percentage. */
+  failWhenExceeds(value: string | number): this {
+    this.#failThresholdBytes = parseByteThreshold(value, 'failWhenExceeds')
+    this.#failThresholdPercentage = null
+    return this
+  }
+
+  /** Warn above this share of the heap ceiling. Clears any byte threshold. */
+  warnWhenExceedsPercentage(valueInPercentage: number): this {
+    assertPercentage(valueInPercentage, 'Warn')
+    this.#warnThresholdPercentage = valueInPercentage
+    this.#warnThresholdBytes = null
+    return this
+  }
+
+  /** Fail above this share of the heap ceiling. Clears any byte threshold. */
+  failWhenExceedsPercentage(valueInPercentage: number): this {
+    assertPercentage(valueInPercentage, 'Fail')
+    this.#failThresholdPercentage = valueInPercentage
+    this.#failThresholdBytes = null
+    return this
+  }
+
+  /** Replace how the reading is taken, so a test can drive the thresholds. */
+  compute(callback: () => NodeJS.MemoryUsage): this {
+    this.#computeFn = callback
+    return this
+  }
+
+  async run(): Promise<HealthCheckResult> {
+    const { heapUsed } = this.#computeFn()
+    return runMemoryCheck(
+      heapUsed,
+      {
+        warnBytes: this.#warnThresholdBytes,
+        failBytes: this.#failThresholdBytes,
+        warnPercentage: this.#warnThresholdPercentage,
+        failPercentage: this.#failThresholdPercentage,
+      },
+      { subject: 'Heap', ceilingKey: 'heapInBytes', ceilingName: 'maxHeapSize' },
+      () => v8.getHeapStatistics().heap_size_limit,
+    )
+  }
+}

package/src/health/checks/MemoryRSSCheck.ts

@@ -0,0 +1,68 @@
+import os from 'node:os'
+import { BaseCheck } from '../BaseCheck.js'
+import type { HealthCheckResult } from '../types.js'
+import { assertPercentage, parseByteThreshold, runMemoryCheck } from './memory.js'
+
+/**
+ * Watches the process' resident set size (AdonisJS `MemoryRSSCheck`).
+ */
+export class MemoryRSSCheck extends BaseCheck {
+  #warnThresholdBytes: number | null = 320 * 1024 ** 2
+  #failThresholdBytes: number | null = 350 * 1024 ** 2
+  #warnThresholdPercentage: number | null = null
+  #failThresholdPercentage: number | null = null
+  #computeFn: () => NodeJS.MemoryUsage = () => process.memoryUsage()
+
+  name = 'Memory RSS check'
+
+  /** Warn above this size — `'300 mb'` or a byte count. Clears any percentage. */
+  warnWhenExceeds(value: string | number): this {
+    this.#warnThresholdBytes = parseByteThreshold(value, 'warnWhenExceeds')
+    this.#warnThresholdPercentage = null
+    return this
+  }
+
+  /** Fail above this size. Clears any percentage. */
+  failWhenExceeds(value: string | number): this {
+    this.#failThresholdBytes = parseByteThreshold(value, 'failWhenExceeds')
+    this.#failThresholdPercentage = null
+    return this
+  }
+
+  /** Warn above this share of total system memory. Clears any byte threshold. */
+  warnWhenExceedsPercentage(valueInPercentage: number): this {
+    assertPercentage(valueInPercentage, 'Warn')
+    this.#warnThresholdPercentage = valueInPercentage
+    this.#warnThresholdBytes = null
+    return this
+  }
+
+  /** Fail above this share of total system memory. Clears any byte threshold. */
+  failWhenExceedsPercentage(valueInPercentage: number): this {
+    assertPercentage(valueInPercentage, 'Fail')
+    this.#failThresholdPercentage = valueInPercentage
+    this.#failThresholdBytes = null
+    return this
+  }
+
+  /** Replace how the reading is taken, so a test can drive the thresholds. */
+  compute(callback: () => NodeJS.MemoryUsage): this {
+    this.#computeFn = callback
+    return this
+  }
+
+  async run(): Promise<HealthCheckResult> {
+    const { rss } = this.#computeFn()
+    return runMemoryCheck(
+      rss,
+      {
+        warnBytes: this.#warnThresholdBytes,
+        failBytes: this.#failThresholdBytes,
+        warnPercentage: this.#warnThresholdPercentage,
+        failPercentage: this.#failThresholdPercentage,
+      },
+      { subject: 'RSS', ceilingKey: 'memoryInBytes', ceilingName: 'totalSystemMemory' },
+      () => os.totalmem(),
+    )
+  }
+}

package/src/health/checks/memory.ts

@@ -0,0 +1,115 @@
+import bytes from '../../helpers/bytes.js'
+import { Result } from '../Result.js'
+import type { HealthCheckResult } from '../types.js'
+
+/**
+ * The shared body of the two memory checks.
+ *
+ * Upstream spells this logic out twice, once in `MemoryRSSCheck` and once in
+ * `MemoryHeapCheck`; only the reading, the ceiling it is compared against, and
+ * two strings differ. The public surface of both classes is unchanged — this is
+ * an internal detail, not a deviation.
+ */
+export type MemoryThresholds = {
+  warnBytes: number | null
+  failBytes: number | null
+  warnPercentage: number | null
+  failPercentage: number | null
+}
+
+export function runMemoryCheck(
+  used: number,
+  thresholds: MemoryThresholds,
+  labels: { subject: string; ceilingKey: string; ceilingName: string },
+  readCeiling: () => number,
+): HealthCheckResult {
+  const compareAsPercentage =
+    thresholds.warnPercentage !== null || thresholds.failPercentage !== null
+
+  let warnThreshold: number
+  let failThreshold: number
+  let valueToCompare: number
+  let ceiling: number | null = null
+  let usedPercentage: number | null = null
+
+  if (compareAsPercentage) {
+    ceiling = readCeiling()
+    if (ceiling === 0) {
+      return Result.failed(`Cannot determine ${labels.ceilingName} (0 bytes).`).mergeMetaData({
+        [labels.ceilingKey]: { used, [labels.ceilingName]: ceiling },
+      })
+    }
+    usedPercentage = Math.floor((used / ceiling) * 100)
+    valueToCompare = usedPercentage
+
+    if (thresholds.warnPercentage !== null) warnThreshold = thresholds.warnPercentage
+    else if (thresholds.warnBytes !== null)
+      warnThreshold = Math.floor((thresholds.warnBytes / ceiling) * 100)
+    else return Result.failed('Warning threshold for percentage comparison is missing.')
+
+    if (thresholds.failPercentage !== null) failThreshold = thresholds.failPercentage
+    else if (thresholds.failBytes !== null)
+      failThreshold = Math.floor((thresholds.failBytes / ceiling) * 100)
+    else return Result.failed('Failure threshold for percentage comparison is missing.')
+  } else {
+    valueToCompare = used
+    if (thresholds.warnBytes === null) return Result.failed('Warning threshold (bytes) is missing.')
+    warnThreshold = thresholds.warnBytes
+    if (thresholds.failBytes === null) return Result.failed('Failure threshold (bytes) is missing.')
+    failThreshold = thresholds.failBytes
+  }
+
+  const metaData: Record<string, unknown> = {}
+  if (compareAsPercentage) {
+    metaData.sizeInPercentage = {
+      used: usedPercentage,
+      failureThreshold: failThreshold,
+      warningThreshold: warnThreshold,
+    }
+    if (ceiling !== null) {
+      metaData[labels.ceilingKey] = {
+        used,
+        [labels.ceilingName]: ceiling,
+        failureThreshold: Math.floor((failThreshold / 100) * ceiling),
+        warningThreshold: Math.floor((warnThreshold / 100) * ceiling),
+      }
+    }
+  } else {
+    metaData.memoryInBytes = {
+      used,
+      failureThreshold: failThreshold,
+      warningThreshold: warnThreshold,
+    }
+  }
+
+  const show = (value: number, threshold: number) =>
+    compareAsPercentage
+      ? { used: `${value}%`, limit: `${threshold}%` }
+      : { used: bytes.format(used), limit: bytes.format(threshold) }
+
+  if (valueToCompare >= failThreshold) {
+    const { used: u, limit } = show(valueToCompare, failThreshold)
+    return Result.failed(
+      `${labels.subject} usage is ${u}, which is above the threshold of ${limit}`,
+    ).mergeMetaData(metaData)
+  }
+  if (valueToCompare >= warnThreshold) {
+    const { used: u, limit } = show(valueToCompare, warnThreshold)
+    return Result.warning(
+      `${labels.subject} usage is ${u}, which is above the threshold of ${limit}`,
+    ).mergeMetaData(metaData)
+  }
+  return Result.ok(`${labels.subject} usage is under defined thresholds`).mergeMetaData(metaData)
+}
+
+/** The threshold setters both memory checks expose, shared verbatim. */
+export function parseByteThreshold(value: string | number, method: string): number {
+  const parsed = bytes.parse(value)
+  if (parsed === null) throw new Error(`Invalid byte value for ${method}: ${value}`)
+  return parsed
+}
+
+export function assertPercentage(value: number, label: string): void {
+  if (value < 0 || value > 100)
+    throw new Error(`${label} threshold percentage must be between 0 and 100.`)
+}

package/src/health/index.ts

@@ -0,0 +1,13 @@
+export { BaseCheck } from './BaseCheck.js'
+export { DiskSpaceCheck } from './checks/DiskSpaceCheck.js'
+export { MemoryHeapCheck } from './checks/MemoryHeapCheck.js'
+export { MemoryRSSCheck } from './checks/MemoryRSSCheck.js'
+export { HealthChecks } from './HealthChecks.js'
+export { Result } from './Result.js'
+export * as tracingChannels from './tracing.js'
+export type {
+  HealthCheckContract,
+  HealthCheckReport,
+  HealthCheckResult,
+  HealthCheckTracingData,
+} from './types.js'

package/src/health/tracing.ts

@@ -0,0 +1,15 @@
+import diagnostics_channel from 'node:diagnostics_channel'
+import type { HealthCheckTracingData } from './types.js'
+
+/**
+ * A diagnostics channel carrying every check run, so an APM can time checks
+ * without the app wiring anything.
+ *
+ * NAMED DEVIATION — the channel is `ream.health.check`, not upstream's
+ * `adonisjs.health.check`. A channel name is product identity, and a subscriber
+ * listening for both frameworks in one process must be able to tell them apart.
+ */
+export const healthCheck = diagnostics_channel.tracingChannel<
+  'ream.health.check',
+  HealthCheckTracingData
+>('ream.health.check')

package/src/health/types.ts

@@ -0,0 +1,51 @@
+/**
+ * Health-check contracts, mirroring `@adonisjs/core/health`.
+ */
+
+/** The outcome of running one check. */
+export type HealthCheckResult = {
+  /** A summary of the check result. */
+  message: string
+  /** The status of the check. */
+  status: 'ok' | 'warning' | 'error'
+  /** When this check finished. */
+  finishedAt: Date
+  /** Free-form data the check wants to expose alongside its verdict. */
+  meta?: Record<string, unknown>
+}
+
+/** The report produced by running every registered check. */
+export type HealthCheckReport = {
+  /** False as soon as one check reports `error`. A warning stays healthy. */
+  isHealthy: boolean
+  /** `error` beats `warning` beats `ok`. */
+  status: 'ok' | 'warning' | 'error'
+  /** When the whole report was computed. */
+  finishedAt: Date
+  /** Identifying data for the process that produced the report. */
+  debugInfo: {
+    pid: number
+    ppid?: number
+    /** Seconds the process has been running. */
+    uptime: number
+    version: string
+    platform: string
+  }
+  /** Each check's result, plus whether it came from the cache. */
+  checks: ({ isCached: boolean; name: string } & HealthCheckResult)[]
+}
+
+/** What every check must implement. */
+export interface HealthCheckContract {
+  /** A unique name for the check. */
+  name: string
+  /** Seconds to reuse a previous result for. Undefined means never cache. */
+  cacheDuration?: number
+  /** Perform the check. */
+  run(): Promise<HealthCheckResult>
+}
+
+/** What a tracing subscriber receives. */
+export type HealthCheckTracingData = {
+  check: HealthCheckContract
+}

package/src/helpers/bytes.ts

@@ -0,0 +1,71 @@
+/**
+ * Byte-size parsing and formatting, as `string.bytes` in AdonisJS.
+ *
+ * Upstream reaches for `@poppinss/string`, which wraps the `bytes` package.
+ * Ream carries the ~40 lines instead of the dependency, matching that package's
+ * semantics exactly: binary units (1 kb = 1024 b), a bare number string read as
+ * bytes, and `null` — never a throw — when the input cannot be read.
+ */
+
+const UNITS = {
+  b: 1,
+  kb: 1024,
+  mb: 1024 ** 2,
+  gb: 1024 ** 3,
+  tb: 1024 ** 4,
+  pb: 1024 ** 5,
+} as const
+
+type Unit = keyof typeof UNITS
+
+const PARSE = /^((?:-|\+)?(?:\d+(?:\.\d+)?)) *(kb|mb|gb|tb|pb)$/i
+/** Trailing `.00`, or the zeros trailing a real decimal. */
+const TRAILING_ZEROS = /(?:\.0*|(\.[^0]+)0+)$/
+
+/**
+ * Read a human-readable size into a number of bytes.
+ *
+ * A number passes through untouched. A string with no unit is read as bytes,
+ * so `'1024'` and `1024` agree. Returns `null` when there is no number to find.
+ */
+export function parse(value: string | number): number | null {
+  if (typeof value === 'number') return Number.isNaN(value) ? null : value
+  if (typeof value !== 'string') return null
+
+  const matched = PARSE.exec(value)
+  const amount = matched ? Number.parseFloat(matched[1]) : Number.parseInt(value, 10)
+  if (Number.isNaN(amount)) return null
+
+  const unit = (matched ? matched[2].toLowerCase() : 'b') as Unit
+  return Math.floor(UNITS[unit] * amount)
+}
+
+/**
+ * Render a number of bytes for a human, picking the largest unit that leaves a
+ * value at or above 1. Returns `null` for a non-finite input.
+ */
+export function format(valueInBytes: number, options?: { decimalPlaces?: number }): string | null {
+  if (!Number.isFinite(valueInBytes)) return null
+
+  const magnitude = Math.abs(valueInBytes)
+  const unit: Unit =
+    magnitude >= UNITS.pb
+      ? 'pb'
+      : magnitude >= UNITS.tb
+        ? 'tb'
+        : magnitude >= UNITS.gb
+          ? 'gb'
+          : magnitude >= UNITS.mb
+            ? 'mb'
+            : magnitude >= UNITS.kb
+              ? 'kb'
+              : 'b'
+
+  const rendered = (valueInBytes / UNITS[unit])
+    .toFixed(options?.decimalPlaces ?? 2)
+    .replace(TRAILING_ZEROS, '$1')
+
+  return `${rendered}${unit.toUpperCase()}`
+}
+
+export default { parse, format }

package/src/helpers/string.ts

@@ -1,4 +1,5 @@
 import { randomBytes } from 'node:crypto'
+import bytes from './bytes.js'
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -441,6 +442,7 @@ export function interpolate(template: string, data: Record<string, unknown>): st
 // ---------------------------------------------------------------------------
 
 const string = {
+  bytes,
   camelCase,
   snakeCase,
   pascalCase,

package/src/http/HttpContext.ts

@@ -168,9 +168,31 @@ export interface RouteInfo {
   action?: string
 }
 
+/**
+ * The `'ControllerName.method'` identity of a route, or undefined for an inline
+ * handler. This is what `request.matchesRoute()` matches on besides the name and
+ * the pattern, the way AdonisJS matches `route.handler.reference`.
+ */
+function controllerReference(route: RouteInfo): string | undefined {
+  const controller = route.controller as { name?: string } | undefined
+  if (!controller?.name || !route.action) return undefined
+  return `${controller.name}.${route.action}`
+}
+
 /** Ambient per-request context store (AdonisJS `HttpContext` ALS accessor). */
 const httpContextStorage = new AsyncLocalStorage<HttpContext>()
 
+/**
+ * Whether the ambient context is being tracked.
+ *
+ * NAMED DEVIATION — on by default, where AdonisJS makes it opt-in through
+ * `useAsyncLocalStorage` in `config/app.ts`. Ream's own middleware and service
+ * accessors read the ambient context, so defaulting it off would break the
+ * framework's own wiring rather than just an app's. Turn it off with
+ * {@link HttpContext.useAsyncLocalStorage} to reclaim the tracking cost.
+ */
+let asyncLocalStorageEnabled = true
+
 export class HttpContext extends Macroable {
   /**
    * @internal Run `fn` with `ctx` as the ambient HttpContext, so code deep in
@@ -179,16 +201,50 @@ export class HttpContext extends Macroable {
    * request pipeline in this.
    */
   static run<T>(ctx: HttpContext, fn: () => T): T {
+    if (!asyncLocalStorageEnabled) return fn()
     return httpContextStorage.run(ctx, fn)
   }
 
-  /** The ambient HttpContext, or `undefined` outside a request (AdonisJS `HttpContext.get()`). */
-  static get(): HttpContext | undefined {
-    return httpContextStorage.getStore()
+  /**
+   * Whether the ambient context is being tracked (AdonisJS
+   * `HttpContext.usingAsyncLocalStorage`). When false, {@link get} always
+   * answers `null` and {@link getOrFail} always throws.
+   */
+  static get usingAsyncLocalStorage(): boolean {
+    return asyncLocalStorageEnabled
+  }
+
+  /**
+   * Turn ambient-context tracking on or off.
+   *
+   * AdonisJS decides this from `useAsyncLocalStorage` in `config/app.ts`; ream
+   * has it on by default (see the note on the storage above) and exposes the
+   * switch instead of a config key, so a benchmark or a worker process can
+   * drop the tracking without a config file.
+   */
+  static useAsyncLocalStorage(enabled: boolean): void {
+    asyncLocalStorageEnabled = enabled
+  }
+
+  /**
+   * The ambient HttpContext, or `null` outside a request (AdonisJS
+   * `HttpContext.get()`).
+   *
+   * `null`, not `undefined`: upstream's contract is `HttpContext | null`, and a
+   * migrated `=== null` check has to keep working.
+   */
+  static get(): HttpContext | null {
+    if (!asyncLocalStorageEnabled) return null
+    return httpContextStorage.getStore() ?? null
   }
 
   /** The ambient HttpContext, or throw outside a request (AdonisJS `HttpContext.getOrFail()`). */
   static getOrFail(): HttpContext {
+    if (!asyncLocalStorageEnabled) {
+      throw new Error(
+        '[E_HTTP_CONTEXT_NOT_FOUND] HttpContext.getOrFail() called while ambient-context tracking is off. Re-enable it with HttpContext.useAsyncLocalStorage(true), or pass ctx explicitly.',
+      )
+    }
     const ctx = httpContextStorage.getStore()
     if (!ctx) {
       throw new Error(
@@ -207,6 +263,17 @@ export class HttpContext extends Macroable {
     return httpContextStorage.exit(fn)
   }
 
+  /**
+   * A one-line summary of the request (AdonisJS `inspect`).
+   *
+   * What a log line or a debugger label wants: the verb, the path, and which
+   * route answered.
+   */
+  inspect(): string {
+    const route = this.route.name ?? this.route.pattern
+    return `${this.request.method()} ${this.request.url()} (${route})`
+  }
+
   /** Unique request/correlation ID. */
   readonly id: string
 
@@ -218,6 +285,14 @@ export class HttpContext extends Macroable {
 
   /** Route parameters extracted from the URL pattern. */
   /** Matched route parameters — `*` holds the segments it swallowed, as an array. */
+  /**
+   * Route parameters.
+   *
+   * `string | string[]`, not AdonisJS's `any`: a catch-all `*` really is the
+   * ARRAY of segments on both sides, so the `any` upstream only hides it. Use
+   * {@link Request.param} when you want the single-value form — it joins a
+   * catch-all with `/` and returns `string | undefined`.
+   */
   readonly params: MatchedParams
 
   /** Information about the matched route. */
@@ -335,7 +410,14 @@ export class HttpContext extends Macroable {
     // And the reverse, so `request.fresh()`/`stale()` delegate to it, plus the
     // matched-route info for `request.matchesRoute()`.
     this.request.setResponse(this.response)
-    this.request.setRouteInfo({ name: route.name, pattern: route.pattern })
+    // The back-references AdonisJS exposes as `request.ctx` / `response.ctx`.
+    this.request.ctx = this
+    this.response.ctx = this
+    this.request.setRouteInfo({
+      name: route.name,
+      pattern: route.pattern,
+      reference: controllerReference(route),
+    })
     // APP_KEY-backed encryption / signed-URL services + the base logger are
     // resolved asynchronously by HttpKernel and injected via the setters above
     // (the container is async now, so a constructor can't resolve them itself).