@adonisjs/http-server 6.8.2-1 → 6.8.2-10

package/build/src/router/store.js

@@ -1,16 +1,61 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+// @ts-expect-error
 import matchit from '@poppinss/matchit';
 import lodash from '@poppinss/utils/lodash';
 import { RuntimeException } from '@poppinss/utils';
+import { parseRoutePattern } from './parser.js';
+import debug from '../debug.js';
+/**
+ * Store class is used to store a list of routes, along side with their tokens
+ * to match the URLs.
+ *
+ * ```ts
+ * const store = new Store()
+ *
+ * store.add({
+ *  pattern: 'posts/:id',
+ *  handler: function onRoute () {},
+ *  middleware: [],
+ *  matchers: {
+ *    id: '^[0-9]$+'
+ *  },
+ *  meta: {},
+ *  methods: ['GET']
+ * })
+ *
+ * store.match('posts/1', 'GET')
+ * ```
+ */
 export class RoutesStore {
+    /**
+     * A flag to know if routes for explicit domains
+     * have been registered
+     */
     usingDomains = false;
+    /**
+     * Tree of registered routes and their matchit tokens
+     */
     tree = { tokens: [], domains: {} };
+    /**
+     * Returns the domain node for a given domain.
+     */
     #getDomainNode(domain) {
         if (!this.tree.domains[domain]) {
-            this.tree.tokens.push(matchit.parse(domain));
+            this.tree.tokens.push(parseRoutePattern(domain));
             this.tree.domains[domain] = {};
         }
         return this.tree.domains[domain];
     }
+    /**
+     * Returns the method node for a given domain and method.
+     */
     #getMethodNode(domain, method) {
         const domainNode = this.#getDomainNode(domain);
         if (!domainNode[method]) {
@@ -18,6 +63,9 @@ export class RoutesStore {
         }
         return domainNode[method];
     }
+    /**
+     * Collects route params
+     */
     #collectRouteParams(route, tokens) {
         const collectedParams = new Set();
         for (let token of tokens) {
@@ -34,38 +82,95 @@ export class RoutesStore {
         collectedParams.clear();
         return params;
     }
+    /**
+     * Register route for a given domain and method
+     */
     #registerRoute(domain, method, tokens, route) {
         const methodRoutes = this.#getMethodNode(domain, method);
+        /*
+         * Check for duplicate route for the same domain and method
+         */
         if (methodRoutes.routes[route.pattern]) {
             throw new RuntimeException(`Duplicate route found. "${method}: ${route.pattern}" route already exists`);
         }
+        if (debug.enabled) {
+            debug('registering route to the store %O', route);
+            debug('route middleware %O', route.middleware.all().entries());
+        }
         methodRoutes.tokens.push(tokens);
         methodRoutes.routes[route.pattern] = route;
         methodRoutes.routeKeys[route.pattern] =
             domain !== 'root' ? `${domain}-${method}-${route.pattern}` : `${method}-${route.pattern}`;
     }
+    /**
+     * Add a route to the store
+     *
+     * ```ts
+     * store.add({
+     *   pattern: 'post/:id',
+     *   methods: ['GET'],
+     *   matchers: {},
+     *   meta: {},
+     *   handler: function handler () {
+     *   }
+     * })
+     * ```
+     */
     add(route) {
+        /**
+         * Set flag when a custom domain is used
+         */
         if (route.domain !== 'root') {
             this.usingDomains = true;
         }
-        const tokens = matchit.parse(route.pattern, route.matchers);
+        /**
+         * Generate tokens for the route
+         */
+        const tokens = parseRoutePattern(route.pattern, route.matchers);
+        /**
+         * Create route node object for persistence
+         */
         const routeNode = lodash.merge({ meta: {} }, lodash.pick(route, ['pattern', 'handler', 'meta', 'middleware', 'name', 'execute']));
+        /**
+         * Set route params
+         */
         routeNode.meta.params = this.#collectRouteParams(routeNode, tokens);
+        /**
+         * Register route for every method
+         */
         route.methods.forEach((method) => {
             this.#registerRoute(route.domain, method, tokens, routeNode);
         });
         return this;
     }
