@adonisjs/http-server 8.0.0 → 8.1.0

package/build/index.js

@@ -1,27 +1,92 @@
-import { a as RouteGroup, c as Route, m as canWriteResponseBody, o as RouteResource, p as tracing_channels_exports, s as BriskRoute, t as parseRange } from "./utils-BjSHKI3s.js";
-import { _ as Qs, a as CookieSerializer, c as HttpRequest, d as Redirect, f as E_CANNOT_LOOKUP_ROUTE, g as errors_exports, h as E_ROUTE_NOT_FOUND, i as HttpResponse, l as CookieParser, m as E_HTTP_REQUEST_ABORTED, n as Server, o as ResponseStatus, p as E_HTTP_EXCEPTION, r as HttpContext, s as Router, t as defineConfig, u as CookieClient } from "./define_config-D-kQXU0e.js";
-import "./helpers-C_2HouOe.js";
-import "./types-AUwURgIL.js";
+import "./chunk-B2GA45YG.js";
+import { _ as Qs, a as CookieSerializer, c as HttpRequest, d as Redirect, f as E_CANNOT_LOOKUP_ROUTE, g as errors_exports, h as E_ROUTE_NOT_FOUND, i as HttpResponse, l as CookieParser, m as E_HTTP_REQUEST_ABORTED, n as Server, o as ResponseStatus, p as E_HTTP_EXCEPTION, r as HttpContext, s as Router, t as defineConfig, u as CookieClient } from "./define_config-t7GL92UR.js";
+import { C as canWriteResponseBody, S as tracing_channels_exports, _ as Route, g as BriskRoute, h as RouteResource, m as RouteGroup, u as parseRange } from "./helpers-aa47NQc6.js";
+import "./helpers-XD4_pfkD.js";
 import Macroable from "@poppinss/macroable";
 import is from "@sindresorhus/is";
+//#region src/exception_handler.ts
+/**
+* The base HTTP exception handler that provides comprehensive error handling capabilities.
+*
+* This class can be inherited to create custom exception handlers for your application.
+* It provides built-in support for:
+*
+* - Self-handling exceptions via their own render/handle methods
+* - Custom status page rendering for different HTTP error codes
+* - Debug-friendly error display during development
+* - Content negotiation for JSON, JSON API, and HTML error responses
+* - Configurable error reporting and logging
+* - Validation error handling with field-specific messages
+*
+* @example
+* ```ts
+* export default class HttpExceptionHandler extends ExceptionHandler {
+*   protected debug = app.inDev
+*   protected renderStatusPages = app.inProduction
+*
+*   protected statusPages = {
+*     '404': (error, ctx) => ctx.view.render('errors/404')
+*   }
+* }
+* ```
+*/
 var ExceptionHandler = class extends Macroable {
+	/**
+	* Cached expanded status pages mapping individual status codes to their renderers
+	* Computed from the statusPages property when first accessed
+	*/
 	#expandedStatusPages;
+	/**
+	* Controls whether to include debug information in error responses
+	* When enabled, errors include complete stack traces and detailed debugging info
+	* Defaults to true in non-production environments
+	*/
 	debug = process.env.NODE_ENV !== "production";
+	/**
+	* Controls whether to render custom status pages for unhandled errors
+	* When enabled, errors with matching status codes use configured status page renderers
+	* Defaults to true in production environments
+	*/
 	renderStatusPages = process.env.NODE_ENV === "production";
+	/**
+	* Mapping of HTTP status code ranges to their corresponding page renderers
+	* Supports ranges like '400-499' or individual codes like '404'
+	*/
 	statusPages = {};
+	/**
+	* Controls whether errors should be reported to logging systems
+	* When disabled, errors are handled but not logged or reported
+	*/
 	reportErrors = true;
+	/**
+	* Array of exception class constructors to exclude from error reporting
+	* These exceptions are handled but not logged or reported to external systems
+	*/
 	ignoreExceptions = [
 		E_HTTP_EXCEPTION,
 		E_ROUTE_NOT_FOUND,
 		E_CANNOT_LOOKUP_ROUTE,
 		E_HTTP_REQUEST_ABORTED
 	];
+	/**
+	* Array of HTTP status codes to exclude from error reporting
+	* Errors with these status codes are handled but not logged
+	*/
 	ignoreStatuses = [
 		400,
 		422,
 		401
 	];
+	/**
+	* Array of custom error codes to exclude from error reporting
+	* Errors with these codes are handled but not logged
+	*/
 	ignoreCodes = [];
+	/**
+	* Expands status page ranges into individual status code mappings
+	* Creates a cached lookup table for faster status page resolution
+	* @returns Mapping of status codes to renderers
+	*/
 	#expandStatusPages() {
 		if (!this.#expandedStatusPages) this.#expandedStatusPages = Object.keys(this.statusPages).reduce((result, range) => {
 			const renderer = this.statusPages[range];
@@ -30,24 +95,54 @@ var ExceptionHandler = class extends Macroable {
 		}, {});
 		return this.#expandedStatusPages;
 	}
