@adonisjs/http-server 8.1.2 → 8.1.3

package/build/{helpers-C_2HouOe.js → helpers-Dqw8abku.js}

@@ -1,4 +1,28 @@
+//#region src/client/helpers.ts
+/**
+* Finds a route by its identifier across domains.
+*
+* Searches for routes by name, pattern, or controller reference. When no domain
+* is specified, searches across all domains. Supports legacy lookup strategies
+* for backwards compatibility.
+*
+* @param domainsRoutes - Object mapping domain names to route arrays
+* @param routeIdentifier - Route name, pattern, or controller reference to find
+* @param domain - Optional domain to limit search scope
+* @param method - Optional HTTP method to filter routes
+* @param disableLegacyLookup - Whether to disable pattern and controller lookup
+*
+* @example
+* ```ts
+* const route = findRoute(routes, 'users.show', 'api', 'GET')
+* const route2 = findRoute(routes, '/users/:id', undefined, 'GET')
+* ```
+*/
 function findRoute(domainsRoutes, routeIdentifier, domain, method, disableLegacyLookup) {
+	/**
+	* Search for route in all the domains when no domain name is
+	* mentioned.
+	*/
 	if (!domain) {
 		let route = null;
 		for (const routeDomain of Object.keys(domainsRoutes)) {
@@ -9,6 +33,10 @@ function findRoute(domainsRoutes, routeIdentifier, domain, method, disableLegacy
 	}
 	const routes = domainsRoutes[domain];
 	if (!routes) return null;
+	/**
+	* Pattern and controller are supported for legacy reasons. However
+	* the URL builder only works with names
+	*/
 	const lookupByPattern = !disableLegacyLookup;
 	const lookupByController = !disableLegacyLookup;
 	return routes.find((route) => {
@@ -18,16 +46,34 @@ function findRoute(domainsRoutes, routeIdentifier, domain, method, disableLegacy
 		return false;
 	}) || null;
 }
+/**
+* Makes URL for a given route pattern using its parsed tokens. The
+* tokens could be generated using the "parseRoute" method.
+*
+* @param pattern - The route pattern
+* @param tokens - Array of parsed route tokens
+* @param searchParamsStringifier - Function to stringify query parameters
+* @param params - Route parameters as array or object
+* @param options - URL options
+* @returns {string} The generated URL
+*/
 function createURL(pattern, tokens, searchParamsStringifier, params, options) {
 	const uriSegments = [];
 	const paramsArray = Array.isArray(params) ? params : null;
 	const paramsObject = !Array.isArray(params) ? params ?? {} : {};
 	let paramsIndex = 0;
 	for (const token of tokens) {
+		/**
+		* Static param
+		*/
 		if (token.type === 0) {
 			uriSegments.push(token.val === "/" ? "" : `${token.val}${token.end}`);
 			continue;
 		}
+		/**
+		* Wildcard param. It will always be the last param, hence we will provide
+		* it all the remaining values
+		*/
 		if (token.type === 2) {
 			const values = paramsArray ? paramsArray.slice(paramsIndex) : paramsObject["*"];
 			if (!Array.isArray(values) || !values.length) throw new Error(`Cannot make URL for "${pattern}". Invalid value provided for the wildcard param`);
@@ -37,16 +83,26 @@ function createURL(pattern, tokens, searchParamsStringifier, params, options) {
 		const paramName = token.val;
 		const value = paramsArray ? paramsArray[paramsIndex] : paramsObject[paramName];
 		const isDefined = value !== void 0 && value !== null;
+		/**
+		* Required param
+		*/
 		if (token.type === 1 && !isDefined) throw new Error(`Cannot make URL for "${pattern}". Missing value for the "${paramName}" param`);
 		if (isDefined) uriSegments.push(`${value}${token.end}`);
 		paramsIndex++;
 	}
 	let URI = `/${uriSegments.join("/")}`;
+	/**
+	* Prefix base URL
+	*/
 	if (options?.prefixUrl) URI = `${options?.prefixUrl.replace(/\/$/, "")}${URI}`;
+	/**
+	* Append query string
+	*/
 	if (options?.qs) {
 		const queryString = searchParamsStringifier(options?.qs);
 		URI = queryString ? `${URI}?${queryString}` : URI;
 	}
 	return URI;
 }
+//#endregion
 export { findRoute as n, createURL as t };

package/build/index.js

@@ -1,27 +1,90 @@
-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-BRmlbWlB.js";
-import "./helpers-C_2HouOe.js";
-import "./types-AUwURgIL.js";
+import { C as tracing_channels_exports, _ as BriskRoute, d as parseRange, g as RouteResource, h as RouteGroup, v as Route, w as canWriteResponseBody } from "./helpers-CLk8RLHd.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-drp-Wzwx.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 +93,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 +148,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 +163,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 +182,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 +212,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 +237,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 +265,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 +282,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 +295,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.js

@@ -1,5 +1,11 @@
-import { n as findRoute, t as createURL } from "../../helpers-C_2HouOe.js";
-import "../../types-AUwURgIL.js";
+import { n as findRoute, t as createURL } from "../../helpers-Dqw8abku.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;
@@ -22,6 +28,10 @@ function createUrlBuilder(routesLoader, searchParamsStringifier, defaultOptions)
 		} : 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);
 	};
@@ -116,4 +126,5 @@ function createUrlBuilder(routesLoader, searchParamsStringifier, defaultOptions)
 	};
 	return urlFor;
 }