+    /**
+     * Matches the url, method and optionally domain to pull the matching
+     * route. `null` is returned when unable to match the URL against
+     * registered routes.
+     *
+     * 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
+     */
     match(url, method, domain) {
         const domainName = domain?.tokens[0]?.old || 'root';
         const matchedDomain = this.tree.domains[domainName];
         if (!matchedDomain) {
             return null;
         }
+        /*
+         * Next get the method node for the given method inside the domain. If
+         * method node is missing, means no routes ever got registered for that
+         * method
+         */
         const matchedMethod = this.tree.domains[domainName][method];
         if (!matchedMethod) {
             return null;
         }
+        /*
+         * Next, match route for the given url inside the tokens list for the
+         * matchedMethod
+         */
         const matchedRoute = matchit.match(url, matchedMethod.tokens);
         if (!matchedRoute.length) {
             return null;
@@ -78,6 +183,9 @@ export class RoutesStore {
             subdomains: domain?.hostname ? matchit.exec(domain.hostname, domain.tokens) : {},
         };
     }
+    /**
+     * Match hostname against registered domains.
+     */
     matchDomain(hostname) {
         if (!hostname || !this.usingDomains) {
             return [];

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

@@ -1,4 +1,10 @@
 import type { ContainerResolver } from '@adonisjs/fold';
 import type { Router } from '../../router/main.js';
 import type { HttpContext } from '../../http_context/main.js';
-export declare function finalHandler(router: Router, resolver: ContainerResolver<any>, ctx: HttpContext): () => any;
+import type { ServerErrorHandler } from '../../types/server.js';
+/**
+ * The final handler is executed after the server middleware stack.
+ * It looks for a matching route and executes the route middleware
+ * stack.
+ */
+export declare function finalHandler(router: Router, resolver: ContainerResolver<any>, ctx: HttpContext, errorResponder: ServerErrorHandler['handle']): () => any;

package/build/src/server/factories/final_handler.js

@@ -1,5 +1,18 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import * as errors from '../../exceptions.js';
-export function finalHandler(router, resolver, ctx) {
+/**
+ * The final handler is executed after the server middleware stack.
+ * It looks for a matching route and executes the route middleware
+ * stack.
+ */
+export function finalHandler(router, resolver, ctx, errorResponder) {
     return function () {
         const url = ctx.request.url();
         const method = ctx.request.method();
@@ -10,7 +23,7 @@ export function finalHandler(router, resolver, ctx) {
             ctx.subdomains = route.subdomains;
             ctx.route = route.route;
             ctx.routeKey = route.routeKey;
-            return route.route.execute(route.route, resolver, ctx);
+            return route.route.execute(route.route, resolver, ctx, errorResponder);
         }
         return Promise.reject(new errors.E_ROUTE_NOT_FOUND([method, url]));
     };

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

@@ -2,4 +2,7 @@ import type { NextFn } from '@poppinss/middleware/types';
 import type { ContainerResolver } from '@adonisjs/fold';
 import type { HttpContext } from '../../http_context/main.js';
 import { ParsedGlobalMiddleware } from '../../types/middleware.js';
+/**
+ * The middleware handler invokes the middleware functions.
+ */
 export declare function middlewareHandler(resolver: ContainerResolver<any>, ctx: HttpContext): (fn: ParsedGlobalMiddleware, next: NextFn) => any;

package/build/src/server/factories/middleware_handler.js

@@ -1,3 +1,14 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+/**
+ * The middleware handler invokes the middleware functions.
+ */
 export function middlewareHandler(resolver, ctx) {
     return function (fn, next) {
         return fn.handle(resolver, ctx, next);

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

@@ -1,2 +1,6 @@
 import type { HttpContext } from '../../http_context/main.js';
+/**
+ * Writes the response to the socket. The "finish" method can
+ * raise error when unable to serialize the response.
+ */
 export declare function writeResponse(ctx: HttpContext): () => void;

package/build/src/server/factories/write_response.js

@@ -1,3 +1,15 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+/**
+ * Writes the response to the socket. The "finish" method can
+ * raise error when unable to serialize the response.
+ */
 export function writeResponse(ctx) {
     return function () {
         try {

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

@@ -14,19 +14,67 @@ import { Request } from '../request.js';
 import { Response } from '../response.js';
 import { Router } from '../router/main.js';
 import { HttpContext } from '../http_context/main.js';
+/**
+ * The HTTP server implementation to handle incoming requests and respond using the
+ * registered routes.
+ */
 export declare class Server {
     #private;
+    /**
+     * Know if async local storage is enabled or not.
+     */
     get usingAsyncLocalStorage(): boolean;
     constructor(app: Application<any>, encryption: Encryption, emitter: Emitter<any>, logger: Logger, config: ServerConfig);
+    /**
+     * Creates a pipeline of middleware.
+     */
     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
+     */
     use(middleware: LazyImport<MiddlewareAsClass>[]): this;
+    /**
+     * Register a custom error handler for HTTP requests.
+     * All errors will be reported to this method
+     */
     errorHandler(handler: LazyImport<ErrorHandlerAsAClass>): this;
+    /**
+     * Boot the server. Calling this method performs the following actions.
+     *
+     * - Register routes with the store.
+     * - Resolve and construct the error handler.
+     */
     boot(): Promise<void>;
+    /**
+     * Set the HTTP server instance used to listen for requests.
+     */
     setNodeServer(server: HttpServer | HttpsServer): void;
+    /**
+     * Returns reference to the underlying HTTP server
+     * in use
+     */
     getNodeServer(): HttpServer<typeof IncomingMessage, typeof ServerResponse> | HttpsServer<typeof IncomingMessage, typeof ServerResponse> | undefined;
+    /**
+     * Returns reference to the router instance used
+     * by the server.
+     */
     getRouter(): Router;
+    /**
+     * Creates an instance of the [[Request]] class
+     */
     createRequest(req: IncomingMessage, res: ServerResponse): Request;
+    /**
+     * Creates an instance of the [[Response]] class
+     */
     createResponse(req: IncomingMessage, res: ServerResponse): Response;
+    /**
+     * Creates an instance of the [[HttpContext]] class
+     */
     createHttpContext(request: Request, response: Response, resolver: ContainerResolver<any>): HttpContext;
+    /**
+     * Handle request
+     */
     handle(req: IncomingMessage, res: ServerResponse): Promise<any>;
 }

package/build/src/server/main.js

@@ -1,3 +1,11 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import onFinished from 'on-finished';
 import Middleware from '@poppinss/middleware';
 import { moduleCaller, moduleImporter } from '@adonisjs/fold';
@@ -11,25 +19,86 @@ import { finalHandler } from './factories/final_handler.js';
 import { writeResponse } from './factories/write_response.js';
 import { asyncLocalStorage } from '../http_context/local_storage.js';
 import { middlewareHandler } from './factories/middleware_handler.js';
+/**
+ * The HTTP server implementation to handle incoming requests and respond using the
+ * registered routes.
+ */
 export class Server {
+    /**
+     * The default error handler to use
+     */
     #defaultErrorHandler = {
         report() { },
         handle(error, ctx) {
             ctx.response.status(error.status || 500).send(error.message || 'Internal server error');
         },
     };
+    /**
+     * Logger instance, a child logger is added
+     * to the context to have request specific
+     * logging capabilities.
+     */
     #logger;
+    /**
+     * Registered error handler (if any)
+     */
     #errorHandler;
+    /**
+     * Resolved error handler is an instance of the lazily imported error
+     * handler class.
+     */
     #resolvedErrorHandler = this.#defaultErrorHandler;
+    /**
+     * Emitter is required to notify when a request finishes
+     */
     #emitter;
+    /**
+     * The application instance to be shared with the router
+     */
     #app;
+    /**
+     * The encryption instance to be shared with the router
+     */
     #encryption;
+    /**
+     * Server config
+     */
     #config;
+    /**
+     * Query string parser used by the server
+     */
     #qsParser;
+    /**
+     * Server middleware stack runs on every incoming HTTP request
+     */
     #serverMiddlewareStack;
+    /**
+     * Reference to the router used by the server
+     */
     #router;
+    /**
+     * Reference to the underlying Node HTTP server in use
+     */
     #nodeHttpServer;
+    /**
+     * Middleware store to be shared with the routes
+     */
     #middleware = [];
+    /**
+     * The request error response is attached to the middleware
+     * pipeline to intercept errors and invoke the user
+     * registered error handler.
+     *
+     * We share this with the route middleware pipeline as well,
+     * so that it does not throw any exceptions
+     */
+    #requestErrorResponder = (error, ctx) => {
+        this.#resolvedErrorHandler.report(error, ctx);
+        return this.#resolvedErrorHandler.handle(error, ctx);
+    };
+    /**
+     * Know if async local storage is enabled or not.
+     */
     get usingAsyncLocalStorage() {
         return asyncLocalStorage.isEnabled;
     }
@@ -44,6 +113,9 @@ export class Server {
         this.#createAsyncLocalStore();
         debug('server config: %O', this.#config);
     }
+    /**
+     * Create async local storage store when enabled
+     */
     #createAsyncLocalStore() {
         if (this.#config.useAsyncLocalStorage) {
             debug('creating ALS store for HTTP context');
@@ -53,19 +125,22 @@ export class Server {
             asyncLocalStorage.destroy();
         }
     }
+    /**
+     * Creates an instance of the server middleware stack
+     */
     #createServerMiddlewareStack() {
         this.#serverMiddlewareStack = new Middleware();
         this.#middleware.forEach((middleware) => this.#serverMiddlewareStack.add(middleware));
         this.#serverMiddlewareStack.freeze();
         this.#middleware = [];
     }
+    /**
+     * Handles the HTTP request
+     */
     #handleRequest(ctx, resolver) {
         return this.#serverMiddlewareStack.runner()
-            .errorHandler((error) => {
-            this.#resolvedErrorHandler.report(error, ctx);
-            return this.#resolvedErrorHandler.handle(error, ctx);
-        })
-            .finalHandler(finalHandler(this.#router, resolver, ctx))
+            .errorHandler((error) => this.#requestErrorResponder(error, ctx))
+            .finalHandler(finalHandler(this.#router, resolver, ctx, this.#requestErrorResponder))
             .run(middlewareHandler(resolver, ctx))
             .catch((error) => {
             ctx.logger.fatal({ err: error }, 'Exception raised by error handler');
@@ -73,6 +148,9 @@ export class Server {
         })
             .finally(writeResponse(ctx));
     }
+    /**
+     * Creates a pipeline of middleware.
+     */
     pipeline(middleware) {
         const middlewareStack = new Middleware();
         middleware.forEach((one) => {
@@ -96,18 +174,42 @@ export class Server {
             },
         };
     }
+    /**
+     * 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
+     */
     use(middleware) {
         middleware.forEach((one) => this.#middleware.push(moduleImporter(one, 'handle').toHandleMethod()));
         return this;
     }
+    /**
+     * Register a custom error handler for HTTP requests.
+     * All errors will be reported to this method
+     */
     errorHandler(handler) {
         this.#errorHandler = handler;
         return this;
     }
+    /**
+     * Boot the server. Calling this method performs the following actions.
+     *
+     * - Register routes with the store.
+     * - Resolve and construct the error handler.
+     */
     async boot() {
         debug('booting HTTP server');
+        /**
+         * Creates the middleware stack for the server
+         */
         this.#createServerMiddlewareStack();
+        /**
+         * Commit routes
+         */
         this.#router.commit();
+        /**
+         * Register custom error handler
+         */
         if (this.#errorHandler) {
             if (debug.enabled) {
                 debug('using custom error handler "%s"', this.#errorHandler);
@@ -116,29 +218,61 @@ export class Server {
             this.#resolvedErrorHandler = await this.#app.container.make(moduleExports.default);
         }
     }
+    /**
+     * Set the HTTP server instance used to listen for requests.
+     */
     setNodeServer(server) {
         this.#nodeHttpServer = server;
     }
+    /**
+     * Returns reference to the underlying HTTP server
+     * in use
+     */
     getNodeServer() {
         return this.#nodeHttpServer;
     }
+    /**
+     * Returns reference to the router instance used
+     * by the server.
+     */
     getRouter() {
         return this.#router;
     }
+    /**
+     * Creates an instance of the [[Request]] class
+     */
     createRequest(req, res) {
         return new Request(req, res, this.#encryption, this.#config, this.#qsParser);
     }
+    /**
+     * Creates an instance of the [[Response]] class
+     */
     createResponse(req, res) {
         return new Response(req, res, this.#encryption, this.#config, this.#router, this.#qsParser);
     }
+    /**
+     * Creates an instance of the [[HttpContext]] class
+     */
     createHttpContext(request, response, resolver) {
         return new HttpContext(request, response, this.#logger.child({ request_id: request.id() }), resolver);
     }
+    /**
+     * Handle request
+     */
     handle(req, res) {
+        /**
+         * Setup for the "http:request_finished" event
+         */
         const hasRequestListener = this.#emitter.hasListeners('http:request_finished');
         const startTime = hasRequestListener ? process.hrtime() : null;
+        /**
+         * Creating essential instances
+         */
         const resolver = this.#app.container.createResolver();
         const ctx = this.createHttpContext(this.createRequest(req, res), this.createResponse(req, res), resolver);
+        /**
+         * Emit event when listening for the request_finished event
+         */
         if (startTime) {
             onFinished(res, () => {
                 this.#emitter.emit('http:request_finished', {
@@ -147,6 +281,9 @@ export class Server {
                 });
             });
         }
+        /**
+         * Handle request
+         */
         if (this.usingAsyncLocalStorage) {
             return asyncLocalStorage.storage.run(ctx, () => this.#handleRequest(ctx, resolver));
         }

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

@@ -1,7 +1,19 @@
 export type { NextFn } from '@poppinss/middleware/types';
+/**
+ * Accept one or more of the mentioned type
+ */
 export type OneOrMore<T> = T | T[];
+/**
+ * Class constructor type
+ */
 export type Constructor<T> = new (...args: any[]) => T;
+/**
+ * A function that lazily imports a middleware
+ */
 export type LazyImport<DefaultExport> = () => Promise<{
     default: DefaultExport;
 }>;
+/**
+ * Unwraps default export from a lazy import function
+ */
 export type UnWrapLazyImport<Fn extends LazyImport<any>> = Awaited<ReturnType<Fn>>['default'];

package/build/src/types/base.js

@@ -1 +1,9 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 export {};

package/build/src/types/main.js

@@ -1,3 +1,11 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 export * from './base.js';
 export * from './middleware.js';
 export * from './qs.js';

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

@@ -1,15 +1,33 @@
 import type { ContainerResolver } from '@adonisjs/fold';
 import type { Constructor, NextFn } from './base.js';
 import type { HttpContext } from '../http_context/main.js';
+/**
+ * Middleware represented as a class
+ */
 export type MiddlewareAsClass = Constructor<{
     handle: (ctx: HttpContext, next: NextFn, args?: any) => any;
 }>;
+/**
+ * Check if a union has undefined or null
+ */
 type HasUndefined<T> = T extends NonNullable<T> ? true : false;
+/**
+ * Returns the arguments accepted by the middleware's handle method
+ */
 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
+ */
 export type MiddlewareFn = (ctx: HttpContext, next: NextFn) => any;
+/**
+ * Parsed global middleware
+ */
 export type ParsedGlobalMiddleware = {
     handle: (resolver: ContainerResolver<any>, ...args: [ctx: HttpContext, next: NextFn, params?: any]) => any;
 };
+/**
+ * Parsed named middleware
+ */
 export type ParsedNamedMiddleware = ParsedGlobalMiddleware & {
     name: string;
     args: any;

package/build/src/types/middleware.js

@@ -1 +1,9 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 export {};