+	/**
+	* Normalizes any thrown value into a standardized HttpError object
+	* Ensures the error has required properties like message and status
+	* @param error - Any thrown value (Error, string, object, etc.)
+	* @returns {HttpError} Normalized error object with status and message
+	*/
 	toHttpError(error) {
 		const httpError = is.object(error) ? error : new Error(String(error));
 		if (!httpError.message) httpError.message = "Internal server error";
 		if (!httpError.status) httpError.status = 500;
 		return httpError;
 	}
+	/**
+	* Provides additional context information for error reporting
+	* Includes request ID when available for correlation across logs
+	* @param ctx - HTTP context containing request information
+	* @returns Additional context data for error reporting
+	*/
 	context(ctx) {
 		const requestId = ctx.request.id();
 		return requestId ? { "x-request-id": requestId } : {};
 	}
+	/**
+	* Determines the appropriate log level based on HTTP status code
+	* 5xx errors are logged as 'error', 4xx as 'warn', others as 'info'
+	* @param error - HTTP error object with status code
+	* @returns {Level} Appropriate logging level for the error
+	*/
 	getErrorLogLevel(error) {
 		if (error.status >= 500) return "error";
 		if (error.status >= 400) return "warn";
 		return "info";
 	}
+	/**
+	* Determines whether debug information should be included in error responses
+	* Override this method to implement context-specific debug control
+	* @param _ - HTTP context (unused in base implementation)
+	* @returns {boolean} True if debugging should be enabled
+	*/
 	isDebuggingEnabled(_) {
 		return this.debug;
 	}
+	/**
+	* Determines whether an error should be reported to logging systems
+	* Checks against ignore lists for exceptions, status codes, and error codes
+	* @param error - HTTP error to evaluate for reporting
+	* @returns {boolean} True if the error should be reported
+	*/
 	shouldReport(error) {
 		if (this.reportErrors === false) return false;
 		if (this.ignoreStatuses.includes(error.status)) return false;
@@ -55,6 +150,12 @@ var ExceptionHandler = class extends Macroable {
 		if (this.ignoreExceptions.find((exception) => error instanceof exception)) return false;
 		return true;
 	}
+	/**
+	* Renders an error as a JSON response
+	* In debug mode, includes full stack trace using Youch
+	* @param error - HTTP error to render
+	* @param ctx - HTTP context for the request
+	*/
 	async renderErrorAsJSON(error, ctx) {
 		if (this.isDebuggingEnabled(ctx)) {
 			const { Youch } = await import("youch");
@@ -64,6 +165,12 @@ var ExceptionHandler = class extends Macroable {
 		}
 		ctx.response.status(error.status).send({ message: error.message });
 	}
+	/**
+	* Renders an error as a JSON API compliant response
+	* Follows JSON API specification for error objects
+	* @param error - HTTP error to render
+	* @param ctx - HTTP context for the request
+	*/
 	async renderErrorAsJSONAPI(error, ctx) {
 		if (this.isDebuggingEnabled(ctx)) {
 			const { Youch } = await import("youch");
@@ -77,10 +184,22 @@ var ExceptionHandler = class extends Macroable {
 			status: error.status
 		}] });
 	}
+	/**
+	* Renders an error as an HTML response
+	* Uses status pages if configured, otherwise shows debug info or simple message
+	* @param error - HTTP error to render
+	* @param ctx - HTTP context for the request
+	*/
 	async renderErrorAsHTML(error, ctx) {
+		/**
+		* Render status page
+		*/
 		const statusPages = this.#expandStatusPages();
 		if (this.renderStatusPages && statusPages[error.status]) {
 			const statusPageResponse = await statusPages[error.status](error, ctx);
+			/**
+			* Use return value and convert it into a response
+			*/
 			if (canWriteResponseBody(statusPageResponse, ctx)) return ctx.response.safeStatus(error.status).send(statusPageResponse);
 			return statusPageResponse;
 		}
@@ -95,9 +214,21 @@ var ExceptionHandler = class extends Macroable {
 		}
 		ctx.response.status(error.status).send(`<p> ${error.message} </p>`);
 	}
