@adonisjs/http-server 8.0.0-next.5 → 8.0.0-next.7

package/build/src/server/main.d.ts

@@ -13,74 +13,128 @@ import { Response } from '../response.ts';
 import { Router } from '../router/main.ts';
 import { HttpContext } from '../http_context/main.ts';
 /**
- * The HTTP server implementation to handle incoming requests and respond using the
- * registered routes.
+ * The Server class provides the core HTTP server implementation for AdonisJS.
+ *
+ * It handles incoming HTTP requests by processing them through middleware pipelines,
+ * routing them to appropriate handlers, and managing response generation. The server
+ * supports custom error handling, middleware registration, and various Node.js HTTP
+ * server configurations.
+ *
+ * @example
+ * ```ts
+ * const server = new Server(app, encryption, emitter, logger, config)
+ * server.use([AuthMiddleware, CorsMiddleware])
+ * server.errorHandler(() => import('./error_handler.ts'))
+ * await server.boot()
+ *
+ * http.createServer(server.handle.bind(server))
+ * ```
  */
 export declare class Server {
     #private;
     /**
-     * Check if the server has already been booted
+     * Indicates whether the server has completed its boot process
      */
     get booted(): boolean;
     /**
-     * Know if async local storage is enabled or not.
+     * Indicates whether async local storage is enabled for request context
      */
     get usingAsyncLocalStorage(): boolean;
+    /**
+     * Creates a new Server instance
+     *
+     * @param app - AdonisJS application instance
+     * @param encryption - Encryption service for secure operations
+     * @param emitter - Event emitter for server lifecycle events
+     * @param logger - Logger instance for server operations
+     * @param config - Server configuration settings
+     */
     constructor(app: Application<any>, encryption: Encryption, emitter: EmitterLike<HttpServerEvents>, logger: Logger, config: ServerConfig);
     /**
-     * Creates a pipeline of middleware.
+     * Creates a testing middleware pipeline for unit/integration testing
+     *
+     * @param middleware - Array of middleware classes to include in pipeline
+     * @returns TestingMiddlewarePipeline instance for test execution
      */
     pipeline(middleware: MiddlewareAsClass[]): TestingMiddlewarePipeline;
     /**
-     * Define an array of middleware to use on all the incoming HTTP request.
-     * Calling this method multiple times pushes to the existing list
-     * of middleware
+     * Registers global middleware to run on all incoming HTTP requests
+     *
+     * @param middleware - Array of lazy-imported middleware classes
+     * @returns The Server instance for method chaining
      */
     use(middleware: LazyImport<MiddlewareAsClass>[]): this;
     /**
-     * Register a custom error handler for HTTP requests.
-     * All errors will be reported to this method
+     * Registers a custom error handler for HTTP request processing
+     *
+     * @param handler - Lazy import of the error handler class
+     * @returns The Server instance for method chaining
      */
     errorHandler(handler: LazyImport<ErrorHandlerAsAClass>): this;
     /**
-     * Boot the server. Calling this method performs the following actions.
+     * Initializes the server by compiling middleware, committing routes, and resolving handlers
      *
-     * - Register routes with the store.
-     * - Resolve and construct the error handler.
+     * Performs the following operations:
+     * - Compiles the middleware stack
+     * - Commits registered routes to the router
+     * - Resolves and instantiates the custom error handler
      */
     boot(): Promise<void>;
     /**
-     * Set the HTTP server instance used to listen for requests.
+     * Configures the underlying Node.js HTTP/HTTPS server with timeout settings
+     *
+     * @param server - Node.js HTTP or HTTPS server instance
      */
     setNodeServer(server: HttpServer | HttpsServer): void;
     /**
-     * Returns reference to the underlying HTTP server
-     * in use
+     * Gets the underlying Node.js HTTP/HTTPS server instance
+     *
+     * @returns The configured server instance or undefined if not set
      */
     getNodeServer(): HttpServer<typeof IncomingMessage, typeof ServerResponse> | HttpsServer<typeof IncomingMessage, typeof ServerResponse> | undefined;
     /**
-     * Returns reference to the router instance used
-     * by the server.
+     * Gets the router instance used for route registration and matching
+     *
+     * @returns The Router instance
      */
     getRouter(): Router;
     /**
-     * Creates an instance of the [[Request]] class
+     * Creates a Request instance from Node.js request/response objects
+     *
+     * @param req - Node.js IncomingMessage
+     * @param res - Node.js ServerResponse
+     * @returns New Request instance
      */
     createRequest(req: IncomingMessage, res: ServerResponse): Request;
     /**
-     * Creates an instance of the [[Response]] class
+     * Creates a Response instance from Node.js request/response objects
+     *
+     * @param req - Node.js IncomingMessage
+     * @param res - Node.js ServerResponse
+     * @returns New Response instance
      */
     createResponse(req: IncomingMessage, res: ServerResponse): Response;
     /**
-     * Creates an instance of the [[HttpContext]] class
+     * Creates an HttpContext instance with request-specific logger
+     *
+     * @param request - Request instance
+     * @param response - Response instance
+     * @param resolver - Container resolver for dependency injection
+     * @returns New HttpContext instance
      */
     createHttpContext(request: Request, response: Response, resolver: ContainerResolver<any>): HttpContext;
     /**
-     * Returns a list of server middleware stack
+     * Gets the list of registered global middleware
+     *
+     * @returns Array of parsed global middleware
      */
     getMiddlewareList(): ParsedGlobalMiddleware[];
     /**
-     * Handle request
+     * Handles an incoming HTTP request by creating context and processing through pipeline
+     *
+     * @param req - Node.js IncomingMessage
+     * @param res - Node.js ServerResponse
+     * @returns Promise that resolves when request processing is complete
      */
     handle(req: IncomingMessage, res: ServerResponse): Promise<any>;
 }

