@adonisjs/http-server 6.8.2-4 → 6.8.2-5

package/src/exception_handler.ts

@@ -0,0 +1,290 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import is from '@sindresorhus/is'
+import type { Level } from '@adonisjs/logger/types'
+
+import { parseRange } from './helpers.js'
+import * as errors from './exceptions.js'
+import type { HttpContext } from './http_context/main.js'
+import type { HttpError, StatusPageRange, StatusPageRenderer } from './types/server.js'
+
+/**
+ * The base HTTP exception handler one can inherit from to handle
+ * HTTP exceptions.
+ *
+ * The HTTP exception handler has support for
+ *
+ * - Ability to render exceptions by calling the render method on the exception.
+ * - Rendering status pages
+ * - Pretty printing errors during development
+ * - Transforming errors to JSON or HTML using content negotiation
+ * - Reporting errors
+ */
+export class ExceptionHandler {
+  /**
+   * Whether or not to render debug info. When set to true, the errors
+   * will have the complete error stack.
+   */
+  protected debug: boolean = process.env.NODE_ENV !== 'production'
+
+  /**
+   * Whether or not to render status pages. When set to true, the unhandled
+   * errors with matching status codes will be rendered using a status
+   * page.
+   */
+  protected renderStatusPages: boolean = process.env.NODE_ENV === 'production'
+
+  /**
+   * A collection of error status code range and the view to render.
+   */
+  protected statusPages: Record<StatusPageRange, StatusPageRenderer> = {}
+
+  /**
+   * Computed from the status pages property
+   */
+  #expandedStatusPages?: Record<number, StatusPageRenderer>
+
+  /**
+   * Renderers for rendering an error.
+   */
+  protected renderers: {
+    html: (error: HttpError, ctx: HttpContext) => Promise<void>
+    json: (error: HttpError, ctx: HttpContext) => Promise<void>
+    json_api: (error: HttpError, ctx: HttpContext) => Promise<void>
+  } = {
+    html: async (error: HttpError, ctx: HttpContext) => {
+      if (this.isDebuggingEnabled(ctx)) {
+        const { default: Youch } = await import('youch')
+        const html = await new Youch(error, ctx.request.request).toHTML()
+        ctx.response.status(error.status).send(html)
+
+        return
+      }
+
+      ctx.response.status(error.status).send(`<p> ${error.message} </p>`)
+    },
+
+    json: async (error: HttpError, ctx: HttpContext) => {
+      if (this.isDebuggingEnabled(ctx)) {
+        const { default: Youch } = await import('youch')
+        const json = await new Youch(error, ctx.request.request).toJSON()
+        ctx.response.status(error.status).send(json.error)
+
+        return
+      }
+
+      ctx.response.status(error.status).send({ message: error.message })
+    },
+
+    json_api: async (error: HttpError, ctx: HttpContext) => {
+      if (this.isDebuggingEnabled(ctx)) {
+        const { default: Youch } = await import('youch')
+        const json = await new Youch(error, ctx.request.request).toJSON()
+        ctx.response.status(error.status).send(json.error)
+
+        return
+      }
+
+      ctx.response.status(error.status).send({
+        errors: [
+          {
+            title: error.message,
+            code: error.code,
+            status: error.status,
+          },
+        ],
+      })
+    },
+  }
+
+  /**
+   * Enable/disable errors reporting
+   */
+  protected reportErrors: boolean = true
+
+  /**
+   * An array of exception classes to ignore when
+   * reporting an error
+   */
+  protected ignoreExceptions: any[] = [
+    errors.E_HTTP_EXCEPTION,
+    errors.E_ROUTE_NOT_FOUND,
+    errors.E_CANNOT_LOOKUP_ROUTE,
+    errors.E_HTTP_REQUEST_ABORTED,
+  ]
+
+  /**
+   * An array of HTTP status codes to ignore when reporting
+   * an error
+   */
+  protected ignoreStatuses: number[] = [400, 422, 401]
+
+  /**
+   * An array of error codes to ignore when reporting
+   * an error
+   */
+  protected ignoreCodes: string[] = []
+
+  /**
+   * Expands status pages
+   */
+  #expandStatusPages() {
+    if (!this.#expandedStatusPages) {
+      this.#expandedStatusPages = Object.keys(this.statusPages).reduce((result, range) => {
+        const renderer = this.statusPages[range as StatusPageRange]
+        result = Object.assign(result, parseRange(range, renderer))
+        return result
+      }, {} as Record<number, StatusPageRenderer>)
+    }
+
+    return this.#expandedStatusPages
+  }
+
+  /**
+   * Forcefully tweaking the type of the error object to
+   * have known properties.
+   */
+  #toHttpError(error: unknown): HttpError {
+    const httpError: any = is.object(error) ? error : new Error(String(error))
+    httpError.message = httpError.message || 'Internal server error'
+    httpError.status = httpError.status || 500
+    return httpError
+  }
+
+  /**
+   * Error reporting context
+   */
+  protected context(ctx: HttpContext): any {
+    const requestId = ctx.request.id()
+    return requestId
+      ? {
+          'x-request-id': requestId,
+        }
+      : {}
+  }
+
+  /**
+   * The format in which the error should be rendered.
+   */
+  protected getResponseFormat(ctx: HttpContext): 'html' | 'json' | 'json_api' {
+    switch (ctx.request.accepts(['html', 'application/vnd.api+json', 'json'])) {
+      case 'application/vnd.api+json':
+        return 'json_api'
+      case 'json':
+        return 'json'
+      case 'html':
+      default:
+        return 'html'
+    }
+  }
+
+  /**
+   * Returns the log level for an error based upon the error
+   * status code.
+   */
+  protected getErrorLogLevel(error: HttpError): Level {
+    if (error.status >= 500) {
+      return 'error'
+    }
+
+    if (error.status >= 400) {
+      return 'warn'
+    }
+
+    return 'info'
+  }
+
+  /**
+   * A boolean to control if errors should be rendered with
+   * all the available debugging info.
+   */
+  protected isDebuggingEnabled(_: HttpContext): boolean {
+    return this.debug
+  }
+
+  /**
+   * Returns a boolean by checking if an error should be reported.
+   */
+  protected shouldReport(error: HttpError): boolean {
+    if (this.reportErrors === false) {
+      return false
+    }
+
+    if (this.ignoreStatuses.includes(error.status)) {
+      return false
+    }
+
+    if (error.code && this.ignoreCodes.includes(error.code)) {
+      return false
+    }
+
+    if (this.ignoreExceptions.find((exception) => error instanceof exception)) {
+      return false
+    }
+
+    return true
+  }
+
+  /**
+   * Reports an error during an HTTP request
+   */
+  async report(error: unknown, ctx: HttpContext) {
+    const httpError = this.#toHttpError(error)
+    if (!this.shouldReport(httpError)) {
+      return
+    }
+
+    if (typeof httpError.report === 'function') {
+      httpError.report(httpError, ctx)
+      return
+    }
+
+    /**
+     * Log the error using the logger
+     */
+    const level = this.getErrorLogLevel(httpError)
+    ctx.logger.log(
+      level,
+      {
+        ...(level === 'error' || level === 'fatal' ? { err: httpError } : {}),
+        ...this.context(ctx),
+      },
+      httpError.message
+    )
+  }
+
+  /**
+   * Handles the error during the HTTP request.
+   */
+  async handle(error: unknown, ctx: HttpContext) {
+    const httpError = this.#toHttpError(error)
+
+    /**
+     * Self handle exception
+     */
+    if (typeof httpError.handle === 'function') {
+      return httpError.handle(httpError, ctx)
+    }
+
+    /**
+     * Render status page
+     */
+    const statusPages = this.#expandStatusPages()
+    if (this.renderStatusPages && statusPages[httpError.status]) {
+      return statusPages[httpError.status](httpError, ctx)
+    }
+
+    /**
+     * Use the format renderers.
+     */
+    const responseFormat = this.getResponseFormat(ctx)
+    return this.renderers[responseFormat](httpError, ctx)
+  }
+}

