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

package/build/src/cookies/parser.js

@@ -0,0 +1,167 @@
+/*
+ * @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 cookie from 'cookie';
+import { CookieClient } from './client.js';
+/**
+ * Cookie parser parses the HTTP `cookie` header and collects all cookies
+ * inside an object of `key-value` pair, but doesn't attempt to decrypt
+ * or unsign or decode the individual values.
+ *
+ * The cookie values are lazily decrypted, or unsigned to avoid unncessary
+ * processing, which infact can be used as a means to burden the server
+ * by sending too many cookies which even doesn't belongs to the
+ * server.
+ */
+export class CookieParser {
+    #client;
+    /**
+     * A copy of cached cookies, they are cached during a request after
+     * initial decoding, unsigning or decrypting.
+     */
+    #cachedCookies = {
+        signedCookies: {},
+        plainCookies: {},
+        encryptedCookies: {},
+    };
+    /**
+     * An object of key-value pair collected by parsing
+     * the request cookie header.
+     */
+    #cookies;
+    constructor(cookieHeader, encryption) {
+        this.#client = new CookieClient(encryption);
+        this.#cookies = this.#parse(cookieHeader);
+    }
+    /**
+     * Parses the request `cookie` header
+     */
+    #parse(cookieHeader) {
+        /*
+         * Set to empty object when cookie header is empty string
+         */
+        if (!cookieHeader) {
+            return {};
+        }
+        /*
+         * Parse and store reference
+         */
+        return cookie.parse(cookieHeader);
+    }
+    /**
+     * Attempts to decode a cookie by the name. When calling this method,
+     * you are assuming that the cookie was just encoded in the first
+     * place and not signed or encrypted.
+     */
+    decode(key, encoded = true) {
+        /*
+         * Ignore when initial value is not defined or null
+         */
+        const value = this.#cookies[key];
+        if (value === null || value === undefined) {
+            return null;
+        }
+        /*
+         * Reference to the cache object. Mainly done to avoid typos,
+         * since this object is referenced a handful of times inside
+         * this method.
+         */
+        const cache = this.#cachedCookies.plainCookies;
+        /*
+         * Return from cache, when already parsed
+         */
+        if (cache[key] !== undefined) {
+            return cache[key];
+        }
+        /*
+         * Attempt to unpack and cache it for future. The value is only
+         * when value it is not null.
+         */
+        const parsed = encoded ? this.#client.decode(key, value) : value;
+        if (parsed !== null) {
+            cache[key] = parsed;
+        }
+        return parsed;
+    }
+    /**
+     * Attempts to unsign a cookie by the name. When calling this method,
+     * you are assuming that the cookie was signed in the first place.
+     */
+    unsign(key) {
+        /*
+         * Ignore when initial value is not defined or null
+         */
+        const value = this.#cookies[key];
+        if (value === null || value === undefined) {
+            return null;
+        }
+        /*
+         * Reference to the cache object. Mainly done to avoid typos,
+         * since this object is referenced a handful of times inside
+         * this method.
+         */
+        const cache = this.#cachedCookies.signedCookies;
+        /*
+         * Return from cache, when already parsed
+         */
+        if (cache[key] !== undefined) {
+            return cache[key];
+        }
+        /*
+         * Attempt to unpack and cache it for future. The value is only
+         * when value it is not null.
+         */
+        const parsed = this.#client.unsign(key, value);
+        if (parsed !== null) {
+            cache[key] = parsed;
+        }
+        return parsed;
+    }
+    /**
+     * Attempts to decrypt a cookie by the name. When calling this method,
+     * you are assuming that the cookie was encrypted in the first place.
+     */
+    decrypt(key) {
+        /*
+         * Ignore when initial value is not defined or null
+         */
+        const value = this.#cookies[key];
+        if (value === null || value === undefined) {
+            return null;
+        }
+        /*
+         * Reference to the cache object. Mainly done to avoid typos,
+         * since this object is referenced a handful of times inside
+         * this method.
+         */
+        const cache = this.#cachedCookies.encryptedCookies;
+        /*
+         * Return from cache, when already parsed
+         */
+        if (cache[key] !== undefined) {
+            return cache[key];
+        }
+        /*
+         * Attempt to unpack and cache it for future. The value is only
+         * when value it is not null.
+         */
+        const parsed = this.#client.decrypt(key, value);
+        if (parsed !== null) {
+            cache[key] = parsed;
+        }
+        return parsed;
+    }
+    /**
+     * Returns an object of cookies key-value pair. Do note, the
+     * cookies are not decoded, unsigned or decrypted inside this
+     * list.
+     */
+    list() {
+        return this.#cookies;
+    }
+}