package/build/src/tracing_channels.d.ts

@@ -1,13 +1,13 @@
 import diagnostics_channel from 'node:diagnostics_channel';
-import type { MiddlewareTracingData } from './types/tracing_channels.ts';
+import type { MiddlewareTracingData, HTTPRequestTracingData, RouteHandlerTracingData } from './types/tracing_channels.ts';
 /**
  * Traces every HTTP request handled by the {@link Server} class.
  */
-export declare const httpRequest: diagnostics_channel.TracingChannel<"adonisjs:http.request", import("./http_context/main.ts").HttpContext>;
+export declare const httpRequest: diagnostics_channel.TracingChannel<"adonisjs.http.request", HTTPRequestTracingData>;
 /**
  * Traces middleware executed during the HTTP request
  */
-export declare const httpMiddleware: diagnostics_channel.TracingChannel<"adonisjs:http.middleware", MiddlewareTracingData>;
+export declare const httpMiddleware: diagnostics_channel.TracingChannel<"adonisjs.http.middleware", MiddlewareTracingData>;
 /**
  * Traces the exception handler that converts errors into HTTP responses
  */
@@ -15,7 +15,7 @@ export declare const httpExceptionHandler: diagnostics_channel.TracingChannel<"a
 /**
  * Traces route handler executed during the HTTP request
  */
