@twin.org/api-processors 0.0.1-next.10

package/dist/esm/index.mjs

@@ -0,0 +1,333 @@
+import { HttpErrorHelper } from '@twin.org/api-models';
+import { Is, NotFoundError, Guards, ObjectHelper, Coerce } from '@twin.org/core';
+import { HttpStatusCode, HeaderTypes, MimeTypes } from '@twin.org/web';
+import { LoggingConnectorFactory } from '@twin.org/logging-models';
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Process the REST request and hands it on to the route handler.
+ */
+class RouteProcessor {
+    /**
+     * Runtime name for the class.
+     */
+    CLASS_NAME = "RouteProcessor";
+    /**
+     * Include the stack with errors.
+     * @internal
+     */
+    _includeErrorStack;
+    /**
+     * Create a new instance of RouteProcessor.
+     * @param options Options for the processor.
+     * @param options.config The configuration for the processor.
+     * @returns Promise that resolves when the processor is initialized.
+     */
+    constructor(options) {
+        this._includeErrorStack = options?.config?.includeErrorStack ?? false;
+    }
+    /**
+     * Process the REST request for the specified route.
+     * @param request The incoming request.
+     * @param response The outgoing response.
+     * @param route The route to process.
+     * @param requestIdentity The identity context for the request.
+     * @param processorState The state handed through the processors.
+     */
+    async process(request, response, route, requestIdentity, processorState) {
+        // Don't handle the route if another processor has already set the response
+        // status code e.g. from an auth processor
+        if (Is.empty(response.statusCode)) {
+            if (Is.empty(route)) {
+                HttpErrorHelper.buildResponse(response, {
+                    name: NotFoundError.CLASS_NAME,
+                    message: `${this.CLASS_NAME}.routeNotFound`,
+                    properties: {
+                        notFoundId: request.url
+                    }
+                }, HttpStatusCode.notFound);
+            }
+            else {
+                try {
+                    const req = {
+                        pathParams: request.pathParams,
+                        query: request.query,
+                        body: request.body
+                    };
+                    const restRouteResponse = await route.handler({
+                        ...requestIdentity,
+                        serverRequest: request,
+                        processorState
+                    }, req);
+                    let statusCode = restRouteResponse.statusCode ?? response.statusCode ?? HttpStatusCode.ok;
+                    const headers = restRouteResponse?.headers ?? {};
+                    if (Is.empty(restRouteResponse?.body)) {
+                        // If there is no custom status code and the body is empty
+                        // use the no content response and set the length to 0
+                        headers[HeaderTypes.ContentLength] = "0";
+                        // Only change to no content if the status code is ok
+                        // This could be something like a created status code
+                        // which is successful but has no content
+                        if (statusCode === HttpStatusCode.ok) {
+                            statusCode = HttpStatusCode.noContent;
+                        }
+                    }
+                    else {
+                        // Only set the content type if there is a body
+                        // If there are custom response types for the route then use them
+                        // instead of the default application/json
+                        headers[HeaderTypes.ContentType] =
+                            restRouteResponse?.attachment?.mimeType ??
+                                response.headers?.[HeaderTypes.ContentType] ??
+                                `${MimeTypes.Json}; charset=utf-8`;
+                        // If there are filename or inline options set then add the content disposition
+                        if (Is.stringValue(restRouteResponse?.attachment?.filename) ||
+                            Is.boolean(restRouteResponse?.attachment?.inline)) {
+                            let filename = "";
+                            if (Is.stringValue(restRouteResponse?.attachment?.filename)) {
+                                filename = `; filename="${restRouteResponse?.attachment?.filename}"`;
+                            }
+                            headers[HeaderTypes.ContentDisposition] =
+                                `${restRouteResponse?.attachment?.inline ? "inline" : "attachment"}${filename}`;
+                        }
+                        // If this is a binary response then set the content length
+                        if (Is.uint8Array(restRouteResponse?.body)) {
+                            const contentLength = restRouteResponse.body.length;
+                            headers[HeaderTypes.ContentLength] = contentLength.toString();
+                        }
+                        response.body = restRouteResponse?.body;
+                    }
+                    response.headers = headers;
+                    response.statusCode = statusCode;
+                }
+                catch (err) {
+                    const { error, httpStatusCode } = HttpErrorHelper.processError(err, this._includeErrorStack);
+                    HttpErrorHelper.buildResponse(response, error, httpStatusCode);
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Adds a static user identity to the request context.
+ */
+class StaticUserIdentityProcessor {
+    /**
+     * Runtime name for the class.
+     */
+    CLASS_NAME = "StaticUserIdentityProcessor";
+    /**
+     * The fixed identity for request context.
+     * @internal
+     */
+    _userIdentity;
+    /**
+     * Create a new instance of StaticIdentityProcessor.
+     * @param options Options for the processor.
+     * @param options.config The configuration for the processor.
+     * @returns Promise that resolves when the processor is initialized.
+     */
+    constructor(options) {
+        Guards.object(this.CLASS_NAME, "options", options);
+        Guards.object(this.CLASS_NAME, "options.config", options.config);
+        Guards.stringValue(this.CLASS_NAME, "options.config.userIdentity", options.config.userIdentity);
+        this._userIdentity = options.config.userIdentity;
+    }
+    /**
+     * Pre process the REST request for the specified route.
+     * @param request The incoming request.
+     * @param response The outgoing response.
+     * @param route The route to process.
+     * @param requestIdentity The identity context for the request.
+     * @param processorState The state handed through the processors.
+     */
+    async pre(request, response, route, requestIdentity, processorState) {
+        if (!Is.empty(route) && !(route.skipAuth ?? false)) {
+            requestIdentity.userIdentity = this._userIdentity;
+        }
+    }
+}
+
+/**
+ * Adds a node identity to the request identity.
+ */
+class NodeIdentityProcessor {
+    /**
+     * Runtime name for the class.
+     */
+    CLASS_NAME = "NodeIdentityProcessor";
+    /**
+     * The node identity for request context.
+     * @internal
+     */
+    _nodeIdentity;
+    /**
+     * The service needs to be started when the application is initialized.
+     * @param nodeIdentity The identity of the node.
+     * @param nodeLoggingConnectorType The node logging connector type, defaults to "node-logging".
+     * @returns Nothing.
+     */
+    async start(nodeIdentity, nodeLoggingConnectorType) {
+        Guards.string(this.CLASS_NAME, "nodeIdentity", nodeIdentity);
+        this._nodeIdentity = nodeIdentity;
+    }
+    /**
+     * Pre process the REST request for the specified route.
+     * @param request The incoming request.
+     * @param response The outgoing response.
+     * @param route The route to process.
+     * @param requestIdentity The identity context for the request.
+     * @param processorState The state handed through the processors.
+     */
+    async pre(request, response, route, requestIdentity, processorState) {
+        requestIdentity.nodeIdentity = this._nodeIdentity;
+    }
+}
+
+/**
+ * Process the REST request and log its information.
+ */
+class LoggingProcessor {
+    /**
+     * Runtime name for the class.
+     */
+    CLASS_NAME = "LoggingProcessor";
+    /**
+     * The connector for logging the information.
+     * @internal
+     */
+    _loggingConnector;
+    /**
+     * Include the body objects when logging the information.
+     * @internal
+     */
+    _includeBody;
+    /**
+     * Show the full base64 content for data, default to abbreviate.
+     * @internal
+     */
+    _fullBase64;
+    /**
+     * List of property names to obfuscate, defaults to "password".
+     * @internal
+     */
+    _obfuscateProperties;
+    /**
+     * Create a new instance of RequestLoggingProcessor.
+     * @param options Options for the processor.
+     * @param options.loggingConnectorType The type for the logging connector, defaults to "logging".
+     * @param options.config The configuration for the processor.
+     * @returns Promise that resolves when the processor is initialized.
+     */
+    constructor(options) {
+        this._loggingConnector = LoggingConnectorFactory.get(options?.loggingConnectorType ?? "logging");
+        this._includeBody = options?.config?.includeBody ?? false;
+        this._fullBase64 = options?.config?.fullBase64 ?? false;
+        this._obfuscateProperties = options?.config?.obfuscateProperties ?? ["password"];
+    }
+    /**
+     * Pre process the REST request for the specified route.
+     * @param request The incoming request.
+     * @param response The outgoing response.
+     * @param route The route to process.
+     * @param requestIdentity The identity context for the request.
+     * @param processorState The state handed through the processors.
+     */
+    async pre(request, response, route, requestIdentity, processorState) {
+        const now = process.hrtime.bigint();
+        processorState.requestStart = now;
+        const contentType = request.headers?.[HeaderTypes.ContentType];
+        const isJson = Is.stringValue(contentType)
+            ? contentType.includes(MimeTypes.Json) || contentType.includes(MimeTypes.JsonLd)
+            : false;
+        await this._loggingConnector.log({
+            level: "info",
+            source: this.CLASS_NAME,
+            ts: Date.now(),
+            message: `===> ${request.method} ${request.url ? new URL(request.url).pathname : ""}`,
+            data: this._includeBody && isJson
+                ? this.processJson("body", ObjectHelper.clone(request?.body))
+                : undefined
+        });
+    }
+    /**
+     * Post process the REST request for the specified route.
+     * @param request The incoming request.
+     * @param response The outgoing response.
+     * @param route The route to process.
+     * @param requestIdentity The identity context for the request.
+     * @param processorState The state handed through the processors.
+     */
+    async post(request, response, route, requestIdentity, processorState) {
+        let data;
+        if (this._includeBody) {
+            const contentType = response.headers?.[HeaderTypes.ContentType];
+            const isJson = Is.stringValue(contentType)
+                ? contentType.includes(MimeTypes.Json) || contentType.includes(MimeTypes.JsonLd)
+                : false;
+            const contentLength = response.headers?.[HeaderTypes.ContentLength];
+            if (isJson) {
+                data = {
+                    body: this.processJson("body", ObjectHelper.clone(response.body))
+                };
+            }
+            else {
+                const dataParts = {};
+                if (Is.stringValue(contentType)) {
+                    dataParts["Content Type"] = contentType;
+                }
+                if (Is.stringValue(contentLength)) {
+                    dataParts["Content Length"] = contentLength;
+                }
+                if (Object.keys(dataParts).length > 0) {
+                    data = {
+                        headers: dataParts
+                    };
+                }
+            }
+        }
+        const now = process.hrtime.bigint();
+        const start = Coerce.bigint(processorState.requestStart) ?? now;
+        const elapsed = now - start;
+        const elapsedMicroSeconds = Math.floor(Number(elapsed) / 1000);
+        await this._loggingConnector.log({
+            level: Is.number(response.statusCode) && response.statusCode >= HttpStatusCode.badRequest
+                ? "error"
+                : "info",
+            source: this.CLASS_NAME,
+            ts: Date.now(),
+            message: `<=== ${response.statusCode ?? ""} ${request.method} ${request.url ? new URL(request.url).pathname : ""} duration: ${elapsedMicroSeconds}µs`,
+            data
+        });
+    }
+    /**
+     * Process the JSON.
+     * @param propValue The property to process.
+     * @returns The processed property.
+     * @internal
+     */
+    processJson(propName, propValue) {
+        if (Is.array(propValue)) {
+            for (let i = 0; i < propValue.length; i++) {
+                propValue[i] = this.processJson(`${i}`, propValue[i]);
+            }
+        }
+        else if (Is.object(propValue)) {
+            for (const key of Object.keys(propValue)) {
+                propValue[key] = this.processJson(key, propValue[key]);
+            }
+        }
+        else if (Is.stringBase64(propValue) && !this._fullBase64) {
+            propValue = "<base64>";
+        }
+        else if (Is.string(propValue) &&
+            this._obfuscateProperties.some(op => new RegExp(op).test(propName))) {
+            propValue = "**************";
+        }
+        return propValue;
+    }
+}
+
+export { LoggingProcessor, NodeIdentityProcessor, RouteProcessor, StaticUserIdentityProcessor };

package/dist/types/data/routeProcessor.d.ts

@@ -0,0 +1,31 @@
+import { type IHttpRequestIdentity, type IHttpResponse, type IHttpRestRouteProcessor, type IHttpServerRequest, type IRestRoute } from "@twin.org/api-models";
+import type { IRouteProcessorConfig } from "../models/IRouteProcessorConfig";
+/**
+ * Process the REST request and hands it on to the route handler.
+ */
+export declare class RouteProcessor implements IHttpRestRouteProcessor {
+    /**
+     * Runtime name for the class.
+     */
+    readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of RouteProcessor.
+     * @param options Options for the processor.
+     * @param options.config The configuration for the processor.
+     * @returns Promise that resolves when the processor is initialized.
+     */
+    constructor(options?: {
+        config?: IRouteProcessorConfig;
+    });
+    /**
+     * Process the REST request for the specified route.
+     * @param request The incoming request.
+     * @param response The outgoing response.
+     * @param route The route to process.
+     * @param requestIdentity The identity context for the request.
+     * @param processorState The state handed through the processors.
+     */
+    process(request: IHttpServerRequest, response: IHttpResponse, route: IRestRoute | undefined, requestIdentity: IHttpRequestIdentity, processorState: {
+        [id: string]: unknown;
+    }): Promise<void>;
+}

package/dist/types/identity/nodeIdentityProcessor.d.ts

@@ -0,0 +1,28 @@
+import type { IHttpRequestIdentity, IHttpResponse, IHttpRestRouteProcessor, IHttpServerRequest, IRestRoute } from "@twin.org/api-models";
+/**
+ * Adds a node identity to the request identity.
+ */
+export declare class NodeIdentityProcessor implements IHttpRestRouteProcessor {
+    /**
+     * Runtime name for the class.
+     */
+    readonly CLASS_NAME: string;
+    /**
+     * The service needs to be started when the application is initialized.
+     * @param nodeIdentity The identity of the node.
+     * @param nodeLoggingConnectorType The node logging connector type, defaults to "node-logging".
+     * @returns Nothing.
+     */
+    start(nodeIdentity: string, nodeLoggingConnectorType?: string): Promise<void>;
+    /**
+     * Pre process the REST request for the specified route.
+     * @param request The incoming request.
+     * @param response The outgoing response.
+     * @param route The route to process.
+     * @param requestIdentity The identity context for the request.
+     * @param processorState The state handed through the processors.
+     */
+    pre(request: IHttpServerRequest, response: IHttpResponse, route: IRestRoute | undefined, requestIdentity: IHttpRequestIdentity, processorState: {
+        [id: string]: unknown;
+    }): Promise<void>;
+}

package/dist/types/identity/staticUserIdentityProcessor.d.ts

@@ -0,0 +1,31 @@
+import type { IHttpRequestIdentity, IHttpResponse, IHttpRestRouteProcessor, IHttpServerRequest, IRestRoute } from "@twin.org/api-models";
+import type { IStaticUserIdentityProcessorConfig } from "../models/IStaticUserIdentityProcessorConfig";
+/**
+ * Adds a static user identity to the request context.
+ */
+export declare class StaticUserIdentityProcessor implements IHttpRestRouteProcessor {
+    /**
+     * Runtime name for the class.
+     */
+    readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of StaticIdentityProcessor.
+     * @param options Options for the processor.
+     * @param options.config The configuration for the processor.
+     * @returns Promise that resolves when the processor is initialized.
+     */
+    constructor(options: {
+        config: IStaticUserIdentityProcessorConfig;
+    });
+    /**
+     * Pre process the REST request for the specified route.
+     * @param request The incoming request.
+     * @param response The outgoing response.
+     * @param route The route to process.
+     * @param requestIdentity The identity context for the request.
+     * @param processorState The state handed through the processors.
+     */
+    pre(request: IHttpServerRequest, response: IHttpResponse, route: IRestRoute | undefined, requestIdentity: IHttpRequestIdentity, processorState: {
+        [id: string]: unknown;
+    }): Promise<void>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./data/routeProcessor";
+export * from "./identity/staticUserIdentityProcessor";
+export * from "./identity/nodeIdentityProcessor";
+export * from "./logging/loggingProcessor";
+export * from "./models/IRequestLoggingProcessorConfig";
+export * from "./models/IResponseLoggingProcessorConfig";
+export * from "./models/IRouteProcessorConfig";
+export * from "./models/IStaticUserIdentityProcessorConfig";

package/dist/types/logging/loggingProcessor.d.ts

@@ -0,0 +1,44 @@
+import type { IHttpRequestIdentity, IHttpResponse, IHttpRestRouteProcessor, IHttpServerRequest, IRestRoute } from "@twin.org/api-models";
+import type { IRequestLoggingProcessorConfig } from "../models/IRequestLoggingProcessorConfig";
+/**
+ * Process the REST request and log its information.
+ */
+export declare class LoggingProcessor implements IHttpRestRouteProcessor {
+    /**
+     * Runtime name for the class.
+     */
+    readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of RequestLoggingProcessor.
+     * @param options Options for the processor.
+     * @param options.loggingConnectorType The type for the logging connector, defaults to "logging".
+     * @param options.config The configuration for the processor.
+     * @returns Promise that resolves when the processor is initialized.
+     */
+    constructor(options?: {
+        loggingConnectorType?: string;
+        config?: IRequestLoggingProcessorConfig;
+    });
+    /**
+     * Pre process the REST request for the specified route.
+     * @param request The incoming request.
+     * @param response The outgoing response.
+     * @param route The route to process.
+     * @param requestIdentity The identity context for the request.
+     * @param processorState The state handed through the processors.
+     */
+    pre(request: IHttpServerRequest, response: IHttpResponse, route: IRestRoute | undefined, requestIdentity: IHttpRequestIdentity, processorState: {
+        [id: string]: unknown;
+    }): Promise<void>;
+    /**
+     * Post process the REST request for the specified route.
+     * @param request The incoming request.
+     * @param response The outgoing response.
+     * @param route The route to process.
+     * @param requestIdentity The identity context for the request.
+     * @param processorState The state handed through the processors.
+     */
+    post(request: IHttpServerRequest, response: IHttpResponse, route: IRestRoute | undefined, requestIdentity: IHttpRequestIdentity, processorState: {
+        [id: string]: unknown;
+    }): Promise<void>;
+}

package/dist/types/models/IRequestLoggingProcessorConfig.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Configuration for the request logging processor.
+ */
+export interface IRequestLoggingProcessorConfig {
+    /**
+     * Include the body objects when logging the information.
+     */
+    includeBody?: boolean;
+    /**
+     * Show the full base64 content for data, default to abbreviate.
+     */
+    fullBase64?: boolean;
+    /**
+     * List of property names to obfuscate, can be regex, defaults to "password".
+     */
+    obfuscateProperties?: string[];
+}

package/dist/types/models/IResponseLoggingProcessorConfig.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Configuration for the response logging processor.
+ */
+export interface IResponseLoggingProcessorConfig {
+    /**
+     * Include the body objects when logging the information.
+     */
+    includeBody?: boolean;
+}

package/dist/types/models/IRouteProcessorConfig.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Configuration for the route processor.
+ */
+export interface IRouteProcessorConfig {
+    /**
+     * Include the stack with errors.
+     */
+    includeErrorStack?: boolean;
+}

package/dist/types/models/IStaticUserIdentityProcessorConfig.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Configuration for the static identity processor.
+ */
+export interface IStaticUserIdentityProcessorConfig {
+    /**
+     * The fixed user identity for request context.
+     */
+    userIdentity: string;
+}

package/docs/changelog.md

@@ -0,0 +1,5 @@
+# @twin.org/api-processors - Changelog
+
+## v0.0.1-next.10
+
+- Initial Release

package/docs/examples.md

@@ -0,0 +1 @@
+# @twin.org/api-processors - Examples

package/docs/reference/classes/LoggingProcessor.md

@@ -0,0 +1,123 @@
+# Class: LoggingProcessor
+
+Process the REST request and log its information.
+
+## Implements
+
+- `IHttpRestRouteProcessor`
+
+## Constructors
+
+### new LoggingProcessor()
+
+> **new LoggingProcessor**(`options`?): [`LoggingProcessor`](LoggingProcessor.md)
+
+Create a new instance of RequestLoggingProcessor.
+
+#### Parameters
+
+• **options?**
+
+Options for the processor.
+
+• **options.loggingConnectorType?**: `string`
+
+The type for the logging connector, defaults to "logging".
+
+• **options.config?**: [`IRequestLoggingProcessorConfig`](../interfaces/IRequestLoggingProcessorConfig.md)
+
+The configuration for the processor.
+
+#### Returns
+
+[`LoggingProcessor`](LoggingProcessor.md)
+
+Promise that resolves when the processor is initialized.
+
+## Properties
+
+### CLASS\_NAME
+
+> `readonly` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+#### Implementation of
+
+`IHttpRestRouteProcessor.CLASS_NAME`
+
+## Methods
+
+### pre()
+
+> **pre**(`request`, `response`, `route`, `requestIdentity`, `processorState`): `Promise`\<`void`\>
+
+Pre process the REST request for the specified route.
+
+#### Parameters
+
+• **request**: `IHttpServerRequest`\<`any`\>
+
+The incoming request.
+
+• **response**: `IHttpResponse`\<`any`\>
+
+The outgoing response.
+
+• **route**: `undefined` \| `IRestRoute`\<`any`, `any`\>
+
+The route to process.
+
+• **requestIdentity**: `IHttpRequestIdentity`
+
+The identity context for the request.
+
+• **processorState**
+
+The state handed through the processors.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Implementation of
+
+`IHttpRestRouteProcessor.pre`
+
+***
+
+### post()
+
+> **post**(`request`, `response`, `route`, `requestIdentity`, `processorState`): `Promise`\<`void`\>
+
+Post process the REST request for the specified route.
+
+#### Parameters
+
+• **request**: `IHttpServerRequest`\<`any`\>
+
+The incoming request.
+
+• **response**: `IHttpResponse`\<`any`\>
+
+The outgoing response.
+
+• **route**: `undefined` \| `IRestRoute`\<`any`, `any`\>
+
+The route to process.
+
+• **requestIdentity**: `IHttpRequestIdentity`
+
+The identity context for the request.
+
+• **processorState**
+
+The state handed through the processors.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Implementation of
+
+`IHttpRestRouteProcessor.post`