@3sixty/api-core-server 0.20.0-next.0 → 0.20.0-next.1

package/dist/es/baseServer.js

@@ -0,0 +1,666 @@
+// Copyright 2026 IOTA Stiftung.
+// Copyright 2026 3Sixty Trade Ltd.
+// SPDX-License-Identifier: Apache-2.0.
+import { request as httpRequest, validateHeaderName, validateHeaderValue } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { HealthCategory, HealthStatus, HttpBodyLimit, HttpContextIdKeys, HttpErrorHelper } from "@3sixty/api-models";
+import { JsonLdMimeTypeProcessor } from "@3sixty/api-processors";
+import { ContextIdStore } from "@3sixty/context";
+import { BaseError, ComponentFactory, GeneralError, Is, RandomHelper, Url } from "@3sixty/core";
+import { HeaderHelper, HeaderTypes, HttpMethod, HttpStatusCode, MimeTypes } from "@3sixty/web";
+/**
+ * Base class for web servers, containing the transport agnostic route processing.
+ * Derived classes supply the transport specific behaviour through the abstract server methods.
+ */
+export class BaseServer {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "BaseServer";
+    /**
+     * Default port for running the server.
+     * @internal
+     */
+    static _DEFAULT_PORT = 3000;
+    /**
+     * Default host for running the server.
+     * @internal
+     */
+    static _DEFAULT_HOST = "localhost";
+    /**
+     * Default named body size limits for routes.
+     * @internal
+     */
+    static _DEFAULT_BODY_LIMITS = {
+        [HttpBodyLimit.Default]: 1048576,
+        [HttpBodyLimit.Large]: 26214400
+    };
+    /**
+     * The logging component type.
+     */
+    _loggingComponentType;
+    /**
+     * The logging component.
+     */
+    _logging;
+    /**
+     * The options for the server.
+     */
+    _options;
+    /**
+     * Whether the server has been started.
+     */
+    _started;
+    /**
+     * The mime type processors.
+     */
+    _mimeTypeProcessors;
+    /**
+     * Include the stack with errors.
+     */
+    _includeErrorStack;
+    /**
+     * The public origin of the server, used for constructing the request URL and for CORS.
+     */
+    _publicOrigin;
+    /**
+     * The local origin of the server, used for constructing the request URL and for CORS.
+     */
+    _localOrigin;
+    /**
+     * The REST processor chains resolved when the server is built.
+     */
+    _restChains;
+    /**
+     * The socket processor chains resolved when the server is built.
+     */
+    _socketChains;
+    /**
+     * Create a new instance of BaseServer.
+     * @param options The options for the server.
+     */
+    constructor(options) {
+        this._loggingComponentType = options?.loggingComponentType;
+        this._logging = ComponentFactory.getIfExists(options?.loggingComponentType);
+        this._started = false;
+        this._restChains = { pre: [], process: [], post: [] };
+        this._socketChains = { connected: [], disconnected: [], pre: [], process: [], post: [] };
+        this._mimeTypeProcessors = options?.mimeTypeProcessors ?? [];
+        this._includeErrorStack = options?.includeErrorStack ?? false;
+        const hasJsonLd = this._mimeTypeProcessors.some(processor => processor.getTypes().includes(MimeTypes.JsonLd));
+        if (!hasJsonLd) {
+            this._mimeTypeProcessors.push(new JsonLdMimeTypeProcessor());
+        }
+    }
+    /**
+     * Start the server.
+     * @returns A promise that resolves when the server is listening for connections.
+     */
+    async start() {
+        const host = this._options?.host ?? BaseServer._DEFAULT_HOST;
+        const port = this._options?.port ?? BaseServer._DEFAULT_PORT;
+        await this._logging?.log({
+            level: "info",
+            ts: Date.now(),
+            source: BaseServer.CLASS_NAME,
+            message: "starting",
+            data: {
+                host,
+                port
+            }
+        });
+        if (!this._started) {
+            try {
+                await this.serverListen(host, port);
+                const addresses = this.serverAddresses();
+                const protocol = this.serverIsSecure() ? "https://" : "http://";
+                const normalizeAnyHost = (address) => {
+                    if (address === "0.0.0.0") {
+                        return "127.0.0.1";
+                    }
+                    if (address === "::") {
+                        return "::1";
+                    }
+                    return address;
+                };
+                const formatAddress = (address, family, forceProtocol) => {
+                    const displayAddress = normalizeAnyHost(address);
+                    const isIPv6 = family === "IPv6" || (Is.stringValue(displayAddress) && displayAddress.includes(":"));
+                    return `${forceProtocol ?? protocol}${isIPv6 ? "[" : ""}${displayAddress}${isIPv6 ? "]" : ""}`;
+                };
+                const startupAddresses = addresses.map(a => {
+                    const formatted = formatAddress(a.address, a.family, protocol);
+                    return `${formatted}:${a.port}`;
+                });
+                for (const origin of [this._localOrigin, this._publicOrigin]) {
+                    if (Is.stringValue(origin)) {
+                        const originUrl = Url.tryParseExact(origin);
+                        if (!Is.empty(originUrl)) {
+                            const originParts = originUrl.parts();
+                            const formatted = formatAddress(originParts.host, undefined, `${originParts.schema}://`);
+                            startupAddresses.push(`${formatted}${Is.integer(originParts.port) ? `:${originParts.port}` : ""}`);
+                        }
+                        else {
+                            startupAddresses.push(origin);
+                        }
+                    }
+                }
+                const distinctStartupAddresses = [...new Set(startupAddresses)];
+                await this._logging?.log({
+                    level: "info",
+                    ts: Date.now(),
+                    source: BaseServer.CLASS_NAME,
+                    message: "started",
+                    data: {
+                        addresses: distinctStartupAddresses.join(", ")
+                    }
+                });
+                this._started = true;
+            }
+            catch (err) {
+                await this._logging?.log({
+                    level: "error",
+                    ts: Date.now(),
+                    source: BaseServer.CLASS_NAME,
+                    message: "startFailed",
+                    error: BaseError.fromError(err)
+                });
+            }
+        }
+    }
+    /**
+     * Stop the server.
+     * @returns A promise that resolves when the server has shut down all connections.
+     */
+    async stop() {
+        if (this._started) {
+            this._started = false;
+            await this.serverClose();
+            await this._logging?.log({
+                level: "info",
+                ts: Date.now(),
+                source: BaseServer.CLASS_NAME,
+                message: "stopped"
+            });
+        }
+    }
+    /**
+     * Returns the health status of the component.
+     * @returns The health status of the component, can return multiple entries for elements within the component.
+     */
+    async health() {
+        let healthCheck;
+        if (this.serverIsListening()) {
+            healthCheck = {
+                source: BaseServer.CLASS_NAME,
+                status: HealthStatus.Ok,
+                category: HealthCategory.Connectivity,
+                description: "healthConnectivityDescription",
+                message: "reachable"
+            };
+        }
+        else {
+            healthCheck = {
+                source: BaseServer.CLASS_NAME,
+                status: HealthStatus.Error,
+                category: HealthCategory.Connectivity,
+                description: "healthConnectivityDescription",
+                message: "unreachable"
+            };
+        }
+        return [healthCheck];
+    }
+    /**
+     * Verify the root endpoint is reachable and returns a body by making a real HTTP request.
+     * Skipped when GET / is not registered on this server instance.
+     * @param callback The callback to invoke when a deferred health result is ready.
+     * @returns The application health status of the component.
+     */
+    async healthApplication(callback) {
+        if (!this.serverHasRootRoute()) {
+            return [];
+        }
+        if (!Is.stringValue(this._localOrigin)) {
+            return [
+                {
+                    source: BaseServer.CLASS_NAME,
+                    status: HealthStatus.Error,
+                    category: HealthCategory.Application,
+                    description: "healthApplicationDescription",
+                    message: "serverNotBuilt"
+                }
+            ];
+        }
+        try {
+            const response = await this.requestLocalRoot(`${this._localOrigin}/`);
+            if (response.ok && Is.stringValue(response.body)) {
+                return [
+                    {
+                        source: BaseServer.CLASS_NAME,
+                        status: HealthStatus.Ok,
+                        category: HealthCategory.Application,
+                        description: "healthApplicationDescription",
+                        message: "rootEndpointReachable"
+                    }
+                ];
+            }
+            return [
+                {
+                    source: BaseServer.CLASS_NAME,
+                    status: HealthStatus.Error,
+                    category: HealthCategory.Application,
+                    description: "healthApplicationDescription",
+                    message: "rootEndpointError"
+                }
+            ];
+        }
+        catch (error) {
+            return [
+                {
+                    source: BaseServer.CLASS_NAME,
+                    status: HealthStatus.Error,
+                    category: HealthCategory.Application,
+                    description: "healthApplicationDescription",
+                    error: BaseError.fromError(error)
+                }
+            ];
+        }
+    }
+    /**
+     * Request the root endpoint of this server over the loopback address.
+     * @param url The url of the root endpoint.
+     * @returns Whether the response was successful and its body.
+     */
+    async requestLocalRoot(url) {
+        const isSecure = url.startsWith("https:");
+        return new Promise((resolve, reject) => {
+            const callback = (response) => {
+                const chunks = [];
+                response.on("data", (chunk) => chunks.push(chunk));
+                response.on("error", reject);
+                response.on("end", () => {
+                    const statusCode = response.statusCode ?? 0;
+                    resolve({
+                        ok: statusCode >= HttpStatusCode.ok && statusCode < HttpStatusCode.multipleChoices,
+                        body: Buffer.concat(chunks).toString("utf8")
+                    });
+                });
+            };
+            // The certificate is issued for the public host name rather than the loopback
+            // address, and this only checks the server can reach its own listener, so it
+            // is not verified
+            const request = isSecure
+                ? httpsRequest(url, { rejectUnauthorized: false }, callback)
+                : httpRequest(url, callback);
+            request.on("error", reject);
+            request.end();
+        });
+    }
+    /**
+     * Perform the transport agnostic part of building the server, validating the routes and
+     * processors, resolving the origins and resolving the processor chains.
+     * @param restRouteProcessors The processors for incoming requests over REST.
+     * @param restRoutes The REST routes.
+     * @param socketRouteProcessors The processors for incoming requests over Sockets.
+     * @param socketRoutes The socket routes.
+     * @param options Options for building the server.
+     * @returns A promise that resolves when the shared build steps are complete.
+     */
+    async prepareBuild(restRouteProcessors, restRoutes, socketRouteProcessors, socketRoutes, options) {
+        if (Is.arrayValue(restRoutes) && !Is.arrayValue(restRouteProcessors)) {
+            throw new GeneralError(BaseServer.CLASS_NAME, "noRestProcessors");
+        }
+        if (Is.arrayValue(socketRoutes) && !Is.arrayValue(socketRouteProcessors)) {
+            throw new GeneralError(BaseServer.CLASS_NAME, "noSocketProcessors");
+        }
+        await this._logging?.log({
+            level: "info",
+            ts: Date.now(),
+            source: BaseServer.CLASS_NAME,
+            message: "building"
+        });
+        let localHost = options?.host ?? "127.0.0.1";
+        if (localHost === "0.0.0.0") {
+            localHost = "127.0.0.1";
+        }
+        this._localOrigin = `${this.serverIsSecure() ? "https" : "http"}://${localHost}:${options?.port ?? 3000}`;
+        if (Is.stringValue(options?.publicOrigin)) {
+            const publicUrl = Url.tryParseExact(options.publicOrigin);
+            if (!Is.empty(publicUrl)) {
+                const urlParts = publicUrl.parts();
+                this._publicOrigin = `${urlParts.schema}://${urlParts.host}${Is.integer(urlParts.port) ? `:${urlParts.port}` : ""}`;
+            }
+            else {
+                throw new GeneralError(BaseServer.CLASS_NAME, "invalidPublicOrigin", {
+                    publicOrigin: options.publicOrigin
+                });
+            }
+        }
+        this._options = options;
+        this.buildProcessorChains(restRouteProcessors, socketRouteProcessors);
+    }
+    /**
+     * Resolve the route processors in to per phase chains, so that the lookups and bindings
+     * are performed once when the server is built instead of on every request.
+     * @param restRouteProcessors The processors for the incoming REST requests.
+     * @param socketRouteProcessors The processors for the incoming socket requests.
+     */
+    buildProcessorChains(restRouteProcessors, socketRouteProcessors) {
+        const restChains = { pre: [], process: [], post: [] };
+        for (const routeProcessor of restRouteProcessors ?? []) {
+            const pre = routeProcessor.pre?.bind(routeProcessor);
+            if (Is.function(pre)) {
+                restChains.pre.push(pre);
+            }
+            const process = routeProcessor.process?.bind(routeProcessor);
+            if (Is.function(process)) {
+                restChains.process.push(process);
+            }
+            const post = routeProcessor.post?.bind(routeProcessor);
+            if (Is.function(post)) {
+                restChains.post.push(post);
+            }
+        }
+        const socketChains = {
+            connected: [],
+            disconnected: [],
+            pre: [],
+            process: [],
+            post: []
+        };
+        for (const routeProcessor of socketRouteProcessors ?? []) {
+            const connected = routeProcessor.connected?.bind(routeProcessor);
+            if (Is.function(connected)) {
+                socketChains.connected.push(connected);
+            }
+            const disconnected = routeProcessor.disconnected?.bind(routeProcessor);
+            if (Is.function(disconnected)) {
+                socketChains.disconnected.push(disconnected);
+            }
+            const pre = routeProcessor.pre?.bind(routeProcessor);
+            if (Is.function(pre)) {
+                socketChains.pre.push(pre);
+            }
+            const process = routeProcessor.process?.bind(routeProcessor);
+            if (Is.function(process)) {
+                socketChains.process.push(process);
+            }
+            const post = routeProcessor.post?.bind(routeProcessor);
+            if (Is.function(post)) {
+                socketChains.post.push(post);
+            }
+        }
+        this._restChains = restChains;
+        this._socketChains = socketChains;
+    }
+    /**
+     * Merge the configured body limits over the built-in ones and validate them.
+     * @returns The named body limits in bytes.
+     * @throws GeneralError If a limit is not a positive integer.
+     */
+    resolveBodyLimits() {
+        const bodyLimits = {
+            ...BaseServer._DEFAULT_BODY_LIMITS,
+            ...this._options?.bodyLimits
+        };
+        for (const name of Object.keys(bodyLimits)) {
+            const bodyLimit = bodyLimits[name];
+            if (!Is.integer(bodyLimit) || bodyLimit <= 0) {
+                throw new GeneralError(BaseServer.CLASS_NAME, "invalidBodyLimit", {
+                    bodyLimit: name,
+                    value: bodyLimit
+                });
+            }
+        }
+        return bodyLimits;
+    }
+    /**
+     * Resolve the CORS options from the web server options, merging in the defaults.
+     * @param options The web server options.
+     * @returns The resolved CORS options.
+     */
+    resolveCorsOptions(options) {
+        let origins = ["*"];
+        if (Is.arrayValue(options?.corsOrigins)) {
+            origins = options?.corsOrigins;
+        }
+        else if (Is.stringValue(options?.corsOrigins)) {
+            origins = [options?.corsOrigins];
+        }
+        const hasWildcardOrigin = origins.includes("*");
+        const methods = options?.methods ?? [
+            HttpMethod.GET,
+            HttpMethod.PUT,
+            HttpMethod.POST,
+            HttpMethod.PATCH,
+            HttpMethod.DELETE,
+            HttpMethod.OPTIONS
+        ];
+        const allowedHeaders = [
+            HeaderTypes.AccessControlAllowOrigin,
+            HeaderTypes.ContentEncoding,
+            HeaderTypes.AcceptEncoding,
+            HeaderTypes.ContentType,
+            HeaderTypes.Authorization,
+            HeaderTypes.Accept
+        ];
+        const exposedHeaders = [HeaderTypes.ContentDisposition, HeaderTypes.Location];
+        if (Is.arrayValue(options?.allowedHeaders)) {
+            allowedHeaders.push(...options.allowedHeaders);
+        }
+        if (Is.arrayValue(options?.exposedHeaders)) {
+            exposedHeaders.push(...options.exposedHeaders);
+        }
+        return { origins, hasWildcardOrigin, methods, allowedHeaders, exposedHeaders };
+    }
+    /**
+     * Build the server request from the transport values, the path params and query must already
+     * have been decoded by the transport, as decoding them again corrupts values containing %.
+     * @param method The request method.
+     * @param url The full request url, including the origin.
+     * @param body The request body.
+     * @param query The request query params.
+     * @param pathParams The request path params.
+     * @param headers The request headers.
+     * @returns The server request.
+     */
+    buildServerRequest(method, url, body, query, pathParams, headers) {
+        return {
+            method,
+            url,
+            body,
+            query,
+            pathParams,
+            headers
+        };
+    }
+    /**
+     * Validate the processed response before it is sent, so that every transport fails an invalid
+     * response in the same way rather than with its own transport specific error.
+     * @param httpResponse The processed response.
+     * @throws GeneralError If the status code or a header is invalid.
+     */
+    validateResponse(httpResponse) {
+        const statusCode = httpResponse.statusCode;
+        if (!Is.empty(statusCode) &&
+            (!Is.integer(statusCode) || statusCode < 100 || statusCode > 599)) {
+            throw new GeneralError(BaseServer.CLASS_NAME, "invalidStatusCode", { statusCode });
+        }
+        if (!Is.empty(httpResponse.headers)) {
+            for (const header of Object.keys(httpResponse.headers)) {
+                const value = httpResponse.headers[header];
+                try {
+                    validateHeaderName(header);
+                    for (const item of Is.array(value) ? value : [value]) {
+                        if (!Is.empty(item)) {
+                            validateHeaderValue(header, item);
+                        }
+                    }
+                }
+                catch (err) {
+                    throw new GeneralError(BaseServer.CLASS_NAME, "invalidHeader", { header }, err);
+                }
+            }
+        }
+    }
+    /**
+     * Build the context ids for an incoming request.
+     * @param requestOrigin The origin the request was received on.
+     * @param headers The request headers.
+     * @returns The context ids.
+     */
+    buildContextIds(requestOrigin, headers) {
+        return {
+            [HttpContextIdKeys.IpAddress]: HeaderHelper.extractClientIps(headers).join("|"),
+            [HttpContextIdKeys.UserAgent]: HeaderHelper.extractUserAgent(headers),
+            [HttpContextIdKeys.CorrelationId]: HeaderHelper.extractCorrelationId(headers),
+            [HttpContextIdKeys.RemoteRequest]: RandomHelper.generateUuidV7("compact"),
+            [HttpContextIdKeys.LocalOrigin]: this._localOrigin,
+            // This can be overridden by a processor if needed, for example a tenant processor
+            [HttpContextIdKeys.PublicOrigin]: this._publicOrigin ?? requestOrigin ?? this._localOrigin
+        };
+    }
+    /**
+     * Run the REST processors for the route.
+     * @param restRoute The route to process.
+     * @param httpServerRequest The incoming request.
+     * @param httpResponse The outgoing response.
+     * @param contextIds The context IDs of the request.
+     * @param processorState The state handed through the processors.
+     */
+    async runProcessorsRest(restRoute, httpServerRequest, httpResponse, contextIds, processorState) {
+        let hasPreError = false;
+        try {
+            // Run inside ContextIdStore.run so pre-processors can do tenant-scoped storage lookups.
+            await ContextIdStore.run(contextIds, async () => {
+                for (const pre of this._restChains.pre) {
+                    await pre(httpServerRequest, httpResponse, restRoute, contextIds, processorState, {
+                        loggingComponentType: this._loggingComponentType
+                    });
+                }
+            });
+        }
+        catch (err) {
+            const { error, httpStatusCode } = HttpErrorHelper.processError(err, this._includeErrorStack);
+            HttpErrorHelper.buildResponse(httpResponse, error, httpStatusCode, this._includeErrorStack);
+            hasPreError = true;
+        }
+        // A pre-processor may set an error response without throwing; treat that as halt.
+        if (!hasPreError &&
+            Is.integer(httpResponse.statusCode) &&
+            httpResponse.statusCode >= HttpStatusCode.badRequest) {
+            hasPreError = true;
+        }
+        // Don't run the main processing if there was an error in the pre processing
+        // As this is likely to perform tasks such as authentication which may have failed
+        if (!hasPreError) {
+            try {
+                // Run the processors within an async context
+                // so that any services can access the context ids
+                await ContextIdStore.run(contextIds, async () => {
+                    for (const process of this._restChains.process) {
+                        await process(httpServerRequest, httpResponse, restRoute, processorState, {
+                            loggingComponentType: this._loggingComponentType
+                        });
+                    }
+                });
+            }
+            catch (err) {
+                const { error, httpStatusCode } = HttpErrorHelper.processError(err, this._includeErrorStack);
+                HttpErrorHelper.buildResponse(httpResponse, error, httpStatusCode, this._includeErrorStack);
+            }
+        }
+        try {
+            // Always run the post processors, even if there was an error earlier
+            // as they may perform cleanup tasks, or logging etc
+            await ContextIdStore.run(contextIds, async () => {
+                for (const post of this._restChains.post) {
+                    await post(httpServerRequest, httpResponse, restRoute, contextIds, processorState, {
+                        loggingComponentType: this._loggingComponentType
+                    });
+                }
+            });
+        }
+        catch (err) {
+            // Just log post processor errors
+            await this._logging?.log({
+                level: "error",
+                ts: Date.now(),
+                source: BaseServer.CLASS_NAME,
+                message: "postProcessorError",
+                error: BaseError.fromError(err),
+                data: {
+                    route: restRoute?.path ?? ""
+                }
+            });
+        }
+    }
+    /**
+     * Run the socket processors for the route.
+     * @param socketRoute The route to process.
+     * @param socketServerRequest The incoming request.
+     * @param httpResponse The outgoing response.
+     * @param contextIds The context IDs of the request.
+     * @param processorState The state handed through the processors.
+     * @param requestTopic The topic of the request.
+     * @param responseEmitter The emitter to send the response on.
+     */
+    async runProcessorsSocket(socketRoute, socketServerRequest, httpResponse, contextIds, processorState, requestTopic, responseEmitter) {
+        // Custom emit method which will also call the post processors
+        const postProcessEmit = async (topic, response, responseProcessorState) => {
+            await responseEmitter(topic, response);
+            try {
+                // The post processors are called after the response has been emitted
+                for (const post of this._socketChains.post) {
+                    await post(socketServerRequest, response, socketRoute, contextIds, responseProcessorState, {
+                        loggingComponentType: this._loggingComponentType
+                    });
+                }
+            }
+            catch (err) {
+                await this._logging?.log({
+                    level: "error",
+                    ts: Date.now(),
+                    source: BaseServer.CLASS_NAME,
+                    message: "postProcessorError",
+                    error: BaseError.fromError(err),
+                    data: {
+                        route: socketRoute.path
+                    }
+                });
+            }
+        };
+        try {
+            for (const pre of this._socketChains.pre) {
+                await pre(socketServerRequest, httpResponse, socketRoute, contextIds, processorState, {
+                    loggingComponentType: this._loggingComponentType
+                });
+            }
+            // We always call all the processors regardless of any response set by a previous processor.
+            // But if a pre processor sets a status code, we will emit the response manually, as the pre
+            // and post processors do not receive the emit method, they just populate the response object.
+            if (!Is.empty(httpResponse.statusCode)) {
+                await postProcessEmit(requestTopic, httpResponse, processorState);
+            }
+            await ContextIdStore.run(contextIds, async () => {
+                for (const process of this._socketChains.process) {
+                    await process(socketServerRequest, httpResponse, socketRoute, processorState, async (topic, processResponse) => {
+                        await postProcessEmit(topic, processResponse, processorState);
+                    }, this._loggingComponentType);
+                }
+            });
+            // If the processors set the status to any kind of error then we should emit this manually
+            if (Is.integer(httpResponse.statusCode) &&
+                httpResponse.statusCode >= HttpStatusCode.badRequest) {
+                await postProcessEmit(requestTopic, httpResponse, processorState);
+            }
+        }
+        catch (err) {
+            // Emit any unhandled errors manually
+            const { error, httpStatusCode } = HttpErrorHelper.processError(err, this._includeErrorStack);
+            HttpErrorHelper.buildResponse(httpResponse, error, httpStatusCode, this._includeErrorStack);
+            await postProcessEmit(requestTopic, httpResponse, processorState);
+        }
+    }
+}
+//# sourceMappingURL=baseServer.js.map