-export declare const httpRouteHandler: diagnostics_channel.TracingChannel<"adonisjs:http.route.handler", import("./types/route.ts").RouteJSON>;
+export declare const httpRouteHandler: diagnostics_channel.TracingChannel<"adonisjs.http.route.handler", RouteHandlerTracingData>;
 /**
  * Traces non-stream and non-file download responses written by the AdonisJS
  * response class

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

@@ -2,69 +2,94 @@ import type { ContainerResolver } from '@adonisjs/fold';
 import type { NextFn } from '@poppinss/middleware/types';
 import type { Constructor, LazyImport } from '@poppinss/utils/types';
 import type { HttpContext } from '../http_context/main.ts';
+export { NextFn };
 /**
- * Middleware represented as a class
+ * Middleware represented as a class constructor that implements a handle method
  */
 export type MiddlewareAsClass = Constructor<{
     handle: (ctx: HttpContext, next: NextFn, args?: any) => any;
 }>;
 /**
- * Check if a union has undefined or null
+ * Utility type to check if a union type includes undefined or null values
  */
 type HasUndefined<T> = T extends NonNullable<T> ? true : false;
 /**
- * Returns the arguments accepted by the middleware's handle method
+ * Extracts and returns the argument types accepted by a middleware's handle method
+ * Returns an empty array if no args, otherwise returns the args type as a tuple
  */
 export type GetMiddlewareArgs<Middleware extends MiddlewareAsClass> = Parameters<InstanceType<Middleware>['handle']>[2] extends undefined ? [] : HasUndefined<Parameters<InstanceType<Middleware>['handle']>[2]> extends true ? [Parameters<InstanceType<Middleware>['handle']>[2]] : [Parameters<InstanceType<Middleware>['handle']>[2]?];
 /**
- * The middleware defined as a function on the router or the server
+ * Middleware defined as a function that accepts HTTP context and next function
  */
 export type MiddlewareFn = (ctx: HttpContext, next: NextFn) => any;
 /**
- * Parsed global middleware
+ * Representation of a parsed global middleware with its metadata and execution handler
  */
 export type ParsedGlobalMiddleware = {
+    /** Optional name for the middleware */
     name?: string;
+    /** Reference to the middleware class or lazy import */
     reference: LazyImport<MiddlewareAsClass> | MiddlewareAsClass;
+    /** Handler function that executes the middleware */
     handle: (resolver: ContainerResolver<any>, ...args: [ctx: HttpContext, next: NextFn, params?: any]) => any;
 };
 /**
- * Parsed named middleware
+ * Representation of a parsed named middleware with its metadata, arguments and execution handler
  */
 export type ParsedNamedMiddleware = {
+    /** Name identifier for the middleware */
     name: string;
+    /** Reference to the middleware class or lazy import */
     reference: LazyImport<MiddlewareAsClass> | MiddlewareAsClass;
+    /** Handler function that executes the middleware */
     handle: ParsedGlobalMiddleware['handle'];
+    /** Arguments to pass to the middleware */
     args: any;
 };
 /**
- * Info node representing a middleware handler
+ * Information node describing different types of middleware handlers and their metadata
  */
 export type MiddlewareHandlerInfo = {
+    /** Type identifier for closure middleware */
     type: 'closure';
+    /** Name of the closure middleware */
     name: string;
 } | {
+    /** Type identifier for named middleware */
     type: 'named';
+    /** Name of the named middleware */
     name: string;
+    /** Arguments to pass to the middleware */
     args: any | undefined;
+    /** Method name on the middleware class */
     method: string;
+    /** Module name or file path for the middleware */
     moduleNameOrPath: string;
 } | {
+    /** Type identifier for global middleware */
     type: 'global';
+    /** Optional name for the global middleware */
     name?: string | undefined;
+    /** Method name on the middleware class */
     method: string;
+    /** Module name or file path for the middleware */
     moduleNameOrPath: string;
 };
 /**
- * Info node representing route handler
+ * Information node describing different types of route handlers and their metadata
  */
 export type RouteHandlerInfo = {
+    /** Type identifier for closure route handler */
     type: 'closure';
+    /** Name of the closure handler */
     name: string;
+    /** Optional arguments for the closure */
     args?: string;
 } | {
+    /** Type identifier for controller route handler */
     type: 'controller';
+    /** Method name on the controller class */
     method: string;
+    /** Module name or file path for the controller */
     moduleNameOrPath: string;
 };
-export {};

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

