@adonisjs/http-server 6.8.2-1 → 6.8.2-11

package/build/src/exception_handler.js

@@ -1,57 +1,73 @@
+/*
+ * @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 { parseRange } from './helpers.js';
 import * as errors from './exceptions.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 {
+    /**
+     * Computed from the status pages property
+     */
+    #expandedStatusPages;
+    /**
+     * Whether or not to render debug info. When set to true, the errors
+     * will have the complete error stack.
+     */
     debug = 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.
+     */
     renderStatusPages = process.env.NODE_ENV === 'production';
+    /**
+     * A collection of error status code range and the view to render.
+     */
     statusPages = {};
-    #expandedStatusPages;
-    renderers = {
-        html: async (error, ctx) => {
-            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, ctx) => {
-            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, ctx) => {
-            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
+     */
     reportErrors = true;
+    /**
+     * An array of exception classes to ignore when
+     * reporting an error
+     */
     ignoreExceptions = [
         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
+     */
     ignoreStatuses = [400, 422, 401];
+    /**
+     * An array of error codes to ignore when reporting
+     * an error
+     */
     ignoreCodes = [];
+    /**
+     * Expands status pages
+     */
     #expandStatusPages() {
         if (!this.#expandedStatusPages) {
             this.#expandedStatusPages = Object.keys(this.statusPages).reduce((result, range) => {
@@ -62,12 +78,19 @@ export class ExceptionHandler {
         }
         return this.#expandedStatusPages;
     }
+    /**
+     * Forcefully tweaking the type of the error object to
+     * have known properties.
+     */
     #toHttpError(error) {
         const httpError = 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
+     */
     context(ctx) {
         const requestId = ctx.request.id();
         return requestId
@@ -76,17 +99,122 @@ export class ExceptionHandler {
             }
             : {};
     }
-    getResponseFormat(ctx) {
+    /**
+     * Renders an error to JSON response
+     */
+    async renderErrorAsJSON(error, ctx) {
+        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 });
+    }
+    /**
+     * Renders an error to JSON API response
+     */
+    async renderErrorAsJSONAPI(error, ctx) {
+        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,
+                },
+            ],
+        });
+    }
+    /**
+     * Renders an error to HTML response
+     */
+    async renderErrorAsHTML(error, ctx) {
+        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>`);
+    }
+    /**
+     * Renders the validation error message to a JSON
+     * response
+     */
+    async renderValidationErrorAsJSON(error, ctx) {
+        ctx.response.status(error.status).send({
+            errors: error.messages,
+        });
+    }
+    /**
+     * Renders the validation error message as per JSON API
+     * spec
+     */
+    async renderValidationErrorAsJSONAPI(error, ctx) {
+        ctx.response.status(error.status).send({
+            errors: error.messages.map((message) => {
+                return {
+                    title: message.message,
+                    code: message.rule,
+                    source: {
+                        pointer: message.field,
+                    },
+                    meta: message.meta,
+                };
+            }),
+        });
+    }
+    /**
+     * Renders the validation error as an HTML string
+     */
+    async renderValidationErrorAsHTML(error, ctx) {
+        ctx.response
+            .status(error.status)
+            .type('html')
+            .send(error.messages
+            .map((message) => {
+            return `${message.field} - ${message.message}`;
+        })
+            .join('<br />'));
+    }
+    /**
+     * Renders the error to response
+     */
+    renderError(error, ctx) {
         switch (ctx.request.accepts(['html', 'application/vnd.api+json', 'json'])) {
             case 'application/vnd.api+json':
-                return 'json_api';
+                return this.renderErrorAsJSONAPI(error, ctx);
             case 'json':
-                return 'json';
+                return this.renderErrorAsJSON(error, ctx);
             case 'html':
             default:
-                return 'html';
+                return this.renderErrorAsHTML(error, ctx);
         }
     }
+    /**
+     * Renders the validation error to response
+     */
+    renderValidationError(error, ctx) {
+        switch (ctx.request.accepts(['html', 'application/vnd.api+json', 'json'])) {
+            case 'application/vnd.api+json':
+                return this.renderValidationErrorAsJSONAPI(error, ctx);
+            case 'json':
+                return this.renderValidationErrorAsJSON(error, ctx);
+            case 'html':
+            default:
+                return this.renderValidationErrorAsHTML(error, ctx);
+        }
+    }
+    /**
+     * Returns the log level for an error based upon the error
+     * status code.
+     */
     getErrorLogLevel(error) {
         if (error.status >= 500) {
             return 'error';
@@ -96,9 +224,16 @@ export class ExceptionHandler {
         }
         return 'info';
     }
+    /**
+     * A boolean to control if errors should be rendered with
+     * all the available debugging info.
+     */
     isDebuggingEnabled(_) {
         return this.debug;
     }
+    /**
+     * Returns a boolean by checking if an error should be reported.
+     */
     shouldReport(error) {
         if (this.reportErrors === false) {
             return false;
@@ -114,6 +249,9 @@ export class ExceptionHandler {
         }
         return true;
     }
+    /**
+     * Reports an error during an HTTP request
+     */
     async report(error, ctx) {
         const httpError = this.#toHttpError(error);
         if (!this.shouldReport(httpError)) {
@@ -123,22 +261,43 @@ export class ExceptionHandler {
             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, ctx) {
         const httpError = this.#toHttpError(error);
+        /**
+         * Self handle exception
+         */
         if (typeof httpError.handle === 'function') {
             return httpError.handle(httpError, ctx);
         }
+        /**
+         * Handle validation error using the validation error
+         * renderers
+         */
+        if (httpError.code === 'E_VALIDATION_ERROR' && 'messages' in httpError) {
+            return this.renderValidationError(httpError, ctx);
+        }
+        /**
+         * Render status page
+         */
         const statusPages = this.#expandStatusPages();
         if (this.renderStatusPages && statusPages[httpError.status]) {
             return statusPages[httpError.status](httpError, ctx);
         }
-        const responseFormat = this.getResponseFormat(ctx);
-        return this.renderers[responseFormat](httpError, ctx);
+        /**
+         * Use the format renderers.
+         */
+        return this.renderError(httpError, ctx);
     }
 }

package/build/src/exceptions.d.ts

@@ -20,6 +20,9 @@ export declare const E_HTTP_EXCEPTION: {
         cause?: unknown;
     };
     code: string;
+    /**
+     * This method returns an instance of the exception class
+     */
     invoke(body: any, status: number, code?: string): {
         body: any;
         name: string;
@@ -57,6 +60,9 @@ export declare const E_HTTP_REQUEST_ABORTED: {
         cause?: unknown;
     };
     code: string;
+    /**
+     * This method returns an instance of the exception class
+     */
     invoke(body: any, status: number, code?: string): {
         body: any;
         name: string;

package/build/src/exceptions.js

@@ -1,9 +1,20 @@
+/*
+ * @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';
 export const E_ROUTE_NOT_FOUND = createError('Cannot %s:%s', 'E_ROUTE_NOT_FOUND', 404);
 export const E_CANNOT_LOOKUP_ROUTE = createError('Cannot lookup route "%s"', 'E_CANNOT_LOOKUP_ROUTE', 500);
 export const E_HTTP_EXCEPTION = class HttpException extends Exception {
     body;
     static code = 'E_HTTP_EXCEPTION';
+    /**
+     * This method returns an instance of the exception class
+     */
     static invoke(body, status, code = 'E_HTTP_EXCEPTION') {
         if (body === null || body === undefined) {
             const error = new this('HTTP Exception', { status, code });

package/build/src/helpers.d.ts

@@ -3,7 +3,21 @@ 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';
+/**
+ * Makes input string consistent by having only the starting
+ * slash
+ */
 export declare function dropSlash(input: string): string;
+/**
+ * Returns a flat list of routes from the route groups and resources
+ */
 export declare function toRoutesJSON(routes: (RouteGroup | Route | RouteResource | BriskRoute)[]): RouteJSON[];
+/**
+ * Helper to know if the remote address should
+ * be trusted.
+ */
 export declare function trustProxy(remoteAddress: string, proxyFn: (addr: string, distance: number) => boolean): boolean;
+/**
+ * Parses a range expression to an object filled with the range
+ */
 export declare function parseRange<T>(range: string, value: T): Record<number, T>;

package/build/src/helpers.js

@@ -1,15 +1,30 @@
+/*
+ * @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 { BriskRoute } from './router/brisk.js';
 import { RouteGroup } from './router/group.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) {
     if (input === '/') {
         return '/';
     }
     return `/${input.replace(/^\//, '').replace(/\/$/, '')}`;
 }
+/**
+ * Returns a flat list of routes from the route groups and resources
+ */
 export function toRoutesJSON(routes) {
     return routes.reduce((list, route) => {
         if (route instanceof RouteGroup) {
@@ -32,6 +47,10 @@ export function toRoutesJSON(routes) {
         return list;
     }, []);
 }
+/**
+ * Helper to know if the remote address should
+ * be trusted.
+ */
 export function trustProxy(remoteAddress, proxyFn) {
     if (proxyCache.has(remoteAddress)) {
         return proxyCache.get(remoteAddress);
@@ -40,21 +59,45 @@ export function trustProxy(remoteAddress, proxyFn) {
     proxyCache.set(remoteAddress, result);
     return result;
 }
+/**
+ * Parses a range expression to an object filled with the range
+ */
 export function parseRange(range, value) {
     const parts = range.split('..');
     const min = Number(parts[0]);
     const max = Number(parts[1]);
+    /**
+     * The ending status code does not exists
+     */
+    if (parts.length === 1 && !Number.isNaN(min)) {
+        return {
+            [min]: value,
+        };
+    }
+    /**
+     * The starting status code is not a number
+     */
     if (Number.isNaN(min) || Number.isNaN(max)) {
         return {};
     }
+    /**
+     * Min and max are same
+     */
     if (min === max) {
         return {
             [min]: value,
         };
     }
+    /**
+     * Max cannot be smaller than min
+     */
     if (max < min) {
         throw new InvalidArgumentsException(`Invalid range "${range}"`);
     }
+    /**
+     * Loop over the range and create a collection
+     * of status codes
+     */
     return [...Array(max - min + 1).keys()].reduce((result, step) => {
         result[min + step] = value;
         return result;

package/build/src/http_context/local_storage.d.ts

@@ -1,6 +1,9 @@
 /// <reference types="node" resolution-mode="require"/>
 import { AsyncLocalStorage } from 'node:async_hooks';
 import type { HttpContext } from './main.js';
+/**
+ * Async local storage for HTTP context
+ */
 export declare const asyncLocalStorage: {
     isEnabled: boolean;
     storage: null | AsyncLocalStorage<HttpContext>;

package/build/src/http_context/local_storage.js

@@ -1,12 +1,37 @@
+/*
+ * @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';
+/**
+ * Async local storage for HTTP context
+ */
 export const asyncLocalStorage = {
+    /**
+     * 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();
         return this.storage;
     },
+    /**
+     * Destroy the create storage instance
+     */
     destroy() {
         this.isEnabled = false;
         this.storage = null;

package/build/src/http_context/main.d.ts

@@ -4,19 +4,55 @@ import { ContainerResolver } from '@adonisjs/fold';
 import type { Request } from '../request.js';
 import type { Response } from '../response.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 declare class HttpContext extends Macroable {
     request: Request;
     response: Response;
     logger: Logger;
     containerResolver: ContainerResolver<any>;
+    /**
+     * Find if async localstorage is enabled for HTTP requests
+     * or not
+     */
     static get usingAsyncLocalStorage(): boolean;
+    /**
+     * Get access to the HTTP context. Available only when
+     * "usingAsyncLocalStorage" is true
+     */
     static get(): HttpContext | null;
+    /**
+     * Get the HttpContext instance or raise an exception if not
+     * available
+     */
     static getOrFail(): HttpContext;
+    /**
+     * 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;
+    /**
+     * 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(request: Request, response: Response, logger: Logger, containerResolver: ContainerResolver<any>);
+    /**
+     * A helper to see top level properties on the context object
+     */
     inspect(): string;
 }

package/build/src/http_context/main.js

@@ -1,22 +1,49 @@
+/*
+ * @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 { RuntimeException } from '@poppinss/utils';
 import { asyncLocalStorage } from './local_storage.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 {
     request;
     response;
     logger;
     containerResolver;
+    /**
+     * 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() {
         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() {
+        /**
+         * Localstorage is not enabled
+         */
         if (!this.usingAsyncLocalStorage || !asyncLocalStorage.storage) {
             throw new RuntimeException('HTTP context is not available. Enable "useAsyncLocalStorage" inside "config/app.ts" file');
         }
@@ -26,15 +53,32 @@ export class HttpContext extends Macroable {
         }
         return store;
     }
+    /**
+     * Run a method that doesn't have access to HTTP context from
+     * the async local storage.
+     */
     static runOutsideContext(callback, ...args) {
         if (!asyncLocalStorage.storage) {
             return callback(...args);
         }
         return asyncLocalStorage.storage.exit(callback, ...args);
     }
+    /**
+     * Reference to the current route. Not available inside
+     * server middleware
+     */
     route;
+    /**
+     * A unique key for the current route
+     */
     routeKey;
+    /**
+     * Route params
+     */
     params = {};
+    /**
+     * Route subdomains
+     */
     subdomains = {};
     constructor(request, response, logger, containerResolver) {
         super();
@@ -42,9 +86,19 @@ export class HttpContext extends Macroable {
         this.response = response;
         this.logger = logger;
         this.containerResolver = containerResolver;
+        /*
+         * 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/build/src/qs.d.ts

@@ -1,4 +1,8 @@
 import { QSParserConfig } from './types/qs.js';
+/**
+ * Query string parser used to parse and stringify query
+ * strings.
+ */
 export declare class Qs {
     #private;
     constructor(config: QSParserConfig);