@c9up/ream 0.1.3

package/src/http/Exception.ts

@@ -0,0 +1,272 @@
+/**
+ * Exception system — AdonisJS-compatible exception handling.
+ *
+ * - Exception: base class with self-handling support
+ * - ExceptionHandler: global exception handler with content negotiation
+ * - Built-in E_* exceptions
+ */
+
+import type { HttpContext } from './HttpContext.js'
+
+/**
+ * Base exception class. Extend this to create self-handling exceptions.
+ *
+ * Usage:
+ *   throw new Exception('Something went wrong', { status: 400, code: 'E_BAD_REQUEST' })
+ *
+ * Self-handled exception:
+ *   class PaymentFailed extends Exception {
+ *     static status = 402
+ *     static code = 'E_PAYMENT_FAILED'
+ *     async handle(error: this, ctx: HttpContext) {
+ *       ctx.response.status(402).json({ error: 'Payment failed' })
+ *     }
+ *     async report(error: this, ctx: HttpContext) {
+ *       logger.error('Payment failed', { userId: ctx.auth.user?.id })
+ *     }
+ *   }
+ */
+export class Exception extends Error {
+  static status = 500
+  static code = 'E_UNKNOWN'
+
+  status: number
+  code: string
+
+  constructor(message: string, options?: { status?: number; code?: string }) {
+    super(message)
+    this.name = this.constructor.name
+    // biome-ignore lint/suspicious/noExplicitAny: this.constructor is typed as Function; subclass pattern requires the cast
+    const ctor = this.constructor as any as typeof Exception
+    this.status = options?.status ?? ctor.status
+    this.code = options?.code ?? ctor.code
+  }
+
+  /** Override to self-handle the exception (convert to HTTP response). */
+  handle?(error: this, ctx: HttpContext): Promise<void> | void
+
+  /** Override to report the exception (logging, monitoring). Never send HTTP from here. */
+  report?(error: this, ctx: HttpContext): Promise<void> | void
+}
+
+// ─── Built-in exceptions ──────────────────────────────────
+
+export class E_ROUTE_NOT_FOUND extends Exception {
+  static override status = 404
+  static override code = 'E_ROUTE_NOT_FOUND'
+
+  constructor(method: string, path: string) {
+    super(`Route not found: ${method} ${path}`, { status: 404, code: 'E_ROUTE_NOT_FOUND' })
+  }
+}
+
+export class E_UNAUTHORIZED extends Exception {
+  static override status = 401
+  static override code = 'E_UNAUTHORIZED'
+
+  constructor(message = 'Authentication required') {
+    super(message, { status: 401, code: 'E_UNAUTHORIZED' })
+  }
+
+  override handle(_error: this, ctx: HttpContext): void {
+    ctx.response.status(401).json({ error: { code: 'E_UNAUTHORIZED', message: this.message } })
+  }
+}
+
+export class E_FORBIDDEN extends Exception {
+  static override status = 403
+  static override code = 'E_FORBIDDEN'
+
+  required?: string[]
+
+  constructor(message = 'Insufficient permissions', required?: string[]) {
+    super(message, { status: 403, code: 'E_FORBIDDEN' })
+    this.required = required
+  }
+
+  override handle(_error: this, ctx: HttpContext): void {
+    ctx.response.status(403).json({
+      error: {
+        code: 'E_FORBIDDEN',
+        message: this.message,
+        ...(this.required ? { required: this.required } : {}),
+      },
+    })
+  }
+}
+
+export class E_VALIDATION_ERROR extends Exception {
+  static override status = 422
+  static override code = 'E_VALIDATION_ERROR'
+
+  errors: unknown[]
+
+  constructor(errors: unknown[]) {
+    super('Validation failed', { status: 422, code: 'E_VALIDATION_ERROR' })
+    this.errors = errors
+  }
+
+  override handle(_error: this, ctx: HttpContext): void {
+    ctx.response.status(422).json({ errors: this.errors })
+  }
+}
+
+export class E_ROW_NOT_FOUND extends Exception {
+  static override status = 404
+  static override code = 'E_ROW_NOT_FOUND'
+
+  constructor(model?: string) {
+    super(model ? `${model} not found` : 'Resource not found', {
+      status: 404,
+      code: 'E_ROW_NOT_FOUND',
+    })
+  }
+
+  override handle(_error: this, ctx: HttpContext): void {
+    ctx.response.status(404).json({ error: { code: 'E_ROW_NOT_FOUND', message: this.message } })
+  }
+}
+
+export class E_HTTP_EXCEPTION extends Exception {
+  constructor(message: string, status: number) {
+    super(message, { status, code: 'E_HTTP_EXCEPTION' })
+  }
+}
+
+// ─── ExceptionHandler ─────────────────────────────────────
+
+/**
+ * Global exception handler — catches all unhandled exceptions and converts
+ * them to HTTP responses.
+ *
+ * Extend this in your app:
+ *   export default class Handler extends ExceptionHandler {
+ *     protected debug = app.inDev
+ *     protected ignoreStatuses = [400, 401, 404, 422]
+ *   }
+ *
+ * Flow:
+ * 1. If exception has handle() → self-handled (bypass global)
+ * 2. Else → this.handle() → content negotiation (JSON or HTML)
+ * 3. Then → this.report() → logging/monitoring
+ */
+export class ExceptionHandler {
+  protected debug: boolean
+  protected ignoreStatuses: number[] = [400, 401, 404, 422]
+  protected ignoreCodes: string[] = []
+
+  constructor(debug = false) {
+    this.debug = debug
+  }
+
+  /** 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') {
+      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)
+    }
+  }
+
+  /** Pick the user-facing message — full detail only in debug mode. */
+  #errorMessage(error: unknown): string {
+    if (this.debug && 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
+    }
+    ctx.response.status(status).json({ error: errorPayload })
+  }
+
+  #sendHtmlError(ctx: HttpContext, status: number, message: string): void {
+    ctx.response
+      .status(status)
+      .type('text/html; charset=utf-8')
+      .send(
+        `<!DOCTYPE html><html><head><title>Error ${status}</title></head>` +
+          `<body><h1>${status}</h1><p>${escapeHtml(message)}</p></body></html>`,
+      )
+  }
+
+  /** 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
+    }
+
+    // Self-reported exceptions
+    if (error instanceof Exception && typeof error.report === 'function') {
+      await error.report(error, ctx)
+      return
+    }
+
+    // Default: log to stderr
+    const context = this.context(ctx)
+    if (error instanceof Error) {
+      console.error(`[${new Date().toISOString()}] ${error.message}`, context, error.stack)
+    } else {
+      console.error(`[${new Date().toISOString()}] Unknown error:`, error, context)
+    }
+  }
+
+  /** Provide additional context for error reports. Override for custom data. */
+  protected context(ctx: HttpContext): Record<string, unknown> {
+    return {
+      requestId: ctx.id,
+      method: ctx.request.method(),
+      url: ctx.request.url(),
+      userId: ctx.auth.user?.id,
+    }
+  }
+}
+
+/** Extract status + code from an Exception, ReamError, or duck-typed error. */
+function extractErrorMeta(error: unknown): { status: number; code: string } {
+  let status = 500
+  let code = 'E_UNKNOWN'
+  if (error instanceof Exception) {
+    status = error.status
+    code = error.code
+  } else if (error !== null && typeof error === 'object') {
+    if ('status' in error && typeof error.status === 'number') status = error.status
+    if ('code' in error && typeof error.code === 'string') code = error.code
+  }
+  return { status, code }
+}
+
+/** Content negotiation: JSON unless the client explicitly prefers HTML. */
+function wantsJson(ctx: HttpContext): boolean {
+  return (
+    ctx.request.accepts(['json', 'html']) === 'json' ||
+    (ctx.request.header('accept')?.includes('application/json') ?? false) ||
+    !ctx.request.header('accept')?.includes('text/html')
+  )
+}
+
+function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}