+//#endregion
 export { createURL, createUrlBuilder, findRoute };

package/build/src/helpers.d.ts

@@ -1,3 +1,4 @@
+import type { IncomingHttpHeaders } from 'node:http';
 import { type Encryption } from '@boringnode/encryption';
 import { type Qs } from './qs.ts';
 import { createURL } from './client/helpers.ts';
@@ -6,6 +7,20 @@ import { type SignedURLOptions } from './types/url_builder.ts';
 import type { RouteMatchers, RouteJSON, MatchItRouteToken } from './types/route.ts';
 import { type MiddlewareFn, type RouteHandlerInfo, type MiddlewareHandlerInfo, type ParsedGlobalMiddleware, type ParsedNamedMiddleware } from './types/middleware.ts';
 export { createURL };
+/**
+ * Returns the previous URL from the request's `Referer` header,
+ * validated against the request's `Host` header and an optional
+ * list of allowed hosts.
+ *
+ * The referrer is accepted when its host matches the request's
+ * `Host` header or is listed in `allowedHosts`. Otherwise the
+ * `fallback` value is returned.
+ *
+ * @param headers - The incoming request headers
+ * @param allowedHosts - Array of allowed referrer hosts
+ * @param fallback - URL to return when referrer is missing or invalid
+ */
+export declare function getPreviousUrl(headers: IncomingHttpHeaders, allowedHosts: string[], fallback: string): string;
 /**
  * This function is similar to the intrinsic function encodeURI. However, it will not encode:
  *  - The \, ^, or | characters

package/build/src/helpers.js

@@ -1,76 +1,3 @@
-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;
-}
-export { appendQueryString, createSignedURL, createURL, encodeUrl, matchRoute, middlewareInfo, mime, parseRoute, routeInfo, serializeCookie };
+import { a as matchRoute, c as parseRoute, i as getPreviousUrl, l as routeInfo, n as createSignedURL, o as middlewareInfo, r as encodeUrl, s as mime, t as appendQueryString, u as serializeCookie } from "../helpers-CLk8RLHd.js";
+import { t as createURL } from "../helpers-Dqw8abku.js";
+export { appendQueryString, createSignedURL, createURL, encodeUrl, getPreviousUrl, matchRoute, middlewareInfo, mime, parseRoute, routeInfo, serializeCookie };

package/build/src/redirect.d.ts

@@ -2,7 +2,9 @@ import type { IncomingMessage } from 'node:http';
 import type { Qs } from './qs.ts';
 import type { Router } from './router/main.ts';
 import type { HttpResponse } from './response.ts';
+import type { ResponseConfig } from './types/response.ts';
 import type { RoutesList, LookupList, URLOptions, GetRoutesForMethod, RouteBuilderArguments } from './types/url_builder.ts';
+import Macroable from '@poppinss/macroable';
 /**
  * Provides a fluent API for constructing HTTP redirect responses.
  *
@@ -25,16 +27,33 @@ import type { RoutesList, LookupList, URLOptions, GetRoutesForMethod, RouteBuild
  *   .toPath('/dashboard')
  * ```
  */
