@adonisjs/http-server 6.8.2-6 → 6.8.2-8

package/build/src/router/store.js

@@ -1,10 +1,51 @@
+/*
+ * @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(parseRoutePattern(domain));
@@ -12,6 +53,9 @@ export class RoutesStore {
         }
         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]) {
@@ -19,6 +63,9 @@ export class RoutesStore {
         }
         return domainNode[method];
     }
+    /**
+     * Collects route params
+     */
     #collectRouteParams(route, tokens) {
         const collectedParams = new Set();
         for (let token of tokens) {
@@ -35,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;
         }
+        /**
+         * 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;
@@ -79,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,5 +1,9 @@
 import type { ContainerResolver } from '@adonisjs/fold';
 import type { Router } from '../../router/main.js';
 import type { HttpContext } from '../../http_context/main.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): () => any;
-//# sourceMappingURL=final_handler.d.ts.map

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

@@ -1,4 +1,17 @@
+/*
+ * @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';
+/**
+ * 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) {
     return function () {
         const url = ctx.request.url();

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

@@ -2,5 +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;
-//# sourceMappingURL=middleware_handler.d.ts.map

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,3 +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;
-//# sourceMappingURL=write_response.d.ts.map

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,20 +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>;
 }
-//# sourceMappingURL=main.d.ts.map

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,74 @@ 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 = [];
+    /**
+     * Know if async local storage is enabled or not.
+     */
     get usingAsyncLocalStorage() {
         return asyncLocalStorage.isEnabled;
     }
@@ -44,6 +101,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,12 +113,18 @@ 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) => {
@@ -73,6 +139,9 @@ export class Server {
         })
             .finally(writeResponse(ctx));
     }
+    /**
+     * Creates a pipeline of middleware.
+     */
     pipeline(middleware) {
         const middlewareStack = new Middleware();
         middleware.forEach((one) => {
@@ -96,18 +165,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 +209,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 +272,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,8 +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'];
-//# sourceMappingURL=base.d.ts.map

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.d.ts

@@ -5,4 +5,3 @@ export * from './request.js';
 export * from './response.js';
 export * from './route.js';
 export * from './server.js';
-//# sourceMappingURL=main.d.ts.map

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,18 +1,35 @@
 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;
 };
 export {};
-//# sourceMappingURL=middleware.d.ts.map

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 {};