package/build/src/cookies/serializer.d.ts

@@ -0,0 +1,33 @@
+import type { Encryption } from '@adonisjs/encryption';
+import type { CookieOptions } from '../types/response.js';
+/**
+ * Cookies serializer is used to serialize a value to be set on the `Set-Cookie`
+ * header. You can `encode`, `sign` on `encrypt` cookies using the serializer
+ * and then set them individually using the `set-cookie` header.
+ */
+export declare class CookieSerializer {
+    #private;
+    constructor(encryption: Encryption);
+    /**
+     * Encodes value as a plain cookie. By default, the plain value will be converted
+     * to a string using "JSON.stringify" method and then encoded as a base64 string.
+     *
+     * You can disable encoding of the cookie by setting `options.encoded = false`.
+     *
+     * ```ts
+     *  serializer.encode('name', 'virk')
+     * ```
+     */
+    encode(key: string, value: any, options?: Partial<CookieOptions & {
+        encode: boolean;
+    }>): string | null;
+    /**
+     * Sign a key-value pair to a signed cookie. The signed value has a
+     * verification hash attached to it to detect data tampering.
+     */
+    sign(key: string, value: any, options?: Partial<CookieOptions>): string | null;
+    /**
+     * Encrypts a key-value pair to an encrypted cookie.
+     */
+    encrypt(key: string, value: any, options?: Partial<CookieOptions>): string | null;
+}

package/build/src/cookies/serializer.js

@@ -0,0 +1,79 @@
+/*
+ * @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 cookie from 'cookie';
+import string from '@poppinss/utils/string';
+import { CookieClient } from './client.js';
+/**
+ * Cookies serializer is used to serialize a value to be set on the `Set-Cookie`
+ * header. You can `encode`, `sign` on `encrypt` cookies using the serializer
+ * and then set them individually using the `set-cookie` header.
+ */
+export class CookieSerializer {
+    #client;
+    constructor(encryption) {
+        this.#client = new CookieClient(encryption);
+    }
+    /**
+     * Serializes the key-value pair to a string, that can be set on the
+     * `Set-Cookie` header.
+     */
+    #serializeAsCookie(key, value, options) {
+        /**
+         * Invoked expires method to get the date
+         */
+        let expires = options?.expires;
+        if (typeof expires === 'function') {
+            expires = expires();
+        }
+        /**
+         * Parse string based max age to seconds
+         */
+        let maxAge = options?.maxAge ? string.seconds.parse(options?.maxAge) : undefined;
+        const parsedOptions = Object.assign({}, options, { maxAge, expires });
+        return cookie.serialize(key, value, parsedOptions);
+    }
+    /**
+     * Encodes value as a plain cookie. By default, the plain value will be converted
+     * to a string using "JSON.stringify" method and then encoded as a base64 string.
+     *
+     * You can disable encoding of the cookie by setting `options.encoded = false`.
+     *
+     * ```ts
+     *  serializer.encode('name', 'virk')
+     * ```
+     */
+    encode(key, value, options) {
+        const packedValue = options?.encode === false ? value : this.#client.encode(key, value);
+        if (packedValue === null || packedValue === undefined) {
+            return null;
+        }
+        return this.#serializeAsCookie(key, packedValue, options);
+    }
+    /**
+     * Sign a key-value pair to a signed cookie. The signed value has a
+     * verification hash attached to it to detect data tampering.
+     */
+    sign(key, value, options) {
+        const packedValue = this.#client.sign(key, value);
+        if (packedValue === null) {
+            return null;
+        }
+        return this.#serializeAsCookie(key, packedValue, options);
+    }
+    /**
+     * Encrypts a key-value pair to an encrypted cookie.
+     */
+    encrypt(key, value, options) {
+        const packedValue = this.#client.encrypt(key, value);
+        if (packedValue === null) {
+            return null;
+        }
+        return this.#serializeAsCookie(key, packedValue, options);
+    }
+}

