@adonisjs/http-server 8.0.0-next.1 → 8.0.0-next.10

package/build/src/router/store.d.ts

@@ -44,6 +44,8 @@ export declare class RoutesStore {
      *   }
      * })
      * ```
+     * @param route - The route to add to the store
+     * @returns Current RoutesStore instance for method chaining
      */
     add(route: RouteJSON): this;
     /**
@@ -54,6 +56,11 @@ export declare class RoutesStore {
      * The domain parameter has to be a registered pattern and not the fully
      * qualified runtime domain. You must call `matchDomain` first to fetch
      * the pattern for qualified domain
+     * @param url - The URL to match
+     * @param method - HTTP method
+     * @param shouldDecodeParam - Whether to decode parameters
+     * @param domain - Optional domain tokens and hostname
+     * @returns Matched route or null if no match found
      */
     match(url: string, method: string, shouldDecodeParam: boolean, domain?: {
         tokens: MatchItRouteToken[];
@@ -61,6 +68,8 @@ export declare class RoutesStore {
     }): null | MatchedRoute;
     /**
      * Match hostname against registered domains.
+     * @param hostname - The hostname to match
+     * @returns Array of matched domain tokens
      */
     matchDomain(hostname?: string | null): MatchItRouteToken[];
 }

package/build/src/server/factories/middleware_handler.d.ts

@@ -3,6 +3,15 @@ import type { NextFn } from '@poppinss/middleware/types';
 import type { HttpContext } from '../../http_context/main.ts';
 import { type ParsedGlobalMiddleware } from '../../types/middleware.ts';
 /**
- * The middleware handler invokes the middleware functions.
+ * Creates a middleware execution handler that invokes middleware functions with tracing support
+ *
+ * This factory function returns a middleware execution handler that:
+ * - Executes middleware with debug logging
+ * - Provides distributed tracing through tracing channels
+ * - Passes the container resolver, HTTP context, and next function to middleware
+ *
+ * @param resolver - Container resolver for dependency injection
+ * @param ctx - HTTP context containing request/response data
+ * @returns Middleware execution function
  */
 export declare function middlewareHandler(resolver: ContainerResolver<any>, ctx: HttpContext): (fn: ParsedGlobalMiddleware, next: NextFn) => Promise<any>;

package/build/src/server/factories/route_finder.d.ts

@@ -3,8 +3,18 @@ import type { Router } from '../../router/main.ts';
 import type { HttpContext } from '../../http_context/main.ts';
 import type { ServerErrorHandler } from '../../types/server.ts';
 /**
- * The route finder is executed after the server middleware stack.
- * It looks for a matching route and executes the route middleware
- * stack.
+ * Creates a route finder function that matches HTTP requests to registered routes
+ *
+ * This factory function returns a route handler that:
+ * - Matches incoming requests against registered routes
+ * - Extracts route parameters and subdomains
+ * - Executes the matched route's handler and middleware
+ * - Throws E_ROUTE_NOT_FOUND error for unmatched requests
+ *
+ * @param router - Router instance containing registered routes
+ * @param resolver - Container resolver for dependency injection
+ * @param ctx - HTTP context containing request/response data
+ * @param errorResponder - Error handler for route execution errors
+ * @returns Route execution function
  */
 export declare function routeFinder(router: Router, resolver: ContainerResolver<any>, ctx: HttpContext, errorResponder: ServerErrorHandler['handle']): () => any;

package/build/src/server/factories/write_response.d.ts

@@ -1,6 +1,13 @@
 import type { HttpContext } from '../../http_context/main.ts';
 /**
- * Writes the response to the socket. The "finish" method can
- * raise error when unable to serialize the response.
+ * Creates a response writer function that finalizes HTTP responses with error handling
+ *
+ * This factory function returns a response finalizer that:
+ * - Calls the response.finish() method to send the response
+ * - Catches serialization errors and sends a 500 error response
+ * - Logs fatal errors for debugging and monitoring
+ *
+ * @param ctx - HTTP context containing the response to finalize
+ * @returns Response finalization function
  */
 export declare function writeResponse(ctx: HttpContext): () => void;

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

@@ -4,79 +4,90 @@ import type { Constructor, LazyImport } from '@poppinss/utils/types';
 import type { ServerErrorHandler } from './server.ts';
 import type { HttpContext } from '../http_context/main.ts';
 import type { MiddlewareFn, ParsedGlobalMiddleware } from './middleware.ts';
+import { type ClientRouteJSON, type ClientRouteMatchItTokens } from '../client/types.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 & {
-    old: string;
-    type: 0 | 1 | 2 | 3;
-    val: string;
-    end: string;
-};
+export type MatchItRouteToken = RouteMatcher & ClientRouteMatchItTokens;
 /**
- * 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
@@ -92,28 +103,21 @@ 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 = {
+export type RouteJSON = Pick<ClientRouteJSON, 'name' | 'methods' | 'domain' | 'pattern'> & {
     /**
      * The execute function to execute the route middleware
      * and the handler
      */
     execute: (route: RouteJSON, resolver: ContainerResolver<any>, ctx: HttpContext, errorResponder: ServerErrorHandler['handle']) => any;
-    /**
-     * A unique name for the route
-     */
-    name?: string;
-    /**
-     * Route URI pattern
-     */
-    pattern: string;
     /**
      * Route handler
      */
@@ -130,38 +134,34 @@ export type RouteJSON = {
      * Tokens to be used to construct the route URL
      */
     tokens: MatchItRouteToken[];
-    /**
-     * HTTP methods, the route responds to.
-     */
-    methods: string[];
-    /**
-     * The domain for which the route is registered.
-     */
-    domain: string;
     /**
      * Matchers for route params.
      */
     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;
 };