@c9up/ream 0.1.25 → 0.1.27

package/src/http/Exception.ts

@@ -6,6 +6,8 @@
  * - Built-in E_* exceptions
  */
 
+import { format } from 'node:util'
+import { Macroable } from '../utils/Macroable.js'
 import type { HttpContext } from './HttpContext.js'
 
 /**
@@ -29,9 +31,13 @@ import type { HttpContext } from './HttpContext.js'
 export class Exception extends Error {
   static status = 500
   static code = 'E_UNKNOWN'
+  /** Optional static remediation hint, copied onto instances (AdonisJS `Exception.help`). */
+  static help?: string
 
   status: number
   code: string
+  /** Human-readable remediation hint surfaced in debug output (AdonisJS `error.help`). */
+  help?: string
 
   constructor(message: string, options?: { status?: number; code?: string }) {
     super(message)
@@ -40,6 +46,7 @@ export class Exception extends Error {
     const ctor = this.constructor as any as typeof Exception
     this.status = options?.status ?? ctor.status
     this.code = options?.code ?? ctor.code
+    if (ctor.help !== undefined) this.help = ctor.help
   }
 
   /** Override to self-handle the exception (convert to HTTP response). */
@@ -49,6 +56,42 @@ export class Exception extends Error {
   report?(error: this, ctx: HttpContext): Promise<void> | void
 }
 
+/** A concrete Exception subclass produced by {@link createError}. */
+export interface ExceptionConstructor {
+  new (...args: unknown[]): Exception
+  status: number
+  code: string
+}
+
+/**
+ * Build a reusable Exception subclass in one line (AdonisJS `createError`).
+ * `message` may contain `util.format` placeholders (`%s`, `%d`) filled by the
+ * constructor args:
+ *
+ *   const E_RESOURCE_MISSING = createError('Resource %s not found', 'E_RESOURCE_MISSING', 404)
+ *   throw new E_RESOURCE_MISSING('user-42')   // → "Resource user-42 not found"
+ */
+export function createError(message: string, code: string, status = 500): ExceptionConstructor {
+  return class extends Exception {
+    static override status = status
+    static override code = code
+    constructor(...args: unknown[]) {
+      super(format(message, ...args), { status, code })
+    }
+  }
+}
+
+/** A generic 500 runtime error (AdonisJS `RuntimeException`). */
+export class RuntimeException extends Exception {
+  static override status = 500
+  static override code = 'E_RUNTIME_EXCEPTION'
+}
+
+/** Raised when a function receives invalid arguments (AdonisJS `InvalidArgumentsException`). */
+export class InvalidArgumentsException extends RuntimeException {
+  static override code = 'E_INVALID_ARGUMENTS'
+}
+
 // ─── Built-in exceptions ──────────────────────────────────
 
 export class E_ROUTE_NOT_FOUND extends Exception {
@@ -133,6 +176,34 @@ export class E_HTTP_EXCEPTION extends Exception {
   }
 }
 
+/**
+ * Thrown by `response.abort()` / `response.abortIf()` (AdonisJS parity). Carries
+ * an arbitrary body that {@link handle} renders as-is — a string verbatim,
+ * anything else as JSON.
+ */
+export class E_HTTP_REQUEST_ABORTED extends Exception {
+  static override status = 400
+  static override code = 'E_HTTP_REQUEST_ABORTED'
+
+  readonly body: unknown
+
+  constructor(body: unknown, status = 400) {
+    super(typeof body === 'string' ? body : 'Request aborted', {
+      status,
+      code: 'E_HTTP_REQUEST_ABORTED',
+    })
+    this.body = body
+  }
+
+  override handle(_error: this, ctx: HttpContext): void {
+    if (typeof this.body === 'string') {
+      ctx.response.status(this.status).send(this.body)
+    } else {
+      ctx.response.status(this.status).json(this.body)
+    }
+  }
+}
+
 // ─── ExceptionHandler ─────────────────────────────────────
 
 /**
@@ -150,54 +221,131 @@ export class E_HTTP_EXCEPTION extends Exception {
  * 2. Else → this.handle() → content negotiation (JSON or HTML)
  * 3. Then → this.report() → logging/monitoring
  */
-export class ExceptionHandler {
+/** Renders an HTML error page for a status (AdonisJS `StatusPageRenderer`). */
+export type StatusPageRenderer = (error: unknown, ctx: HttpContext) => Promise<string> | string
+
+/** A constructor usable in `instanceof` for {@link ExceptionHandler.ignoreExceptions}. */
+export type ExceptionClass = new (...args: never[]) => Error
+
+/** Reporting log level, keyed to `console` (AdonisJS levels: error/warn/info). */
+type LogLevel = 'error' | 'warn' | 'info'
+
+export class ExceptionHandler extends Macroable {
   protected debug: boolean
+  /** Render `statusPages` (browser HTML). Defaults to production only (AdonisJS). */
+  protected renderStatusPages: boolean = process.env.NODE_ENV === 'production'
+  /** Status → HTML renderer, keys may be single codes or `'500..599'` ranges. */
+  protected statusPages: Record<string, StatusPageRenderer> = {}
+  /** Master reporting switch (AdonisJS `reportErrors`). */
+  protected reportErrors = true
   protected ignoreStatuses: number[] = [400, 401, 404, 422]
   protected ignoreCodes: string[] = []
+  /** Exception classes never reported (AdonisJS `ignoreExceptions`). */
+  protected ignoreExceptions: ExceptionClass[] = []
+
+  #expandedStatusPages?: Record<number, StatusPageRenderer>
 
   constructor(debug = false) {
+    super()
     this.debug = debug
   }
 
+  /** Whether debug detail is exposed for this request (AdonisJS — override per-ctx). */
+  protected isDebuggingEnabled(_ctx: HttpContext): boolean {
+    return this.debug
+  }
+
+  /** Log level for an error by status: 5xx→error, 4xx→warn, else info (AdonisJS). */
+  protected getErrorLogLevel(status: number): LogLevel {
+    if (status >= 500) return 'error'
+    if (status >= 400) return 'warn'
+    return 'info'
+  }
+
+  /** Whether an error should be reported — honours every ignore list (AdonisJS `shouldReport`). */
+  protected shouldReport(error: unknown): boolean {
+    if (!this.reportErrors) return false
+    const { status, code } = extractErrorMeta(error)
+    if (this.ignoreStatuses.includes(status)) return false
+    if (this.ignoreCodes.includes(code)) return false
+    if (this.ignoreExceptions.some((exception) => error instanceof exception)) return false
+    return true
+  }
+
+  /** Expand `statusPages` range keys (`'500..599'`) into a per-code lookup (cached). */
+  #expandStatusPages(): Record<number, StatusPageRenderer> {
+    if (!this.#expandedStatusPages) {
+      const expanded: Record<number, StatusPageRenderer> = {}
+      for (const range of Object.keys(this.statusPages)) {
+        Object.assign(expanded, parseStatusRange(range, this.statusPages[range]))
+      }
+      this.#expandedStatusPages = expanded
+    }
+    return this.#expandedStatusPages
+  }
+
   /** Convert an exception to an HTTP response. */
   async handle(error: unknown, ctx: HttpContext): Promise<void> {
-    // Self-handled exceptions take over entirely.
-    if (error instanceof Exception && typeof error.handle === 'function') {
+    // Self-handled errors take over entirely (duck-typed, per AdonisJS — any
+    // thrown value exposing a `handle()` method, not just `Exception` instances).
+    if (isSelfHandling(error)) {
       await error.handle(error, ctx)
       return
     }
 
-    const { status, code } = extractErrorMeta(error)
-    const message = this.#errorMessage(error)
-    if (wantsJson(ctx)) {
-      this.#sendJsonError(ctx, status, code, message, error)
-    } else {
-      this.#sendHtmlError(ctx, status, message)
+    // Negotiation. DEVIATION (named): ream lists `json` FIRST, so a request
+    // with no/`*/*` Accept defaults to JSON (API-first). AdonisJS lists `html`
+    // first (full-stack default). Explicit `text/html` / `vnd.api+json` are
+    // honoured identically.
+    switch (ctx.request.accepts(['json', 'html', 'application/vnd.api+json'])) {
+      case 'application/vnd.api+json':
+        this.#sendJsonApiError(error, ctx)
+        return
+      case 'html':
+        await this.#sendHtmlError(error, ctx)
+        return
+      default:
+        this.#sendJsonError(error, ctx)
     }
   }
 
   /** Pick the user-facing message — full detail only in debug mode. */
-  #errorMessage(error: unknown): string {
-    if (this.debug && error instanceof Error) return error.message
+  #errorMessage(error: unknown, ctx: HttpContext): string {
+    if (this.isDebuggingEnabled(ctx) && error instanceof Error) return error.message
     if (error instanceof Exception) return error.message
     return 'An internal error occurred'
   }
 
-  #sendJsonError(
-    ctx: HttpContext,
-    status: number,
-    code: string,
-    message: string,
-    error: unknown,
-  ): void {
-    const errorPayload: Record<string, unknown> = { code, message }
-    if (this.debug && error instanceof Error && error.stack) {
-      errorPayload.stack = error.stack
+  #sendJsonError(error: unknown, ctx: HttpContext): void {
+    const { status, code } = extractErrorMeta(error)
+    const payload: Record<string, unknown> = { code, message: this.#errorMessage(error, ctx) }
+    if (error instanceof Exception && error.help) payload.help = error.help
+    if (this.isDebuggingEnabled(ctx) && error instanceof Error && error.stack) {
+      payload.stack = error.stack
     }
-    ctx.response.status(status).json({ error: errorPayload })
+    ctx.response.status(status).json({ error: payload })
   }
 
-  #sendHtmlError(ctx: HttpContext, status: number, message: string): void {
+  #sendJsonApiError(error: unknown, ctx: HttpContext): void {
+    const { status, code } = extractErrorMeta(error)
+    ctx.response
+      .status(status)
+      .type('application/vnd.api+json')
+      .json({ errors: [{ title: this.#errorMessage(error, ctx), code, status: String(status) }] })
+  }
+
+  async #sendHtmlError(error: unknown, ctx: HttpContext): Promise<void> {
+    const { status } = extractErrorMeta(error)
+    // A registered status page wins (production browser error pages).
+    if (this.renderStatusPages) {
+      const renderer = this.#expandStatusPages()[status]
+      if (renderer) {
+        const html = await renderer(error, ctx)
+        ctx.response.status(status).type('text/html; charset=utf-8').send(html)
+        return
+      }
+    }
+    const message = this.#errorMessage(error, ctx)
     ctx.response
       .status(status)
       .type('text/html; charset=utf-8')
@@ -209,23 +357,22 @@ export class ExceptionHandler {
 
   /** Log/report an exception. Override for custom monitoring. */
   async report(error: unknown, ctx: HttpContext): Promise<void> {
-    if (error instanceof Exception) {
-      if (this.ignoreStatuses.includes(error.status)) return
-      if (this.ignoreCodes.includes(error.code)) return
-    }
+    if (!this.shouldReport(error)) return
 
-    // Self-reported exceptions
-    if (error instanceof Exception && typeof error.report === 'function') {
+    // Self-reported exceptions handle their own reporting.
+    if (isSelfReporting(error)) {
       await error.report(error, ctx)
       return
     }
 
-    // Default: log to stderr
+    // Default: log at the status-appropriate level.
+    const { status } = extractErrorMeta(error)
+    const level = this.getErrorLogLevel(status)
     const context = this.context(ctx)
     if (error instanceof Error) {
-      console.error(`[${new Date().toISOString()}] ${error.message}`, context, error.stack)
+      console[level](`[${new Date().toISOString()}] ${error.message}`, context, error.stack)
     } else {
-      console.error(`[${new Date().toISOString()}] Unknown error:`, error, context)
+      console[level](`[${new Date().toISOString()}] Unknown error:`, error, context)
     }
   }
 
@@ -254,15 +401,45 @@ function extractErrorMeta(error: unknown): { status: number; code: string } {
   return { status, code }
 }
 
-/** Content negotiation: JSON unless the client explicitly prefers HTML. */
-function wantsJson(ctx: HttpContext): boolean {
+/** True when a thrown value self-handles via a `handle()` method (AdonisJS duck-type). */
+function isSelfHandling(
+  error: unknown,
+): error is { handle: (error: unknown, ctx: HttpContext) => Promise<void> | void } {
   return (
-    ctx.request.accepts(['json', 'html']) === 'json' ||
-    (ctx.request.header('accept')?.includes('application/json') ?? false) ||
-    !ctx.request.header('accept')?.includes('text/html')
+    error !== null &&
+    typeof error === 'object' &&
+    'handle' in error &&
+    typeof error.handle === 'function'
   )
 }
 
+/** True when a thrown value self-reports via a `report()` method. */
+function isSelfReporting(
+  error: unknown,
+): error is { report: (error: unknown, ctx: HttpContext) => Promise<void> | void } {
+  return (
+    error !== null &&
+    typeof error === 'object' &&
+    'report' in error &&
+    typeof error.report === 'function'
+  )
+}
+
+/** Expand a status-page key into a per-code map: `'500..599'` → {500,…,599}, `'404'` → {404}. */
+function parseStatusRange(
+  range: string,
+  renderer: StatusPageRenderer,
+): Record<number, StatusPageRenderer> {
+  const parts = range.split('..')
+  const min = Number(parts[0])
+  const max = Number(parts[1])
+  if (parts.length === 1 && !Number.isNaN(min)) return { [min]: renderer }
+  if (Number.isNaN(min) || Number.isNaN(max)) return {}
+  const result: Record<number, StatusPageRenderer> = {}
+  for (let status = min; status <= max; status += 1) result[status] = renderer
+  return result
+}
+
 function escapeHtml(str: string): string {
   return str
     .replace(/&/g, '&amp;')

package/src/http/HttpContext.ts

@@ -10,7 +10,10 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
 import type { ServiceToken } from '../container/types.js'
 import type { Emitter } from '../events/Emitter.js'
+import type { CookieSigner } from '../security/CookieSigner.js'
+import type { SignedUrl } from '../security/SignedUrl.js'
 import type { Session } from '../session/Session.js'
+import { Macroable } from '../utils/Macroable.js'
 import type { RouteUrlResolver } from './RedirectBuilder.js'
 import { RedirectBuilder } from './RedirectBuilder.js'
 import type { RawRequest } from './Request.js'
@@ -18,7 +21,12 @@ import { Request } from './Request.js'
 import { Response } from './Response.js'
 
 export interface AuthState {
-  authenticated: boolean
+  /**
+   * Whether the request carries an authenticated user (AdonisJS `auth.isAuthenticated`
+   * parity, renamed from `authenticated`). Always present — Ream defaults it to
+   * `false`; an auth provider (e.g. `@c9up/warden`'s Authenticator) sets it true.
+   */
+  isAuthenticated: boolean
   user?: {
     id: string
     email?: string
@@ -28,6 +36,19 @@ export interface AuthState {
   }
   roles?: string[]
   permissions?: string[]
+  /**
+   * Optional AdonisJS `Authenticator` surface — present when an auth provider
+   * (Warden) fills the slot with a per-request authenticator, absent for the
+   * bare `{ isAuthenticated: false }` default. Methods are OPTIONAL so Ream stays
+   * agnostic: a non-Warden host, or the default state, remains a valid AuthState.
+   */
+  authenticate?(): Promise<void>
+  check?(): Promise<boolean>
+  authenticateUsing?(guards?: string[], options?: { loginRoute?: string }): Promise<void>
+  getUserOrFail?(): AuthState['user']
+  use?(name: string): unknown
+  readonly authenticationAttempted?: boolean
+  readonly authenticatedViaGuard?: string
 }
 
 /**
@@ -65,8 +86,8 @@ export interface Authorizer {
 // declares its own structurally-compatible interface to stay decoupled (same
 // pattern as warden/blackhole middleware), so nothing cross-imports it.
 interface ContainerResolver {
-  /** Resolve/construct a service by token (class, string, or symbol). */
-  make<T>(token: ServiceToken): T
+  /** Resolve/construct a service by token (class, string, or symbol). Async (AdonisJS parity). */
+  make<T>(token: ServiceToken): Promise<T>
 }
 
 /**
@@ -84,7 +105,7 @@ export interface ContextLogger {
 }
 
 /** A logger that can spawn a request-scoped child (e.g. spectrum's `child()`). */
-interface ChildLoggerSource extends ContextLogger {
+export interface ChildLoggerSource extends ContextLogger {
   child?(options: { correlationId?: string; module?: string }): ContextLogger
 }
 
@@ -104,17 +125,16 @@ function consoleLogger(correlationId: string): ContextLogger {
   }
 }
 
-/** Resolve a request-scoped logger from the container, or fall back to console. */
+/**
+ * Build a request-scoped logger from the app's base logger, or fall back to
+ * console. The base logger is resolved (async) once by HttpKernel and injected
+ * via {@link HttpContext.setBaseLogger}; child-scoping here stays synchronous
+ * so `ctx.logger` remains a plain getter.
+ */
 function resolveRequestLogger(
-  resolver: ContainerResolver | undefined,
+  base: ChildLoggerSource | undefined,
   correlationId: string,
 ): ContextLogger {
-  let base: ChildLoggerSource | undefined
-  try {
-    base = resolver?.make<ChildLoggerSource>('logger')
-  } catch {
-    base = undefined
-  }
   if (!base) return consoleLogger(correlationId)
   return typeof base.child === 'function' ? base.child({ correlationId }) : base
 }
@@ -138,7 +158,7 @@ export interface RouteInfo {
 /** Ambient per-request context store (AdonisJS `HttpContext` ALS accessor). */
 const httpContextStorage = new AsyncLocalStorage<HttpContext>()
 
-export class HttpContext {
+export class HttpContext extends Macroable {
   /**
    * @internal Run `fn` with `ctx` as the ambient HttpContext, so code deep in
    * the call stack can reach it via {@link HttpContext.get}/{@link getOrFail}
@@ -165,6 +185,15 @@ export class HttpContext {
     return ctx
   }
 
+  /**
+   * Run `fn` with the ambient HttpContext temporarily cleared (AdonisJS
+   * `HttpContext.runOutsideContext`) — e.g. to detach background work so it
+   * doesn't inherit and pin the request's context.
+   */
+  static runOutsideContext<T>(fn: () => T): T {
+    return httpContextStorage.exit(fn)
+  }
+
   /** Unique request/correlation ID. */
   readonly id: string
 
@@ -181,7 +210,7 @@ export class HttpContext {
   readonly route: RouteInfo
 
   /** Authentication state — populated by auth middleware. */
-  auth: AuthState = { authenticated: false }
+  auth: AuthState = { isAuthenticated: false }
 
   /**
    * Request locale — the primary subtag of the first `Accept-Language` entry
@@ -227,21 +256,50 @@ export class HttpContext {
   /** Lazily-built per-request logger (see {@link logger}). */
   #logger?: ContextLogger
 
+  /** App base logger, resolved once (async) by HttpKernel and injected. */
+  #baseLogger?: ChildLoggerSource
+
   /** Route URL resolver for redirect().toRoute(). */
   #routeUrlResolver?: RouteUrlResolver
 
   /**
-   * Per-request logger (AdonisJS `ctx.logger`). Resolves the container `'logger'`
-   * (e.g. `@c9up/spectrum`) child-scoped to this request's `id`, or falls back to
-   * a console logger when none is registered. Built once, on first access.
+   * Per-request logger (AdonisJS `ctx.logger`) — the injected app logger (e.g.
+   * `@c9up/spectrum`) child-scoped to this request's `id`, or a console logger
+   * when none is registered. Built once, on first access.
    */
   get logger(): ContextLogger {
     if (!this.#logger) {
-      this.#logger = resolveRequestLogger(this.containerResolver, this.id)
+      this.#logger = resolveRequestLogger(this.#baseLogger, this.id)
     }
     return this.#logger
   }
 
+  /** @internal Inject the app base logger (resolved async by HttpKernel). */
+  setBaseLogger(logger: ChildLoggerSource): void {
+    this.#baseLogger = logger
+  }
+
+  /** @internal Inject the APP_KEY cookie signer into request + response (from HttpKernel). */
+  setCookieSigner(signer: CookieSigner): void {
+    this.response.setCookieSigner(signer)
+    this.request.setCookieSigner(signer)
+  }
+
+  /** @internal Inject the APP_KEY signed-URL helper into the request (from HttpKernel). */
+  setSignedUrl(signedUrl: SignedUrl): void {
+    this.request.setSignedUrl(signedUrl)
+  }
+
+  /** Subdomains of the request host (AdonisJS `ctx.subdomains`). */
+  get subdomains(): string[] {
+    return this.request.subdomains()
+  }
+
+  /** Stable identifier for the matched route (`METHOD-pattern`) — AdonisJS `ctx.routeKey`. */
+  get routeKey(): string {
+    return `${this.request.method()}-${this.route.pattern}`
+  }
+
   constructor(
     id: string,
     rawRequest: RawRequest,
@@ -249,12 +307,23 @@ export class HttpContext {
     route: RouteInfo,
     containerResolver?: ContainerResolver,
   ) {
+    super()
     this.id = id
     this.params = params
     this.route = route
     this.containerResolver = containerResolver
     this.request = new Request(rawRequest, params)
     this.response = new Response()
+    // Give the response read access to the request (AdonisJS wires them too) —
+    // needed by `response.fresh()` for conditional-GET / ETag revalidation.
+    this.response.setRequest(this.request)
+    // 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 })
+    // 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).
     this.locale = parseAcceptLanguage(this.request.header('accept-language')) ?? 'en'
 
     // Wire redirect builder with request context

package/src/http/RedirectBuilder.ts

@@ -14,7 +14,10 @@ import type { Response } from './Response.js'
 export type RouteUrlResolver = (name: string, params?: Record<string, string>) => string
 
 function isSameOriginOrRelative(referer: string, requestUrl?: string): boolean {
-  if (referer.startsWith('/') && !referer.startsWith('//')) return true
+  // A relative path is trusted only when it starts with a single "/" and has no
+  // backslash: browsers normalise "\" to "/", so "/\evil.com" would become the
+  // protocol-relative "//evil.com" that a lone `!startsWith("//")` check misses.
+  if (referer.startsWith('/') && !referer.startsWith('//') && !referer.includes('\\')) return true
   if (!requestUrl) return false
   try {
     const ref = new URL(referer)