package/build/src/debug.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="node" resolution-mode="require"/>
+declare const _default: import("util").DebugLogger;
+export default _default;

package/build/src/debug.js

@@ -0,0 +1,10 @@
+/*
+ * @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 { debuglog } from 'node:util';
+export default debuglog('adonisjs:http');

package/build/src/define_config.d.ts

@@ -0,0 +1,9 @@
+import type { ServerConfig } from './types/server.js';
+type UserDefinedServerConfig = Partial<Omit<ServerConfig, 'trustProxy'> & {
+    trustProxy: ((address: string, distance: number) => boolean) | boolean | string;
+}>;
+/**
+ * Define configuration for the HTTP server
+ */
+export declare function defineConfig(config: UserDefinedServerConfig): ServerConfig;
+export {};

package/build/src/define_config.js

@@ -0,0 +1,68 @@
+/*
+ * @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 proxyAddr from 'proxy-addr';
+import string from '@poppinss/utils/string';
+/**
+ * Define configuration for the HTTP server
+ */
+export function defineConfig(config) {
+    const { trustProxy, ...rest } = config;
+    const normalizedConfig = {
+        allowMethodSpoofing: false,
+        trustProxy: proxyAddr.compile('loopback'),
+        subdomainOffset: 2,
+        generateRequestId: false,
+        useAsyncLocalStorage: false,
+        etag: false,
+        jsonpCallbackName: 'callback',
+        cookie: {
+            maxAge: '2h',
+            path: '/',
+            httpOnly: true,
+            secure: false,
+            sameSite: false,
+        },
+        qs: {
+            parse: {
+                depth: 5,
+                parameterLimit: 1000,
+                allowSparse: false,
+                arrayLimit: 20,
+                comma: true,
+            },
+            stringify: {
+                encode: true,
+                encodeValuesOnly: false,
+                arrayFormat: 'indices',
+                skipNulls: false,
+            },
+        },
+        ...rest,
+    };
+    /**
+     * Normalizing maxAge property on cookies to be a number in
+     * seconds
+     */
+    if (normalizedConfig.cookie.maxAge) {
+        normalizedConfig.cookie.maxAge = string.seconds.parse(normalizedConfig.cookie.maxAge);
+    }
+    /**
+     * Normalizing trust proxy setting to allow boolean and
+     * string values
+     */
+    if (typeof trustProxy === 'boolean') {
+        const tpValue = trustProxy;
+        normalizedConfig.trustProxy = (_, __) => tpValue;
+    }
+    else if (typeof trustProxy === 'string') {
+        const tpValue = trustProxy;
+        normalizedConfig.trustProxy = proxyAddr.compile(tpValue);
+    }
+    return normalizedConfig;
+}

package/build/src/define_middleware.d.ts

@@ -0,0 +1,11 @@
+import type { LazyImport, UnWrapLazyImport } from './types/base.js';
+import type { GetMiddlewareArgs, MiddlewareAsClass, ParsedGlobalMiddleware } from './types/middleware.js';
+/**
+ * Define an collection of named middleware. The collection gets converted
+ * into a collection of factory functions. Calling the function returns
+ * a reference to the executable middleware.
+ */
+export declare function defineNamedMiddleware<NamedMiddleware extends Record<string | number | symbol, LazyImport<MiddlewareAsClass>>>(collection: NamedMiddleware): { [K in keyof NamedMiddleware]: <Args extends GetMiddlewareArgs<UnWrapLazyImport<NamedMiddleware[K]>>>(...args: Args) => {
+    name: K;
+    args: Args[0];
+} & ParsedGlobalMiddleware; };

package/build/src/define_middleware.js