package/src/http/HttpContext.ts

@@ -0,0 +1,108 @@
+/**
+ * HttpContext — fully typed HTTP context for handlers, middleware, and controllers.
+ *
+ * Replaces Context.http() for HTTP transport. Always has request + response (no ! assertions).
+ * Compatible with AdonisJS destructuring: { request, response, auth, params }
+ *
+ * @implements FR21
+ */
+
+import type { Emitter } from '../events/Emitter.js'
+import type { RouteUrlResolver } from './RedirectBuilder.js'
+import { RedirectBuilder } from './RedirectBuilder.js'
+import type { RawRequest } from './Request.js'
+import { Request } from './Request.js'
+import { Response } from './Response.js'
+
+export interface AuthState {
+  authenticated: boolean
+  user?: {
+    id: string
+    email?: string
+    roles?: string[]
+    permissions?: string[]
+    [key: string]: unknown
+  }
+  roles?: string[]
+  permissions?: string[]
+}
+
+export interface RouteInfo {
+  pattern: string
+  name?: string
+  middleware: string[]
+  /**
+   * Controller class + method that owns this route, when the route was
+   * registered as `router.get('/x', SomeController, 'method')` (vs an
+   * inline arrow handler). Middleware that reads decorator metadata —
+   * `@Guard`, `@Permission`, `@Role` (Warden), `@Meta` (Photon) —
+   * needs both fields. Absent when the route handler is an inline
+   * function. Populated by `HttpKernel` from `match.route.controller`.
+   */
+  controller?: object
+  action?: string
+}
+
+export class HttpContext {
+  /** Unique request/correlation ID. */
+  readonly id: string
+
+  /** Typed HTTP request. */
+  readonly request: Request
+
+  /** Typed HTTP response builder. */
+  readonly response: Response
+
+  /** Route parameters extracted from the URL pattern. */
+  readonly params: Record<string, string>
+
+  /** Information about the matched route. */
+  readonly route: RouteInfo
+
+  /** Authentication state — populated by auth middleware. */
+  auth: AuthState = { authenticated: false }
+
+  /** Detected locale. */
+  locale = 'en'
+
+  /** Per-request key-value store (for middleware to pass data downstream). */
+  readonly store: Map<string, unknown> = new Map()
+
+  /**
+   * The event bus emitter, when the app registered `EventsProvider`. Lets a
+   * handler emit/subscribe without resolving from the container:
+   * `ctx.events?.emit('user:updated', user)`. Undefined when events aren't wired.
+   */
+  events?: Emitter
+
+  /** Route URL resolver for redirect().toRoute(). */
+  #routeUrlResolver?: RouteUrlResolver
+
+  constructor(
+    id: string,
+    rawRequest: RawRequest,
+    params: Record<string, string>,
+    route: RouteInfo,
+  ) {
+    this.id = id
+    this.params = params
+    this.route = route
+    this.request = new Request(rawRequest, params)
+    this.response = new Response()
+
+    // Wire redirect builder with request context
+    this.response.setRedirectFactory(
+      () =>
+        new RedirectBuilder(this.response, {
+          requestUrl: this.request.url(),
+          requestReferer: this.request.header('referer'),
+          routeUrlResolver: this.#routeUrlResolver,
+        }),
+    )
+  }
+
+  /** @internal Set the route URL resolver (injected by HttpKernel from Router). */
+  setRouteUrlResolver(resolver: RouteUrlResolver): void {
+    this.#routeUrlResolver = resolver
+  }
+}