+	/**
+	* Renders validation error messages as a JSON response
+	* Returns errors in a simple format with field-specific messages
+	* @param error - Validation error containing messages array
+	* @param ctx - HTTP context for the request
+	*/
 	async renderValidationErrorAsJSON(error, ctx) {
 		ctx.response.status(error.status).send({ errors: error.messages });
 	}
+	/**
+	* Renders validation error messages as JSON API compliant response
+	* Transforms validation messages to JSON API error object format
+	* @param error - Validation error containing messages array
+	* @param ctx - HTTP context for the request
+	*/
 	async renderValidationErrorAsJSONAPI(error, ctx) {
 		ctx.response.status(error.status).send({ errors: error.messages.map((message) => {
 			return {
@@ -108,11 +239,23 @@ var ExceptionHandler = class extends Macroable {
 			};
 		}) });
 	}
+	/**
+	* Renders validation error messages as an HTML response
+	* Creates simple HTML list of field errors separated by line breaks
+	* @param error - Validation error containing messages array
+	* @param ctx - HTTP context for the request
+	*/
 	async renderValidationErrorAsHTML(error, ctx) {
 		ctx.response.status(error.status).type("html").send(error.messages.map((message) => {
 			return `${message.field} - ${message.message}`;
 		}).join("<br />"));
 	}
+	/**
+	* Renders an error to the appropriate response format based on content negotiation
+	* Supports HTML, JSON API, and JSON formats based on Accept headers
+	* @param error - HTTP error to render
+	* @param ctx - HTTP context for the request
+	*/
 	renderError(error, ctx) {
 		switch (ctx.request.accepts([
 			"html",
@@ -124,6 +267,12 @@ var ExceptionHandler = class extends Macroable {
 			default: return this.renderErrorAsHTML(error, ctx);
 		}
 	}
+	/**
+	* Renders validation errors to the appropriate response format based on content negotiation
+	* Supports HTML, JSON API, and JSON formats for validation error messages
+	* @param error - Validation error to render
+	* @param ctx - HTTP context for the request
+	*/
 	renderValidationError(error, ctx) {
 		switch (ctx.request.accepts([
 			"html",
@@ -135,6 +284,12 @@ var ExceptionHandler = class extends Macroable {
 			default: return this.renderValidationErrorAsHTML(error, ctx);
 		}
 	}
+	/**
+	* Reports an error to logging systems if reporting is enabled
+	* Allows errors to self-report via their own report method if available
+	* @param error - Any error object to report
+	* @param ctx - HTTP context for additional reporting context
+	*/
 	async report(error, ctx) {
 		const httpError = this.toHttpError(error);
 		if (!this.shouldReport(httpError)) return;
@@ -142,17 +297,37 @@ var ExceptionHandler = class extends Macroable {
 			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 errors during HTTP request processing
+	* Delegates to error's own handle method if available, otherwise renders response
+	* @param error - Any error object to handle
+	* @param ctx - HTTP context for error handling
+	*/
 	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);
+		/**
+		* Use the format renderers.
+		*/
 		return this.renderError(httpError, ctx);
 	}
 };
+//#endregion
 export { BriskRoute, CookieClient, CookieParser, CookieSerializer, ExceptionHandler, HttpContext, HttpRequest, HttpResponse, Qs, Redirect, ResponseStatus, Route, RouteGroup, RouteResource, Router, Server, defineConfig, errors_exports as errors, tracing_channels_exports as tracingChannels };

package/build/src/client/url_builder.d.ts

@@ -1,5 +1,5 @@
 import { createURL, findRoute } from './helpers.ts';
-import { type UrlFor, type LookupList, type ClientRouteJSON } from './types.ts';
+import { type UrlFor, type LookupList, type URLOptions, type ClientRouteJSON } from './types.ts';
 export * from './types.ts';
 export { createURL, findRoute };
 /**
@@ -12,4 +12,4 @@ export declare function createUrlBuilder<Routes extends LookupList>(routesLoader
     [domain: string]: ClientRouteJSON[];
 } | (() => {
     [domain: string]: ClientRouteJSON[];
-}), searchParamsStringifier: (qs: Record<string, any>) => string): UrlFor<Routes>;
+}), searchParamsStringifier: (qs: Record<string, any>) => string, defaultOptions?: URLOptions): UrlFor<Routes>;

package/build/src/client/url_builder.js

@@ -1,6 +1,13 @@
-import { n as findRoute, t as createURL } from "../../helpers-C_2HouOe.js";
-import "../../types-AUwURgIL.js";
-function createUrlBuilder(routesLoader, searchParamsStringifier) {
+import "../../chunk-B2GA45YG.js";
+import { n as findRoute, t as createURL } from "../../helpers-XD4_pfkD.js";
+//#region src/client/url_builder.ts
+/**
+* Creates the URLBuilder helper
+* @param router - The router instance
+* @param searchParamsStringifier - Function to stringify query string parameters
+* @returns URL builder function for creating URLs
+*/
+function createUrlBuilder(routesLoader, searchParamsStringifier, defaultOptions) {
 	let domainsList;
 	let domainsRoutes;
 	function createUrlForRoute(identifier, params, options, method) {
@@ -16,8 +23,16 @@ function createUrlBuilder(routesLoader, searchParamsStringifier) {
 			if (method) throw new Error(`Cannot lookup route "${routeIdentifier}" for method "${method}"`);
 			throw new Error(`Cannot lookup route "${routeIdentifier}"`);
 		}
-		return createURL(route.name ?? route.pattern, route.tokens, searchParamsStringifier, params, options);
+		const mergedOptions = defaultOptions || options ? {
+			...defaultOptions,
+			...options
+		} : void 0;
+		return createURL(route.name ?? route.pattern, route.tokens, searchParamsStringifier, params, mergedOptions);
 	}
+	/**
+	* The urlFor helper is used to make URLs for pre-existing known routes. You can
+	* make a URL using the route name or the route pattern.
+	*/
 	const urlFor = function route(...[identifier, params, options]) {
 		return createUrlForRoute(identifier, params, options);
 	};
@@ -112,4 +127,5 @@ function createUrlBuilder(routesLoader, searchParamsStringifier) {
 	};
 	return urlFor;
 }
+//#endregion
 export { createURL, createUrlBuilder, findRoute };

package/build/src/helpers.js

@@ -1,76 +1,4 @@
-import { n as safeDecodeURI } from "../utils-BjSHKI3s.js";
-import { t as createURL } from "../helpers-C_2HouOe.js";
-import { serialize } from "cookie-es";
-import matchit from "@poppinss/matchit";
-import string from "@poppinss/utils/string";
-import { parseBindingReference } from "@adonisjs/fold";
-import encodeUrl from "encodeurl";
-import mime from "mime-types";
-function parseRoute(pattern, matchers) {
-	return matchit.parse(pattern, matchers);
-}
-function createSignedURL(identifier, tokens, searchParamsStringifier, encryption, params, options) {
-	const signature = encryption.getMessageVerifier().sign(createURL(identifier, tokens, searchParamsStringifier, params, {
-		...options,
-		prefixUrl: void 0
-	}), options?.expiresIn, options?.purpose);
-	return createURL(identifier, tokens, searchParamsStringifier, params, {
-		...options,
-		qs: {
-			...options?.qs,
-			signature
-		}
-	});
-}
-function matchRoute(url, patterns) {
-	const tokensBucket = patterns.map((pattern) => parseRoute(pattern));
-	const match = matchit.match(url, tokensBucket);
-	if (!match.length) return null;
-	return matchit.exec(url, match);
-}
-function serializeCookie(key, value, options) {
-	let expires;
-	let maxAge;
-	if (options) {
-		expires = typeof options.expires === "function" ? options.expires() : options.expires;
-		maxAge = options.maxAge ? string.seconds.parse(options.maxAge) : void 0;
-	}
-	return serialize(key, value, {
-		...options,
-		maxAge,
-		expires
-	});
-}
-async function middlewareInfo(middleware) {
-	if (typeof middleware === "function") return {
-		type: "closure",
-		name: middleware.name || "closure"
-	};
-	if ("args" in middleware) return {
-		type: "named",
-		name: middleware.name,
-		args: middleware.args,
-		...await parseBindingReference([middleware.reference])
-	};
-	return {
-		type: "global",
-		name: middleware.name,
-		...await parseBindingReference([middleware.reference])
-	};
-}
-async function routeInfo(route) {
-	return "reference" in route.handler ? {
-		type: "controller",
-		...await parseBindingReference(route.handler.reference)
-	} : {
-		type: "closure",
-		name: route.handler.name || "closure",
-		args: "listArgs" in route.handler ? String(route.handler.listArgs) : void 0
-	};
-}
-function appendQueryString(uri, queryString, qsParser) {
-	const { query, pathname } = safeDecodeURI(uri, false);
-	const mergedQueryString = qsParser.stringify(Object.assign(qsParser.parse(query), queryString));
-	return mergedQueryString ? `${pathname}?${mergedQueryString}` : pathname;
-}
+import "../chunk-B2GA45YG.js";
+import { a as middlewareInfo, c as routeInfo, i as matchRoute, l as serializeCookie, n as createSignedURL, o as mime, r as encodeUrl, s as parseRoute, t as appendQueryString } from "../helpers-aa47NQc6.js";
+import { t as createURL } from "../helpers-XD4_pfkD.js";
 export { appendQueryString, createSignedURL, createURL, encodeUrl, matchRoute, middlewareInfo, mime, parseRoute, routeInfo, serializeCookie };

package/build/src/types/main.js

@@ -1 +1,2 @@
+import "../../chunk-B2GA45YG.js";
 export {};

package/build/src/types/request.d.ts

@@ -1,3 +1,4 @@
+import { type HttpRequest } from '../request.ts';
 /**
  * Configuration options for HTTP request handling and processing
  */
@@ -32,7 +33,7 @@ export type RequestConfig = {
     /**
      * A custom implementation to get the request ip address
      */
-    getIp?: (request: any) => string;
+    getIp?: (request: HttpRequest, originalFn: () => string) => string;
     /**
      * A callback function to trust proxy ip addresses. You must use
      * the `proxy-addr` package to compute this value.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonisjs/http-server",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "AdonisJS HTTP server with support packed with Routing and Cookies",
   "main": "build/index.js",
   "type": "module",
@@ -47,18 +47,18 @@
     "@adonisjs/eslint-config": "^3.0.0",
     "@adonisjs/events": "^10.1.0",
     "@adonisjs/fold": "^11.0.0",
-    "@adonisjs/logger": "^7.1.0",
+    "@adonisjs/logger": "^7.1.1",
     "@adonisjs/prettier-config": "^1.4.5",
     "@adonisjs/tsconfig": "^2.0.0",
     "@boringnode/encryption": "^1.0.0",
-    "@fastify/middie": "^9.1.0",
+    "@fastify/middie": "^9.3.1",
     "@japa/assert": "^4.2.0",
     "@japa/expect-type": "^2.0.4",
     "@japa/file-system": "^3.0.0",
     "@japa/runner": "^5.3.0",
     "@japa/snapshot": "^2.0.10",
     "@poppinss/ts-exec": "^1.4.4",
-    "@release-it/conventional-changelog": "^10.0.5",
+    "@release-it/conventional-changelog": "^10.0.6",
     "@types/accepts": "^1.3.7",
     "@types/content-disposition": "^0.5.9",
     "@types/destroy": "^1.0.3",
@@ -67,11 +67,11 @@
     "@types/fresh": "^0.5.3",
     "@types/fs-extra": "^11.0.4",
     "@types/mime-types": "^3.0.1",
-    "@types/node": "^25.3.0",
+    "@types/node": "^25.5.0",
     "@types/on-finished": "^2.3.5",
     "@types/pem": "^1.14.4",
     "@types/proxy-addr": "^2.0.3",
-    "@types/supertest": "^6.0.3",
+    "@types/supertest": "^7.2.0",
     "@types/type-is": "^1.6.7",
     "@types/vary": "^1.1.3",
     "@vinejs/vine": "^4.3.0",
@@ -79,9 +79,9 @@
     "autocannon": "^8.0.0",
     "c8": "^11.0.0",
     "cross-env": "^10.1.0",
-    "eslint": "^10.0.2",
-    "fastify": "^5.7.4",
-    "fs-extra": "^11.3.3",
+    "eslint": "^10.0.3",
+    "fastify": "^5.8.2",
+    "fs-extra": "^11.3.4",
     "get-port": "^7.1.0",
     "http-status-codes": "^2.3.0",
     "pem": "^1.14.8",
@@ -89,17 +89,17 @@
     "reflect-metadata": "^0.2.2",
     "release-it": "^19.2.4",
     "supertest": "^7.2.2",
-    "tsdown": "^0.20.3",
+    "tsdown": "^0.21.4",
     "typedoc": "^0.28.17",
     "typescript": "^5.9.3",
     "youch": "^4.1.0"
   },
   "dependencies": {
-    "@poppinss/macroable": "^1.1.0",
+    "@poppinss/macroable": "^1.1.2",
     "@poppinss/matchit": "^3.2.0",
     "@poppinss/middleware": "^3.2.7",
     "@poppinss/qs": "^6.15.0",
-    "@poppinss/utils": "^7.0.0",
+    "@poppinss/utils": "^7.0.1",
     "@sindresorhus/is": "^7.2.0",
     "content-disposition": "^1.0.1",
     "cookie-es": "^2.0.0",