@@ -0,0 +1,35 @@
+/*
+ * @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 { moduleImporter } from '@adonisjs/fold';
+/**
+ * Converts a middleware name and its lazy import to a factory function. The function
+ * can than later be used to reference the middleware with different arguments
+ * every time.
+ */
+function middlewareReferenceBuilder(name, middleware) {
+    const handler = moduleImporter(middleware, 'handle').toHandleMethod();
+    return function (...args) {
+        return {
+            name,
+            args: args[0],
+            ...handler,
+        };
+    };
+}
+/**
+ * Define an collection of named middleware. The collection gets converted
+ * into a collection of factory functions. Calling the function returns
+ * a reference to the executable middleware.
+ */
+export function defineNamedMiddleware(collection) {
+    return Object.keys(collection).reduce((result, key) => {
+        result[key] = middlewareReferenceBuilder(key, collection[key]);
+        return result;
+    }, {});
+}

package/build/src/exception_handler.d.ts

@@ -0,0 +1,113 @@
+import Macroable from '@poppinss/macroable';
+import type { Level } from '@adonisjs/logger/types';
+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 declare class ExceptionHandler extends Macroable {
+    #private;
+    /**
+     * Whether or not to render debug info. When set to true, the errors
+     * will have the complete error stack.
+     */
+    protected debug: boolean;
+    /**
+     * 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;
+    /**
+     * A collection of error status code range and the view to render.
+     */
+    protected statusPages: Record<StatusPageRange, StatusPageRenderer>;
+    /**
+     * Enable/disable errors reporting
+     */
+    protected reportErrors: boolean;
+    /**
+     * An array of exception classes to ignore when
+     * reporting an error
+     */
+    protected ignoreExceptions: any[];
+    /**
+     * An array of HTTP status codes to ignore when reporting
+     * an error
+     */
+    protected ignoreStatuses: number[];
+    /**
+     * An array of error codes to ignore when reporting
+     * an error
+     */
+    protected ignoreCodes: string[];
+    /**
+     * Error reporting context
+     */
+    protected context(ctx: HttpContext): any;
+    /**
+     * Returns the log level for an error based upon the error
+     * status code.
+     */
+    protected getErrorLogLevel(error: HttpError): Level;
+    /**
+     * A boolean to control if errors should be rendered with
+     * all the available debugging info.
+     */
+    protected isDebuggingEnabled(_: HttpContext): boolean;
+    /**
+     * Returns a boolean by checking if an error should be reported.
+     */
+    protected shouldReport(error: HttpError): boolean;
+    /**
+     * Renders an error to JSON response
+     */
+    renderErrorAsJSON(error: HttpError, ctx: HttpContext): Promise<void>;
+    /**
+     * Renders an error to JSON API response
+     */
+    renderErrorAsJSONAPI(error: HttpError, ctx: HttpContext): Promise<void>;
+    /**
+     * Renders an error to HTML response
+     */
+    renderErrorAsHTML(error: HttpError, ctx: HttpContext): Promise<void>;
+    /**
+     * Renders the validation error message to a JSON
+     * response
+     */
+    renderValidationErrorAsJSON(error: HttpError, ctx: HttpContext): Promise<void>;
+    /**
+     * Renders the validation error message as per JSON API
+     * spec
+     */
+    renderValidationErrorAsJSONAPI(error: HttpError, ctx: HttpContext): Promise<void>;
+    /**
+     * Renders the validation error as an HTML string
+     */
+    renderValidationErrorAsHTML(error: HttpError, ctx: HttpContext): Promise<void>;
+    /**
+     * Renders the error to response
+     */
+    renderError(error: HttpError, ctx: HttpContext): Promise<void>;
+    /**
+     * Renders the validation error to response
+     */
+    renderValidationError(error: HttpError, ctx: HttpContext): Promise<void>;
+    /**
+     * Reports an error during an HTTP request
+     */
+    report(error: unknown, ctx: HttpContext): Promise<void>;
+    /**
+     * Handles the error during the HTTP request.
+     */
+    handle(error: unknown, ctx: HttpContext): Promise<any>;
+}