@adonisjs/http-server 6.8.2-6 → 6.8.2-7

package/build/src/cookies/drivers/encrypted.d.ts

@@ -1,5 +1,16 @@
 import type { Encryption } from '@adonisjs/encryption';
+/**
+ * Encrypt a value to be set as cookie
+ */
 export declare function pack(key: string, value: any, encryption: Encryption): null | string;
+/**
+ * Returns a boolean, if the unpack method from this module can attempt
+ * to unpack encrypted value.
+ */
 export declare function canUnpack(encryptedValue: string): boolean;
+/**
+ * Attempts to unpack the encrypted cookie value. Returns null, when fails to do so.
+ * Only call this method, when `canUnpack` returns true, otherwise runtime
+ * exceptions can be raised.
+ */
 export declare function unpack(key: string, encryptedValue: string, encryption: Encryption): null | any;
-//# sourceMappingURL=encrypted.d.ts.map

package/build/src/cookies/drivers/encrypted.js

@@ -1,12 +1,32 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+/**
+ * Encrypt a value to be set as cookie
+ */
 export function pack(key, value, encryption) {
     if (value === undefined || value === null) {
         return null;
     }
     return `e:${encryption.encrypt(value, undefined, key)}`;
 }
+/**
+ * Returns a boolean, if the unpack method from this module can attempt
+ * to unpack encrypted value.
+ */
 export function canUnpack(encryptedValue) {
     return typeof encryptedValue === 'string' && encryptedValue.substring(0, 2) === 'e:';
 }