-export declare class Redirect {
+export declare class Redirect extends Macroable {
     #private;
+    /**
+     * Array of allowed hosts for referrer-based redirects.
+     * When empty, only the request's own host is allowed.
+     */
+    allowedHosts: string[];
     /**
      * Creates a new Redirect instance for handling HTTP redirects
      * @param request - Node.js incoming HTTP request
      * @param response - AdonisJS response instance
      * @param router - AdonisJS router instance
      * @param qs - Query string parser instance
+     * @param config - Redirect configuration
+     */
+    constructor(request: IncomingMessage, response: HttpResponse, router: Router, qs: Qs, config: ResponseConfig['redirect']);
+    /**
+     * Returns the previous URL for redirect back. By default reads
+     * the `Referer` header and validates the host.
+     *
+     * Since `Redirect` extends `Macroable`, this method can be overridden
+     * to implement custom logic such as session-based previous URL
+     * resolution.
+     *
+     * @param fallback - URL to return when no valid previous URL is found
      */
-    constructor(request: IncomingMessage, response: HttpResponse, router: Router, qs: Qs);
+    getPreviousUrl(fallback: string): string;
     /**
      * Sets a custom HTTP status code for the redirect response
      * @param statusCode - HTTP status code to use (e.g., 301, 302, 307)
@@ -62,6 +81,23 @@ export declare class Redirect {
      * ```
      */
     withQs(): this;
+    /**
+     * Enables or disables query string forwarding from the current request.
+     *
+     * Use this overload to explicitly control query string forwarding,
+     * especially useful when `forwardQueryString` is enabled by default
+     * in the redirect config and you want to disable it for a specific redirect.
+     *
+     * @param forward - Whether to forward the query string
+     * @returns The Redirect instance for method chaining
+     *
+     * @example
+     * ```ts
+     * // Disable query string forwarding for this redirect
+     * response.redirect().withQs(false).toPath('/dashboard')
+     * ```
+     */
+    withQs(forward: boolean): this;
     /**
      * Adds multiple query string parameters to the redirect URL
      *
@@ -96,10 +132,11 @@ export declare class Redirect {
      */
     withQs(name: string, value: any): this;
     /**
-     * Redirects to the previous path using the Referer header
-     * Falls back to '/' if no referrer is found
+     * Redirects to the previous URL resolved via `getPreviousUrl`.
+     *
+     * @param fallback - URL to redirect to when no valid previous URL is found
      */
-    back(): void;
+    back(fallback?: string): void;
     /**
      * Redirects to a route using its identifier (name, pattern, or handler reference)
      * @param args - Route identifier, parameters, and options for URL building

package/build/src/request.d.ts

@@ -393,6 +393,18 @@ export declare class HttpRequest extends Macroable {
      * @returns {string} Complete URL including protocol and host
      */
     completeUrl(includeQueryString?: boolean): string;
+    /**
+     * Returns the previous URL from the `Referer` header, validated against
+     * the request's `Host` header and an optional list of allowed hosts.
+     *
+     * The referrer is accepted when its host matches the request's `Host`
+     * header or is listed in `allowedHosts`. Otherwise the `fallback`
+     * value is returned.
+     *
+     * @param allowedHosts - Array of allowed referrer hosts
+     * @param fallback - URL to return when referrer is missing or invalid
+     */
+    getPreviousUrl(allowedHosts: string[], fallback?: string): string;
     /**
      * Find if the current HTTP request is for the given route or the routes
      * @param routeIdentifier - Route name, pattern, or handler reference to match

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

@@ -52,6 +52,25 @@ export type ResponseConfig = {
      * Default options to apply when setting cookies
      */
     cookie: Partial<CookieOptions>;
+    /**
+     * Configuration for HTTP redirects
+     */
+    redirect: {
+        /**
+         * Array of allowed hosts for referrer-based redirects.
+         * When empty, only the request's own host is allowed.
+         *
+         * Defaults to []
+         */
+        allowedHosts: string[];
+        /**
+         * Whether to forward the query string from the current request
+         * by default on redirects.
+         *
+         * Defaults to false
+         */
+        forwardQueryString: boolean;
+    };
 };
 /**
  * A readable stream that can be piped to the response stream method