package/src/exceptions.ts

@@ -0,0 +1,55 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { createError, Exception } from '@poppinss/utils'
+import type { HttpContext } from './http_context/main.js'
+
+export const E_ROUTE_NOT_FOUND = createError<[method: string, url: string]>(
+  'Cannot %s:%s',
+  'E_ROUTE_NOT_FOUND',
+  404
+)
+
+export const E_CANNOT_LOOKUP_ROUTE = createError<[routeIdentifier: string]>(
+  'Cannot lookup route "%s"',
+  'E_CANNOT_LOOKUP_ROUTE',
+  500
+)
+
+export const E_HTTP_EXCEPTION = class HttpException extends Exception {
+  body: any
+  static code = 'E_HTTP_EXCEPTION'
+
+  /**
+   * This method returns an instance of the exception class
+   */
+  static invoke(body: any, status: number, code: string = 'E_HTTP_EXCEPTION'): HttpException {
+    if (body === null || body === undefined) {
+      const error = new this('HTTP Exception', { status, code })
+      error.body = 'Internal server error'
+      return error
+    }
+
+    if (typeof body === 'object') {
+      const error = new this(body.message || 'HTTP Exception', { status, code })
+      error.body = body
+      return error
+    }
+
+    const error = new this(body, { status, code })
+    error.body = body
+    return error
+  }
+}
+
+export const E_HTTP_REQUEST_ABORTED = class AbortException extends E_HTTP_EXCEPTION {
+  handle(error: AbortException, ctx: HttpContext) {
+    ctx.response.status(error.status).send(error.body)
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,108 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import Cache from 'tmp-cache'
+import { InvalidArgumentsException } from '@poppinss/utils'
+
+import { Route } from './router/route.js'
+import { BriskRoute } from './router/brisk.js'
+import { RouteGroup } from './router/group.js'
+import type { RouteJSON } from './types/route.js'
+import { RouteResource } from './router/resource.js'
+
+const proxyCache = new Cache({ max: 200 })
+
+/**
+ * Makes input string consistent by having only the starting
+ * slash
+ */
+export function dropSlash(input: string): string {
+  if (input === '/') {
+    return '/'
+  }
+
+  return `/${input.replace(/^\//, '').replace(/\/$/, '')}`
+}
+
+/**
+ * Returns a flat list of routes from the route groups and resources
+ */
+export function toRoutesJSON(
+  routes: (RouteGroup | Route | RouteResource | BriskRoute)[]
+): RouteJSON[] {
+  return routes.reduce((list: RouteJSON[], route) => {
+    if (route instanceof RouteGroup) {
+      list = list.concat(toRoutesJSON(route.routes))
+      return list
+    }
+
+    if (route instanceof RouteResource) {
+      list = list.concat(toRoutesJSON(route.routes))
+      return list
+    }
+
+    if (route instanceof BriskRoute) {
+      if (route.route && !route.route.isDeleted()) {
+        list.push(route.route.toJSON())
+      }
+      return list
+    }
+
+    if (!route.isDeleted()) {
+      list.push(route.toJSON())
+    }
+
+    return list
+  }, [])
+}
+
+/**
+ * Helper to know if the remote address should
+ * be trusted.
+ */
+export function trustProxy(
+  remoteAddress: string,
+  proxyFn: (addr: string, distance: number) => boolean
+): boolean {
+  if (proxyCache.has(remoteAddress)) {
+    return proxyCache.get(remoteAddress) as boolean
+  }
+
+  const result = proxyFn(remoteAddress, 0)
+  proxyCache.set(remoteAddress, result)
+  return result
+}
+
+/**
+ * Parses a range expression to an object filled with the range
+ */
+export function parseRange<T>(range: string, value: T): Record<number, T> {
+  const parts = range.split('..')
+  const min = Number(parts[0])
+  const max = Number(parts[1])
+
+  if (Number.isNaN(min) || Number.isNaN(max)) {
+    return {}
+  }
+
+  if (min === max) {
+    return {
+      [min]: value,
+    }
+  }
+
+  if (max < min) {
+    throw new InvalidArgumentsException(`Invalid range "${range}"`)
+  }
+
+  return [...Array(max - min + 1).keys()].reduce((result, step) => {
+    result[min + step] = value
+    return result
+  }, {} as Record<number, T>)
+}

package/src/http_context/local_storage.ts

@@ -0,0 +1,50 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { HttpContext } from './main.js'
+
+/**
+ * Async local storage for HTTP context
+ */
+export const asyncLocalStorage: {
+  isEnabled: boolean
+  storage: null | AsyncLocalStorage<HttpContext>
+  create(): AsyncLocalStorage<HttpContext>
+  destroy(): void
+} = {
+  /**
+   * Check if the async local storage for the HTTP
+   * context is enabled or not
+   */
+  isEnabled: false,
+
+  /**
+   * HTTP context storage instance for the current scope
+   */
+  storage: null,
+
+  /**
+   * Create the storage instance. This method must be called only
+   * once.
+   */
+  create() {
+    this.isEnabled = true
+    this.storage = new AsyncLocalStorage<HttpContext>()
+    return this.storage
+  },
+
+  /**
+   * Destroy the create storage instance
+   */
+  destroy() {
+    this.isEnabled = false
+    this.storage = null
+  },
+}

package/src/http_context/main.ts

@@ -0,0 +1,126 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { inspect } from 'node:util'
+import Macroable from '@poppinss/macroable'
+import type { Logger } from '@adonisjs/logger'
+import { RuntimeException } from '@poppinss/utils'
+import { ContainerResolver } from '@adonisjs/fold'
+
+import type { Request } from '../request.js'
+import type { Response } from '../response.js'
+import { asyncLocalStorage } from './local_storage.js'
+import type { StoreRouteNode } from '../types/route.js'
+
+/**
+ * Http context encapsulates properties for a given HTTP request. The
+ * context class can be extended using macros and getters.
+ */
+export class HttpContext extends Macroable {
+  /**
+   * Find if async localstorage is enabled for HTTP requests
+   * or not
+   */
+  static get usingAsyncLocalStorage() {
+    return asyncLocalStorage.isEnabled
+  }
+
+  /**
+   * Get access to the HTTP context. Available only when
+   * "usingAsyncLocalStorage" is true
+   */
+  static get(): HttpContext | null {
+    if (!this.usingAsyncLocalStorage || !asyncLocalStorage.storage) {
+      return null
+    }
+
+    return asyncLocalStorage.storage.getStore() || null
+  }
+
+  /**
+   * Get the HttpContext instance or raise an exception if not
+   * available
+   */
+  static getOrFail(): HttpContext {
+    /**
+     * Localstorage is not enabled
+     */
+    if (!this.usingAsyncLocalStorage || !asyncLocalStorage.storage) {
+      throw new RuntimeException(
+        'HTTP context is not available. Enable "useAsyncLocalStorage" inside "config/app.ts" file'
+      )
+    }
+
+    const store = this.get()
+    if (!store) {
+      throw new RuntimeException('Http context is not available outside of an HTTP request')
+    }
+
+    return store
+  }
+
+  /**
+   * Run a method that doesn't have access to HTTP context from
+   * the async local storage.
+   */
+  static runOutsideContext<T>(callback: (...args: any[]) => T, ...args: any[]): T {
+    if (!asyncLocalStorage.storage) {
+      return callback(...args)
+    }
+
+    return asyncLocalStorage.storage.exit(callback, ...args)
+  }
+
+  /**
+   * Reference to the current route. Not available inside
+   * server middleware
+   */
+  route?: StoreRouteNode
+
+  /**
+   * A unique key for the current route
+   */
+  routeKey?: string
+
+  /**
+   * Route params
+   */
+  params: Record<string, any> = {}
+
+  /**
+   * Route subdomains
+   */
+  subdomains: Record<string, any> = {}
+
+  constructor(
+    public request: Request,
+    public response: Response,
+    public logger: Logger,
+    public containerResolver: ContainerResolver<any>
+  ) {
+    super()
+
+    /*
+     * Creating the circular reference. We do this, since request and response
+     * are meant to be extended and at times people would want to access
+     * other ctx properties like `logger`, `profiler` inside those
+     * extended methods.
+     */
+    this.request.ctx = this
+    this.response.ctx = this
+  }
+
+  /**
+   * A helper to see top level properties on the context object
+   */
+  /* c8 ignore next 3 */
+  inspect() {
+    return inspect(this, false, 1, true)
+  }
+}

package/src/qs.ts

@@ -0,0 +1,31 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { parse, stringify } from 'qs'
+import { QSParserConfig } from './types/qs.js'
+
+/**
+ * Query string parser used to parse and stringify query
+ * strings.
+ */
+export class Qs {
+  #config: QSParserConfig
+
+  constructor(config: QSParserConfig) {
+    this.#config = config
+  }
+
+  parse(value: string) {
+    return parse(value, this.#config.parse)
+  }
+
+  stringify(value: any) {
+    return stringify(value, this.#config.stringify)
+  }
+}