@@ -1,4 +1,8 @@
+/**
+ * Configuration options for query string parsing and stringification
+ */
 export type QSParserConfig = {
+    /** Configuration options for parsing query strings */
     parse: {
         /**
          * Nesting depth till the parameters should be parsed.
@@ -33,6 +37,7 @@ export type QSParserConfig = {
          */
         comma: boolean;
     };
+    /** Configuration options for stringifying query objects */
     stringify: {
         /**
          * URI encode the stringified query string

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

@@ -1,5 +1,5 @@
 /**
- * Shape of the request config
+ * Configuration options for HTTP request handling and processing
  */
 export type RequestConfig = {
     /**

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

@@ -1,25 +1,33 @@
 import { type Readable } from 'node:stream';
 /**
- * Cookie options can that can be set on the response
+ * Configuration options for HTTP cookies that can be set on the response
  */
 export type CookieOptions = {
+    /** Domain name for the cookie */
     domain: string;
+    /** Expiration date for the cookie or function that returns the date */
     expires: Date | (() => Date);
+    /** Whether the cookie should be accessible only through HTTP(S) */
     httpOnly: boolean;
+    /** Maximum age of the cookie in seconds or as a string */
     maxAge: number | string;
+    /** URL path for which the cookie is valid */
     path: string;
+    /** SameSite attribute to control cross-site request behavior */
     sameSite: boolean | 'lax' | 'none' | 'strict';
+    /** Whether the cookie should only be sent over HTTPS */
     secure: boolean;
+    /** Whether the cookie should be partitioned (optional) */
     partitioned?: boolean;
+    /** Priority level for the cookie (optional) */
     priority?: 'low' | 'medium' | 'high';
 };
 /**
- * Types from which response header can be casted to a
- * string
+ * Types that can be cast to a string for HTTP response headers
  */
 export type CastableHeader = string | number | boolean | string[] | number[] | boolean[];
 /**
- * Config accepted by response the class
+ * Configuration options for HTTP response handling and processing
  */
 export type ResponseConfig = {
     /**
@@ -36,11 +44,11 @@ export type ResponseConfig = {
      */
     jsonpCallbackName: string;
     /**
-     * Options to set cookies
+     * Default options to apply when setting cookies
      */
     cookie: Partial<CookieOptions>;
 };
 /**
- * Stream that can be piped to the "response.stream" method
+ * A readable stream that can be piped to the response stream method
  */
 export type ResponseStream = Readable;

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

@@ -5,81 +5,97 @@ import type { ServerErrorHandler } from './server.ts';
 import type { HttpContext } from '../http_context/main.ts';
 import type { MiddlewareFn, ParsedGlobalMiddleware } from './middleware.ts';
 /**
- * Shape of a route param matcher
+ * Configuration for matching and casting route parameters
  */
 export type RouteMatcher = {
+    /** Regular expression to match parameter values */
     match?: RegExp;
+    /** Function to cast string parameter values to specific types */
     cast?: (value: string) => any;
 };
 /**
- * Route token stored by matchit library
+ * Route token structure used internally by the matchit routing library
  */
 export type MatchItRouteToken = RouteMatcher & {
+    /** Original token string */
     old: string;
+    /** Token type identifier (0=static, 1=param, 2=wildcard, 3=optional) */
     type: 0 | 1 | 2 | 3;
+    /** Token value */
     val: string;
+    /** Token end delimiter */
     end: string;
 };
 /**
- * Returns a union of methods from a controller that accepts
- * the context as the first argument.
+ * Extracts method names from a controller class that accept HttpContext as first parameter
  */
 export type GetControllerHandlers<Controller extends Constructor<any>> = {
     [K in keyof InstanceType<Controller>]: InstanceType<Controller>[K] extends (ctx: HttpContext, ...args: any[]) => any ? K : never;
 }[keyof InstanceType<Controller>];
 /**
- * Route handler defined as a function
+ * Route handler implemented as a function that accepts HTTP context
  */
 export type RouteFn = (ctx: HttpContext) => any;
 /**
- * Route handler persisted with the route store
+ * Route handler representation stored in the route registry
  */
 export type StoreRouteHandler = RouteFn | {
+    /** Optional name for the handler */
     name?: string;
+    /** Method name on the controller */
     method: string;
+    /** Dynamic import expression for lazy loading */
     importExpression: string | null;
+    /** Reference to controller class or method */
     reference: string | [LazyImport<Constructor<any>> | Constructor<any>, any?];
+    /** Handler execution function */
     handle: (resolver: ContainerResolver<any>, ...args: [ctx: HttpContext, ...injections: any[]]) => any;
 };
 /**
- * The middleware persisted with the route store
+ * Middleware representation stored with route information
  */
 export type StoreRouteMiddleware = MiddlewareFn | ({
     name?: string;
     args?: any[];
 } & ParsedGlobalMiddleware);
 /**
- * An object of routes for a given HTTP method
+ * Route storage structure for a specific HTTP method containing tokens and route mappings
  */
 export type StoreMethodNode = {
+    /** Array of route tokens for pattern matching */
     tokens: MatchItRouteToken[][];
+    /** Mapping from route patterns to unique route keys */
     routeKeys: {
         [pattern: string]: string;
     };
+    /** Mapping from route patterns to route definitions */
     routes: {
         [pattern: string]: RouteJSON;
     };
 };
 /**
- * Each domain node container an object of methods. Each method
- * object has nested routes.
+ * Domain-specific route storage containing method-based route organization
  */
 export type StoreDomainNode = {
+    /** HTTP method to method node mapping */
     [method: string]: StoreMethodNode;
 };
 /**
- * Routes tree stored within the routes store
+ * Complete route tree structure organizing routes by domains and methods
  */
 export type StoreRoutesTree = {
+    /** Global route tokens for pattern matching */
     tokens: MatchItRouteToken[][];
+    /** Domain-based route organization */
     domains: {
         [domain: string]: StoreDomainNode;
     };
 };
 /**
- * Shape of the matched route for a pattern, method and domain.
+ * Result of successful route matching containing route details and extracted parameters
  */
 export type MatchedRoute = {
+    /** The matched route definition */
     route: RouteJSON;
     /**
      * A unique key for the looked up route
@@ -95,13 +111,14 @@ export type MatchedRoute = {
     subdomains: Record<string, any>;
 };
 /**
- * A collection of route matchers
+ * Collection of parameter matchers indexed by parameter name
  */
 export type RouteMatchers = {
+    /** Parameter name to matcher mapping */
     [param: string]: RouteMatcher;
 };
 /**
- * Representation of a route as JSON
+ * Complete route definition with all metadata, handlers, and execution context
  */
 export type RouteJSON = {
     /**
@@ -147,24 +164,28 @@ export type RouteJSON = {
     matchers: RouteMatchers;
 };
 /**
- * Resource action names
+ * Standard RESTful resource action names for CRUD operations
  */
 export type ResourceActionNames = 'create' | 'index' | 'store' | 'show' | 'edit' | 'update' | 'destroy';
 /**
- * Options accepted by makeUrl method
- * @deprecated
+ * @deprecated Options for URL generation (use URLBuilder instead)
  */
 export type MakeUrlOptions = {
+    /** Query string parameters to append */
     qs?: Record<string, any>;
+    /** Domain name to use for the URL */
     domain?: string;
+    /** Prefix to prepend to the generated URL */
     prefixUrl?: string;
+    /** Whether to disable route lookup optimization */
     disableRouteLookup?: boolean;
 };
 /**
- * Options accepted by makeSignedUrl method
- * @deprecated
+ * @deprecated Options for signed URL generation (use URLBuilder instead)
  */
 export type MakeSignedUrlOptions = MakeUrlOptions & {
+    /** Expiration time for the signed URL */
     expiresIn?: string | number;
+    /** Purpose identifier for the signed URL */
     purpose?: string;
 };

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

@@ -5,63 +5,78 @@ import type { RequestConfig } from './request.ts';
 import type { ResponseConfig } from './response.ts';
 import type { HttpContext } from '../http_context/main.ts';
 /**
- * Normalized HTTP error used by the exception
- * handler.
+ * Normalized HTTP error structure used by exception handlers
  */
 export type HttpError = {
+    /** Error message describing the issue */
     message: string;
+    /** HTTP status code */
     status: number;
+    /** Optional error code identifier */
     code?: string;
+    /** Optional stack trace */
     stack?: string;
+    /** Optional underlying cause of the error */
     cause?: any;
+    /** Optional additional error messages */
     messages?: any;
+    /** Optional validation or field errors */
     errors?: any;
+    /** Optional custom error handler method */
     handle?: (...args: any[]) => any;
+    /** Optional error reporting method */
     report?: (...args: any[]) => any;
 };
 /**
- * The pipeline for executing middleware during tests
+ * Pipeline interface for executing middleware chains during testing
  */
 export interface TestingMiddlewarePipeline {
+    /** Set the final handler for the pipeline */
     finalHandler(handler: FinalHandler): this;
+    /** Set the error handler for the pipeline */
     errorHandler(handler: ErrorHandler): this;
+    /** Execute the middleware pipeline with the given context */
     run(ctx: HttpContext): Promise<any>;
 }
 /**
- * The expression to define a status page range
+ * Expression format for defining HTTP status code ranges for error pages
  */
 export type StatusPageRange = `${number}..${number}` | `${number}` | number;
 /**
- * The callback function to render status page for a given
- * error.
+ * Callback function to render custom status pages for HTTP errors
  */
 export type StatusPageRenderer = (error: HttpError, ctx: HttpContext) => any | Promise<any>;
 /**
- * Data type for the "http:request_completed" event
+ * Payload structure for the http:request_completed event
  */
 export type HttpRequestFinishedPayload = {
+    /** HTTP context for the completed request */
     ctx: HttpContext;
+    /** Request duration as a high-resolution time tuple */
     duration: [number, number];
 };
 /**
- * Events emitted by the HttpServer
+ * Event types and payloads emitted by the HTTP server
  */
 export type HttpServerEvents = {
+    /** Event fired when an HTTP request is completed */
     'http:request_completed': HttpRequestFinishedPayload;
 };
 /**
- * Error handler to handle HTTP errors
+ * Interface for handling and reporting HTTP errors in the server
  */
 export type ServerErrorHandler = {
+    /** Method to report errors for logging or monitoring */
     report: (error: any, ctx: HttpContext) => any;
+    /** Method to handle errors and send appropriate responses */
     handle: (error: any, ctx: HttpContext) => any;
 };
 /**
- * Error handler represented as a class
+ * Constructor type for error handler classes that implement ServerErrorHandler
  */
 export type ErrorHandlerAsAClass = Constructor<ServerErrorHandler>;
 /**
- * Config accepted by the HTTP server
+ * Complete configuration options for the HTTP server extending request and response configs
  */
 export type ServerConfig = RequestConfig & ResponseConfig & {
     /**

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

@@ -1,6 +1,24 @@
 import type { RouteJSON } from './route.ts';
 import type { HttpContext } from '../http_context/main.ts';
 import type { MiddlewareFn, ParsedGlobalMiddleware, ParsedNamedMiddleware } from './middleware.ts';
-export type HTTPRequestTracingData = HttpContext;
-export type MiddlewareTracingData = ParsedGlobalMiddleware | ParsedNamedMiddleware | MiddlewareFn;
-export type RouteHandlerTracingData = RouteJSON;
+/**
+ * Tracing data structure for HTTP request events
+ */
+export type HTTPRequestTracingData = {
+    /** HTTP context for the traced request */
+    ctx: HttpContext;
+};
+/**
+ * Tracing data structure for middleware execution events
+ */
+export type MiddlewareTracingData = {
+    /** The middleware being traced */
+    middleware: ParsedGlobalMiddleware | ParsedNamedMiddleware | MiddlewareFn;
+};
+/**
+ * Tracing data structure for route handler execution events
+ */
+export type RouteHandlerTracingData = {
+    /** The route being traced */
+    route: RouteJSON;
+};