http_server.js

// Copyright Titanium I.T. LLC.
import * as ensure from "util/ensure.js";
import * as type from "util/type.js";
import http from "node:http";
import EventEmitter from "node:events";
import { HttpServerRequest } from "http/http_server_request.js";
import { HttpServerResponse } from "http/http_server_response.js";
import { Log } from "infrastructure/log.js";

const ROUTER_TYPE = {
	routeAsync: Function,
};

/** A general-purpose HTTP server. */
export class HttpServer {

	/**
	 * Factory method. Creates the server instance, but doesn't start it.
	 * @returns {HttpServer} the server
	 */
	static create() {
		ensure.signature(arguments, []);

		return new HttpServer(http);
	}

	/**
	 * Factory method. Creates a 'nulled' server instance that simulates listening on a port rather than
	 * actually doing so.
	 * @returns {HttpServer} the nulled server
	 */
	static createNull() {
		ensure.signature(arguments, []);

		return new HttpServer(stubbedHttp);
	}

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

		this._http = http;
		this._started = false;
		this._nodeServer = http.createServer();
	}

	/**
	 * @returns {boolean} true if the server has been started
	 */
	get isStarted() {
		return this._started;
	}

	/**
	 * @returns {number | null} the port the server is listening on, or null if it hasn't been started
	 */
	get port() {
		return this.isStarted ? this._port : null;
	}

	/**
	 * Start the server.
	 * @param port the port to listen on
	 * @param log logger to use for internal server errors
	 * @param router router for handling requests
	 */
	async startAsync(port, log, router) {
		ensure.signatureMinimum(arguments, [ Number, Log, ROUTER_TYPE ]);
		this.#ensureStopped("Can't start server because it's already running");

		this._port = port;
		this._log = log;
		this._router = router;

		this._started = true;   // located before promise to avoid potential race condition
		await new Promise((resolve, reject) => {
			this._nodeServer.on("listening", () => this.#onStartup(resolve));
			this._nodeServer.on("error", (err) => this.#onStartupError(err, reject));
			this._nodeServer.on("request", (request, response) => this.#onRequestAsync(request, response));

			this._nodeServer.listen(this._port);
		});
	}

	/**
	 * Stop the server.
	 */
	async stopAsync() {
		ensure.signature(arguments, []);
		this.#ensureStarted("Can't stop server because it isn't running");

		await new Promise((resolve, reject) => {
			this._nodeServer.on("close", resolve);
			this._nodeServer.close();
		});
		this._started = false;
	}

	/**
	 * Simulate an HTTP request.
	 * @param httpRequest the request to simulate
	 * @returns {Promise<HttpServerResponse>} the HTTP response
	 */
	async simulateRequestAsync(httpRequest = HttpServerRequest.createNull()) {
		ensure.signature(arguments, [[ undefined, HttpServerRequest ]]);
		this.#ensureStarted("Can't simulate request because server isn't running");

		return await this.#handleRequestAsync(httpRequest);
	}

	#onStartup(resolve) {
		this._log.info({
			message: "server started",
			port: this._port,
		});
		resolve();
	}

	#onStartupError(err, reject) {
		reject(new Error(`Couldn't start server due to error: ${err.message}`));
	}

	async #onRequestAsync(nodeRequest, nodeResponse) {
		const httpRequest = HttpServerRequest.create(nodeRequest);
		const httpResponse = await this.#handleRequestAsync(httpRequest);
		sendResponse(httpResponse, nodeResponse);
	}

	async #handleRequestAsync(httpRequest) {
		try {
			const response = await this._router.routeAsync(httpRequest);
			const typeError = type.check(response, HttpServerResponse);
			if (typeError !== null) {
				return internalServerError(this._log, response, "request handler returned invalid response");
			}
			else {
				return response;
			}
		}
		catch (err) {
			return internalServerError(this._log, err, "request handler threw exception");
		}
	}

	#ensureStarted(message) {
		if (!this.isStarted) throw new Error(message);
	}

	#ensureStopped(message) {
		if (this.isStarted) throw new Error(message);
	}

}

function sendResponse(httpResponse, nodeResponse) {
	nodeResponse.statusCode = httpResponse.status;
	setHeaders(nodeResponse, httpResponse.headers);
	nodeResponse.end(httpResponse.body);
}

function setHeaders(nodeResponse, headers) {
	Object.entries(headers).forEach(([ name, value ]) => {
		nodeResponse.setHeader(name, value);
	});
}

function internalServerError(log, details, message) {
	log.emergency({ message, details });
	return HttpServerResponse.createPlainTextResponse({
		status: 500,
		body: "Internal Server Error",
		debug: {
			message,
			details: details instanceof Error ? details.stack : details,
		},
	});
}


/** Embedded Stub **/

const stubbedHttp = {
	createServer() {
		return new StubbedNodeServer();
	}
};

class StubbedNodeServer extends EventEmitter {
	listen() {
		setImmediate(() => this.emit("listening"));
	}
	close() {
		setImmediate(() => this.emit("close"));
	}
}