@adonisjs/http-server 7.0.0-0 → 7.0.0-1

package/build/src/exception_handler.js

@@ -0,0 +1,306 @@
+/*
+ * @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 Macroable from '@poppinss/macroable';
+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 extends Macroable {
+    /**
+     * 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 = {};
+    /**
+     * 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) => {
+                const renderer = this.statusPages[range];
+                result = Object.assign(result, parseRange(range, renderer));
+                return result;
+            }, {});
+        }
+        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
+            ? {
+                'x-request-id': requestId,
+            }
+            : {};
+    }
+    /**
+     * Returns the log level for an error based upon the error
+     * status code.
+     */
+    getErrorLogLevel(error) {
+        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.
+     */
+    isDebuggingEnabled(_) {
+        return this.debug;
+    }
+    /**
+     * Returns a boolean by checking if an error should be reported.
+     */
+    shouldReport(error) {
+        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;
+    }
+    /**
+     * 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({
+                cspNonce: 'nonce' in ctx.response ? ctx.response.nonce : undefined,
+            });
+            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 this.renderErrorAsJSONAPI(error, ctx);
+            case 'json':
+                return this.renderErrorAsJSON(error, ctx);
+            case 'html':
+            default:
+                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);
+        }
+    }
+    /**
+     * Reports an error during an HTTP request
+     */
+    async report(error, ctx) {
+        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, 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);
+        }
+        /**
+         * Use the format renderers.
+         */
+        return this.renderError(httpError, ctx);
+    }
+}

package/build/src/exceptions.d.ts

@@ -0,0 +1,84 @@
+/// <reference types="node" resolution-mode="require"/>
+import { Exception } from '@poppinss/utils';
+import type { HttpContext } from './http_context/main.js';
+export declare const E_ROUTE_NOT_FOUND: new (args: [method: string, url: string], options?: ErrorOptions | undefined) => Exception;
+export declare const E_CANNOT_LOOKUP_ROUTE: new (args: [routeIdentifier: string], options?: ErrorOptions | undefined) => Exception;
+export declare const E_HTTP_EXCEPTION: {
+    new (message?: string | undefined, options?: (ErrorOptions & {
+        code?: string | undefined;
+        status?: number | undefined;
+    }) | undefined): {
+        body: any;
+        name: string;
+        help?: string | undefined;
+        code?: string | undefined;
+        status: number;
+        toString(): string;
+        readonly [Symbol.toStringTag]: string;
+        message: string;
+        stack?: string | undefined;
+        cause?: unknown;
+    };
+    code: string;
+    /**
+     * This method returns an instance of the exception class
+     */
+    invoke(body: any, status: number, code?: string): {
+        body: any;
+        name: string;
+        help?: string | undefined;
+        code?: string | undefined;
+        status: number;
+        toString(): string;
+        readonly [Symbol.toStringTag]: string;
+        message: string;
+        stack?: string | undefined;
+        cause?: unknown;
+    };
+    help?: string | undefined;
+    status?: number | undefined;
+    message?: string | undefined;
+    captureStackTrace(targetObject: object, constructorOpt?: Function | undefined): void;
+    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+    stackTraceLimit: number;
+};
+export declare const E_HTTP_REQUEST_ABORTED: {
+    new (message?: string | undefined, options?: (ErrorOptions & {
+        code?: string | undefined;
+        status?: number | undefined;
+    }) | undefined): {
+        handle(error: any, ctx: HttpContext): void;
+        body: any;
+        name: string;
+        help?: string | undefined;
+        code?: string | undefined;
+        status: number;
+        toString(): string;
+        readonly [Symbol.toStringTag]: string;
+        message: string;
+        stack?: string | undefined;
+        cause?: unknown;
+    };
+    code: string;
+    /**
+     * This method returns an instance of the exception class
+     */
+    invoke(body: any, status: number, code?: string): {
+        body: any;
+        name: string;
+        help?: string | undefined;
+        code?: string | undefined;
+        status: number;
+        toString(): string;
+        readonly [Symbol.toStringTag]: string;
+        message: string;
+        stack?: string | undefined;
+        cause?: unknown;
+    };
+    help?: string | undefined;
+    status?: number | undefined;
+    message?: string | undefined;
+    captureStackTrace(targetObject: object, constructorOpt?: Function | undefined): void;
+    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+    stackTraceLimit: number;
+};

package/build/src/exceptions.js

@@ -0,0 +1,38 @@
+/*
+ * @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 });
+            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, ctx) {
+        ctx.response.status(error.status).send(error.body);
+    }
+};

package/build/src/helpers.d.ts

@@ -0,0 +1,23 @@
+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';
+/**
+ * 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

@@ -0,0 +1,105 @@
+/*
+ * @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) {
+            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, proxyFn) {
+    if (proxyCache.has(remoteAddress)) {
+        return proxyCache.get(remoteAddress);
+    }
+    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(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

@@ -0,0 +1,12 @@
+/// <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>;
+    create(): AsyncLocalStorage<HttpContext>;
+    destroy(): void;
+};

package/build/src/http_context/local_storage.js

@@ -0,0 +1,39 @@
+/*
+ * @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

@@ -0,0 +1,58 @@
+import Macroable from '@poppinss/macroable';
+import type { Logger } from '@adonisjs/logger';
+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;
+}