package/src/http/RedirectBuilder.ts

@@ -0,0 +1,89 @@
+/**
+ * RedirectBuilder — fluent API for building redirect responses.
+ *
+ * Usage:
+ *   response.redirect().toPath('/login')
+ *   response.redirect().status(301).toPath('/new-url')
+ *   response.redirect().back()
+ *   response.redirect().withQs({ page: '2' }).toPath('/results')
+ *   response.redirect().toRoute('posts.show', { id: '42' })
+ */
+
+import type { Response } from './Response.js'
+
+export type RouteUrlResolver = (name: string, params?: Record<string, string>) => string
+
+export class RedirectBuilder {
+  #response: Response
+  #status = 302
+  #qs: Record<string, string> | null = null
+  #forwardQs = false
+  #requestUrl?: string
+  #requestReferer?: string
+  #routeUrlResolver?: RouteUrlResolver
+
+  constructor(
+    response: Response,
+    options?: {
+      requestUrl?: string
+      requestReferer?: string
+      routeUrlResolver?: RouteUrlResolver
+    },
+  ) {
+    this.#response = response
+    this.#requestUrl = options?.requestUrl
+    this.#requestReferer = options?.requestReferer
+    this.#routeUrlResolver = options?.routeUrlResolver
+  }
+
+  /** Set redirect status code. */
+  status(code: number): this {
+    this.#status = code
+    return this
+  }
+
+  /** Forward current query string to the redirect target. */
+  withQs(qs?: Record<string, string>): this {
+    if (qs) {
+      this.#qs = qs
+    } else {
+      this.#forwardQs = true
+    }
+    return this
+  }
+
+  /** Redirect to an absolute or relative path. */
+  toPath(path: string): void {
+    const url = this.#appendQs(path)
+    this.#response.status(this.#status)
+    this.#response.header('location', url)
+    this.#response.setBody('')
+  }
+
+  /** Redirect to a named route. */
+  toRoute(name: string, params?: Record<string, string>): void {
+    if (!this.#routeUrlResolver) {
+      throw new Error('Route URL resolver not configured. Cannot redirect to named route.')
+    }
+    const path = this.#routeUrlResolver(name, params)
+    this.toPath(path)
+  }
+
+  /** Redirect back to the previous page (Referer header). */
+  back(fallback = '/'): void {
+    const referer = this.#requestReferer ?? fallback
+    this.toPath(referer)
+  }
+
+  #appendQs(path: string): string {
+    let qs = ''
+    if (this.#qs) {
+      qs = new URLSearchParams(this.#qs).toString()
+    } else if (this.#forwardQs && this.#requestUrl) {
+      const qsIdx = this.#requestUrl.indexOf('?')
+      if (qsIdx !== -1) qs = this.#requestUrl.slice(qsIdx + 1)
+    }
+    if (!qs) return path
+    return path.includes('?') ? `${path}&${qs}` : `${path}?${qs}`
+  }
+}