@twin.org/logging-service 0.0.1-next.10

package/dist/esm/index.mjs

@@ -0,0 +1,252 @@
+import { Guards, ComponentFactory, Coerce, Is } from '@twin.org/core';
+import { HttpStatusCode } from '@twin.org/web';
+import { LogicalOperator, ComparisonOperator, SortDirection } from '@twin.org/entity';
+import { LoggingConnectorFactory } from '@twin.org/logging-models';
+
+/**
+ * The source used when communicating about these routes.
+ */
+const ROUTES_SOURCE = "loggingRoutes";
+/**
+ * The tag to associate with the routes.
+ */
+const tagsLogging = [
+    {
+        name: "Logging",
+        description: "Endpoints which are modelled to access a logging contract."
+    }
+];
+/**
+ * The REST routes for logging.
+ * @param baseRouteName Prefix to prepend to the paths.
+ * @param componentName The name of the component to use in the routes stored in the ComponentFactory.
+ * @returns The generated routes.
+ */
+function generateRestRoutesLogging(baseRouteName, componentName) {
+    const createRoute = {
+        operationId: "loggingEntryCreate",
+        summary: "Create a log entry",
+        tag: tagsLogging[0].name,
+        method: "POST",
+        path: `${baseRouteName}/`,
+        handler: async (httpRequestContext, request) => loggingCreate(httpRequestContext, componentName, request),
+        requestType: {
+            type: "ILoggingCreateRequest",
+            examples: [
+                {
+                    id: "loggingEntryCreateInfoExample",
+                    request: {
+                        body: {
+                            level: "info",
+                            message: "This is an information message",
+                            source: "source",
+                            ts: 1715252922273
+                        }
+                    }
+                },
+                {
+                    id: "loggingEntryCreateErrorExample",
+                    request: {
+                        body: {
+                            level: "info",
+                            message: "This is an error message",
+                            source: "source",
+                            ts: 1715252922273,
+                            error: {
+                                name: "GeneralError",
+                                message: "component.error",
+                                properties: {
+                                    foo: "bar"
+                                }
+                            }
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "INoContentResponse"
+            }
+        ]
+    };
+    const listRoute = {
+        operationId: "loggingListEntries",
+        summary: "Get a list of the log entries",
+        tag: tagsLogging[0].name,
+        method: "GET",
+        path: `${baseRouteName}/`,
+        handler: async (httpRequestContext, request) => loggingList(httpRequestContext, componentName, request),
+        requestType: {
+            type: "ILoggingListRequest",
+            examples: [
+                {
+                    id: "loggingListRequestExample",
+                    request: {
+                        query: {
+                            level: "info"
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "ILoggingListResponse",
+                examples: [
+                    {
+                        id: "listResponseExample",
+                        response: {
+                            body: {
+                                entities: [
+                                    {
+                                        level: "info",
+                                        message: "This is an information message",
+                                        source: "source",
+                                        ts: 1715252922273
+                                    }
+                                ],
+                                cursor: "1"
+                            }
+                        }
+                    }
+                ]
+            }
+        ]
+    };
+    return [createRoute, listRoute];
+}
+/**
+ * Create a new log entry.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+async function loggingCreate(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    Guards.object(ROUTES_SOURCE, "request.body", request.body);
+    const component = ComponentFactory.get(componentName);
+    await component.log(request.body);
+    return {
+        statusCode: HttpStatusCode.noContent
+    };
+}
+/**
+ * Get a list of the logging entries.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+async function loggingList(httpRequestContext, componentName, request) {
+    const component = ComponentFactory.get(componentName);
+    const itemsAndCursor = await component.query(request?.query?.level, request?.query?.source, Coerce.number(request?.query?.timeStart), Coerce.number(request?.query?.timeEnd), request?.query?.cursor, Coerce.number(request?.query?.pageSize));
+    return {
+        body: itemsAndCursor
+    };
+}
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Service for performing logging operations to a connector.
+ */
+class LoggingService {
+    /**
+     * The namespace for the logging component.
+     */
+    static NAMESPACE = "logging";
+    /**
+     * Runtime name for the class.
+     */
+    CLASS_NAME = "LoggingService";
+    /**
+     * Logging connector used by the service.
+     * @internal
+     */
+    _loggingConnector;
+    /**
+     * Create a new instance of LoggingService.
+     * @param options The options for the connector.
+     */
+    constructor(options) {
+        this._loggingConnector = LoggingConnectorFactory.get(options?.loggingConnectorType ?? "logging");
+    }
+    /**
+     * Log an entry to the connector.
+     * @param logEntry The entry to log.
+     * @returns Nothing.
+     */
+    async log(logEntry) {
+        Guards.object(this.CLASS_NAME, "logEntry", logEntry);
+        await this._loggingConnector.log(logEntry);
+    }
+    /**
+     * Query the log entries.
+     * @param level The level of the log entries.
+     * @param source The source of the log entries.
+     * @param timeStart The inclusive time as the start of the log entries.
+     * @param timeEnd The inclusive time as the end of the log entries.
+     * @param cursor The cursor to request the next page of entities.
+     * @param pageSize The maximum number of entities in a page.
+     * @returns All the entities for the storage matching the conditions,
+     * and a cursor which can be used to request more entities.
+     * @throws NotImplementedError if the implementation does not support retrieval.
+     */
+    async query(level, source, timeStart, timeEnd, cursor, pageSize) {
+        const condition = {
+            conditions: [],
+            logicalOperator: LogicalOperator.And
+        };
+        if (Is.stringValue(level)) {
+            condition.conditions.push({
+                property: "level",
+                comparison: ComparisonOperator.Equals,
+                value: level
+            });
+        }
+        if (Is.stringValue(source)) {
+            condition.conditions.push({
+                property: "source",
+                comparison: ComparisonOperator.Equals,
+                value: source
+            });
+        }
+        if (Is.number(timeStart)) {
+            condition.conditions.push({
+                property: "ts",
+                comparison: ComparisonOperator.GreaterThanOrEqual,
+                value: timeStart
+            });
+        }
+        if (Is.number(timeEnd)) {
+            condition.conditions.push({
+                property: "ts",
+                comparison: ComparisonOperator.LessThanOrEqual,
+                value: timeEnd
+            });
+        }
+        const result = await this._loggingConnector.query(condition, [
+            {
+                property: "ts",
+                sortDirection: SortDirection.Descending
+            }
+        ], undefined, cursor, pageSize);
+        return {
+            entities: result.entities,
+            cursor: result.cursor
+        };
+    }
+}
+
+const restEntryPoints = [
+    {
+        name: "logging",
+        defaultBaseRoute: "logging",
+        tags: tagsLogging,
+        generateRoutes: generateRestRoutesLogging
+    }
+];
+
+export { LoggingService, generateRestRoutesLogging, loggingCreate, loggingList, restEntryPoints, tagsLogging };

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./loggingRoutes";
+export * from "./loggingService";
+export * from "./models/ILoggingServiceConstructorOptions";
+export * from "./restEntryPoints";

package/dist/types/loggingRoutes.d.ts

@@ -0,0 +1,29 @@
+import type { IHttpRequestContext, INoContentResponse, IRestRoute, ITag } from "@twin.org/api-models";
+import type { ILoggingCreateRequest, ILoggingListRequest, ILoggingListResponse } from "@twin.org/logging-models";
+/**
+ * The tag to associate with the routes.
+ */
+export declare const tagsLogging: ITag[];
+/**
+ * The REST routes for logging.
+ * @param baseRouteName Prefix to prepend to the paths.
+ * @param componentName The name of the component to use in the routes stored in the ComponentFactory.
+ * @returns The generated routes.
+ */
+export declare function generateRestRoutesLogging(baseRouteName: string, componentName: string): IRestRoute[];
+/**
+ * Create a new log entry.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function loggingCreate(httpRequestContext: IHttpRequestContext, componentName: string, request: ILoggingCreateRequest): Promise<INoContentResponse>;
+/**
+ * Get a list of the logging entries.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function loggingList(httpRequestContext: IHttpRequestContext, componentName: string, request: ILoggingListRequest): Promise<ILoggingListResponse>;

package/dist/types/loggingService.d.ts

@@ -0,0 +1,48 @@
+import { type ILogEntry, type ILoggingComponent, type LogLevel } from "@twin.org/logging-models";
+import type { ILoggingServiceConstructorOptions } from "./models/ILoggingServiceConstructorOptions";
+/**
+ * Service for performing logging operations to a connector.
+ */
+export declare class LoggingService implements ILoggingComponent {
+    /**
+     * The namespace for the logging component.
+     */
+    static readonly NAMESPACE: string;
+    /**
+     * Runtime name for the class.
+     */
+    readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of LoggingService.
+     * @param options The options for the connector.
+     */
+    constructor(options?: ILoggingServiceConstructorOptions);
+    /**
+     * Log an entry to the connector.
+     * @param logEntry The entry to log.
+     * @returns Nothing.
+     */
+    log(logEntry: ILogEntry): Promise<void>;
+    /**
+     * Query the log entries.
+     * @param level The level of the log entries.
+     * @param source The source of the log entries.
+     * @param timeStart The inclusive time as the start of the log entries.
+     * @param timeEnd The inclusive time as the end of the log entries.
+     * @param cursor The cursor to request the next page of entities.
+     * @param pageSize The maximum number of entities in a page.
+     * @returns All the entities for the storage matching the conditions,
+     * and a cursor which can be used to request more entities.
+     * @throws NotImplementedError if the implementation does not support retrieval.
+     */
+    query(level?: LogLevel, source?: string, timeStart?: number, timeEnd?: number, cursor?: string, pageSize?: number): Promise<{
+        /**
+         * The entities, which can be partial if a limited keys list was provided.
+         */
+        entities: ILogEntry[];
+        /**
+         * An optional cursor, when defined can be used to call find to get more entities.
+         */
+        cursor?: string;
+    }>;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Options for the logging service constructor.
+ */
+export interface ILoggingServiceConstructorOptions {
+    /**
+     * The type of the logging connector to use.
+     * @default logging
+     */
+    loggingConnectorType?: string;
+}

package/dist/types/restEntryPoints.d.ts

@@ -0,0 +1,2 @@
+import type { IRestRouteEntryPoint } from "@twin.org/api-models";
+export declare const restEntryPoints: IRestRouteEntryPoint[];

package/docs/changelog.md

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

package/docs/examples.md

@@ -0,0 +1 @@
+# @twin.org/logging-service - Examples