+/**
+ * Attempts to unpack the encrypted cookie value. Returns null, when fails to do so.
+ * Only call this method, when `canUnpack` returns true, otherwise runtime
+ * exceptions can be raised.
+ */
 export function unpack(key, encryptedValue, encryption) {
     const value = encryptedValue.slice(2);
     if (!value) {

package/build/src/cookies/drivers/plain.d.ts

@@ -1,4 +1,15 @@
+/**
+ * Encodes a value into a base64 url encoded string to
+ * be set as cookie
+ */
 export declare function pack(value: any): null | string;
+/**
+ * Returns true when this `unpack` method of this module can attempt
+ * to unpack the encode value.
+ */
 export declare function canUnpack(encodedValue: string): boolean;
+/**
+ * Attempts to unpack the value by decoding it. Make sure to call, `canUnpack`
+ * before calling this method
+ */
 export declare function unpack(encodedValue: string): null | any;
-//# sourceMappingURL=plain.d.ts.map

package/build/src/cookies/drivers/plain.js

@@ -1,13 +1,33 @@
+/*
+ * @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 { base64, MessageBuilder } from '@poppinss/utils';
+/**
+ * Encodes a value into a base64 url encoded string to
+ * be set as cookie
+ */
 export function pack(value) {
     if (value === undefined || value === null) {
         return null;
     }
     return base64.urlEncode(new MessageBuilder().build(value));
 }
+/**
+ * Returns true when this `unpack` method of this module can attempt
+ * to unpack the encode value.
+ */
 export function canUnpack(encodedValue) {
     return typeof encodedValue === 'string';
 }
+/**
+ * Attempts to unpack the value by decoding it. Make sure to call, `canUnpack`
+ * before calling this method
+ */
 export function unpack(encodedValue) {
     return new MessageBuilder().verify(base64.urlDecode(encodedValue, 'utf-8', false));
 }

package/build/src/cookies/drivers/signed.d.ts

@@ -1,5 +1,16 @@
 import type { Encryption } from '@adonisjs/encryption';
+/**
+ * Signs a value to be shared as a cookie. The signed output has a
+ * hash to verify tampering with the original value
+ */
 export declare function pack(key: string, value: any, encryption: Encryption): null | string;
+/**
+ * Returns a boolean, if the unpack method from this module can attempt
+ * to unpack the signed value.
+ */
 export declare function canUnpack(signedValue: string): boolean;
+/**
+ * Attempts to unpack the signed value. Make sure to call `canUnpack` before
+ * calling this method.
+ */
 export declare function unpack(key: string, signedValue: string, encryption: Encryption): null | any;
-//# sourceMappingURL=signed.d.ts.map

package/build/src/cookies/drivers/signed.js

@@ -1,12 +1,32 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+/**
+ * Signs a value to be shared as a cookie. The signed output has a
+ * hash to verify tampering with the original value
+ */
 export function pack(key, value, encryption) {
     if (value === undefined || value === null) {
         return null;
     }
     return `s:${encryption.verifier.sign(value, undefined, key)}`;
 }
+/**
+ * Returns a boolean, if the unpack method from this module can attempt
+ * to unpack the signed value.
+ */
 export function canUnpack(signedValue) {
     return typeof signedValue === 'string' && signedValue.substring(0, 2) === 's:';
 }
+/**
+ * Attempts to unpack the signed value. Make sure to call `canUnpack` before
+ * calling this method.
+ */
 export function unpack(key, signedValue, encryption) {
     const value = signedValue.slice(2);
     if (!value) {

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

@@ -1,10 +1,37 @@
 import type { Encryption } from '@adonisjs/encryption';
+/**
+ * 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 declare class CookieParser {
     #private;
     constructor(cookieHeader: string, encryption: Encryption);
+    /**
+     * 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: string, encoded?: boolean): any | null;
+    /**
+     * 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: string): null | any;
+    /**
+     * 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: string): null | any;
+    /**
+     * Returns an object of cookies key-value pair. Do note, the
+     * cookies are not decoded, unsigned or decrypted inside this
+     * list.
+     */
     list(): Record<string, any>;
 }
-//# sourceMappingURL=parser.d.ts.map

package/build/src/cookies/parser.js

@@ -1,68 +1,166 @@
+/*
+ * @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

@@ -1,12 +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;
 }
-//# sourceMappingURL=serializer.d.ts.map

package/build/src/cookies/serializer.js

@@ -1,20 +1,53 @@
+/*
+ * @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) {
@@ -22,6 +55,10 @@ export class CookieSerializer {
         }
         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) {
@@ -29,6 +66,9 @@ export class CookieSerializer {
         }
         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) {

package/build/src/debug.d.ts

@@ -1,4 +1,3 @@
 /// <reference types="node" resolution-mode="require"/>
 declare const _default: import("util").DebugLogger;
 export default _default;
-//# sourceMappingURL=debug.d.ts.map

package/build/src/debug.js

@@ -1,2 +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

@@ -1,3 +1,5 @@
 import type { ServerConfig } from './types/server.js';
+/**
+ * Define configuration for the HTTP server
+ */
 export declare function defineConfig(config: Partial<ServerConfig>): ServerConfig;
-//# sourceMappingURL=define_config.d.ts.map

package/build/src/define_config.js

@@ -1,5 +1,16 @@
+/*
+ * @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 normalizedConfig = {
         allowMethodSpoofing: false,

package/build/src/define_middleware.d.ts

@@ -1,7 +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; };
-//# sourceMappingURL=define_middleware.d.ts.map

package/build/src/define_middleware.js

@@ -1,4 +1,17 @@
+/*
+ * @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) {
@@ -9,6 +22,11 @@ function middlewareReferenceBuilder(name, middleware) {
         };
     };
 }
+/**
+ * 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]);

package/build/src/exception_handler.d.ts

@@ -1,26 +1,90 @@
 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 {
     #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>;
+    /**
+     * 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>;
     };
+    /**
+     * 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;
+    /**
+     * The format in which the error should be rendered.
+     */
     protected getResponseFormat(ctx: HttpContext): 'html' | 'json' | 'json_api';
+    /**
+     * 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;
+    /**
+     * 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>;
 }
-//# sourceMappingURL=exception_handler.d.ts.map