generic_router.js

// Copyright Titanium I.T. LLC.
import * as ensure from "util/ensure.js";
import { HttpServerRequest } from "http/http_server_request.js";
import { OutputListener } from "util/output_listener.js";
import { Log } from "infrastructure/log.js";

/** A general-purpose router that converts request URLs to method calls. */
export class GenericRouter {

	/**
	 * Factory method. Creates the router.
	 * @param errorFnAsync a method to call when a request can't be routed (not found or method not allowed)
	 * @param routes An object containing one property for each path to route. For each property, the property
	 * name is the URL path (e.g., '/') and the property value is a controller object. The controller object
	 * should contain a 'xxxAsync()' method for each HTTP method it supports. E.g., 'getAsync()' and/or
	 * 'postAsync()'.
	 * @returns {GenericRouter} the router
	 */
	static create(errorFnAsync, routes) {
		ensure.signature(arguments, [ Function, Object ]);

		return new GenericRouter(errorFnAsync, routes);
	}

	/** Only for use by tests. (Use a factory method instead.) */
	constructor(errorFnAsync, routes) {
		ensure.signature(arguments, [ Function, Object ]);

		this._errorFnAsync = errorFnAsync;
		this._routes = routes;
		this._listener = new OutputListener();
	}

	/**
	 * Given a request, call the controller that corresponds to the request URL. The method that is called
	 * corresponds to the request's method: GET becomes getAsync(), POST becomes postAsync(), etc. If the
	 * URL's path isn't in the 'routes' object, calls the error function with a 404 (not found) status code.
	 * If the method doesn't exist on the controller, calls the error function with a 405 (method not
	 * allowed) status code.
	 * @param request HTTP request
	 * @param log logger
	 * @param [context] arbitrary context object (just passed through to controller)
	 * @returns {Promise<HttpServerResponse>} the HTTP response returned by the controller
	 */
	async routeAsync(request, log, context) {
		ensure.signature(arguments, [ HttpServerRequest, Log, [ undefined, Object ]]);

		const method = request.method.toLowerCase();
		const path = request.urlPathname;

		this.#recordRequest(method, path, log, context);
		return await this.#callRouteHandlerAsync(method, path, request, context);
	}

	/**
	 * Track requests made to the router.
	 * @returns {OutputTracker} the request tracker
	 */
	trackRequests() {
		return this._listener.trackOutput();
	}

	#recordRequest(method, path, log, context) {
		this._listener.emit({ method, path, context });
		log.info({ message: "request", method, path });
	}

	async #callRouteHandlerAsync(method, path, request, context) {
		const route = this._routes[path];
		if (route === undefined) return await this._errorFnAsync(404, "not found", request);

		const functionName = `${method}Async`;
		const methodFnAsync = route[functionName];
		if (methodFnAsync === undefined) return await this._errorFnAsync(405, "method not allowed", request);

		return await methodFnAsync.call(route, request, context);
	}

}