@twin.org/auditable-item-graph-service 0.0.3-next.13 → 0.0.3-next.15

package/dist/es/auditableItemGraphService.js

@@ -1,14 +1,15 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-import { AuditableItemGraphContexts, AuditableItemGraphDataTypes, AuditableItemGraphTopics, AuditableItemGraphTypes, VerifyDepth } from "@twin.org/auditable-item-graph-models";
+import { AuditableItemGraphContexts, AuditableItemGraphDataTypes, AuditableItemGraphMetricIds, AuditableItemGraphMetrics, AuditableItemGraphTopics, AuditableItemGraphTypes, VerifyDepth } from "@twin.org/auditable-item-graph-models";
 import { ContextIdKeys, ContextIdStore } from "@twin.org/context";
-import { ArrayHelper, ComponentFactory, GeneralError, Guards, Is, JsonHelper, NotFoundError, ObjectHelper, RandomHelper, StringHelper, Urn, Validation } from "@twin.org/core";
+import { ArrayHelper, Coerce, ComponentFactory, GeneralError, Guards, Is, JsonHelper, NotFoundError, ObjectHelper, RandomHelper, StringHelper, Urn, Validation } from "@twin.org/core";
 import { DataTypeHelper } from "@twin.org/data-core";
 import { JsonLdDataTypes, JsonLdHelper, JsonLdProcessor } from "@twin.org/data-json-ld";
 import { ComparisonOperator, LogicalOperator, SortDirection } from "@twin.org/entity";
 import { EntityStorageConnectorFactory } from "@twin.org/entity-storage-models";
 import { ImmutableProofContexts, ImmutableProofFailure, ImmutableProofTypes } from "@twin.org/immutable-proof-models";
 import { SchemaOrgContexts, SchemaOrgDataTypes, SchemaOrgTypes } from "@twin.org/standards-schema-org";
+import { MetricHelper } from "@twin.org/telemetry-models";
 /**
  * Class for performing auditable item graph operations.
  */
@@ -61,6 +62,11 @@ export class AuditableItemGraphService {
      * @internal
      */
     _eventBusComponent;
+    /**
+     * The telemetry component.
+     * @internal
+     */
+    _telemetryComponent;
     /**
      * Create a new instance of AuditableItemGraphService.
      * @param options The dependencies for the auditable item graph connector.
@@ -69,9 +75,8 @@ export class AuditableItemGraphService {
         this._immutableProofComponent = ComponentFactory.get(options?.immutableProofComponentType ?? "immutable-proof");
         this._vertexStorage = EntityStorageConnectorFactory.get(options?.vertexEntityStorageType ?? "auditable-item-graph-vertex");
         this._changesetStorage = EntityStorageConnectorFactory.get(options?.changesetEntityStorageType ?? "auditable-item-graph-changeset");
-        if (Is.stringValue(options?.eventBusComponentType)) {
-            this._eventBusComponent = ComponentFactory.get(options.eventBusComponentType);
-        }
+        this._eventBusComponent = ComponentFactory.getIfExists(options?.eventBusComponentType);
+        this._telemetryComponent = ComponentFactory.getIfExists(options?.telemetryComponentType);
         SchemaOrgDataTypes.registerRedirects();
         AuditableItemGraphDataTypes.registerTypes();
         JsonLdDataTypes.registerTypes();
@@ -83,6 +88,15 @@ export class AuditableItemGraphService {
     className() {
         return AuditableItemGraphService.CLASS_NAME;
     }
+    /**
+     * Register all AIG metrics with the telemetry component.
+     */
+    async start() {
+        if (Is.undefined(this._telemetryComponent)) {
+            return;
+        }
+        await MetricHelper.createMetrics(this._telemetryComponent, AuditableItemGraphMetrics);
+    }
     /**
      * Create a new graph vertex.
      * @param vertex The vertex to create.
@@ -124,11 +138,13 @@ export class AuditableItemGraphService {
             await this.updateEdgeList(context, vertexModel, vertex.edges);
             delete originalEntity.aliasIndex;
             delete originalEntity.resourceTypeIndex;
-            await this.addChangeset(context, originalEntity, vertexModel, true);
+            await this.addChangeset(context, originalEntity, vertexModel, true, 0);
+            vertexModel.version = 0;
             await this._vertexStorage.set({
                 ...vertexModel,
                 ...this.buildIndexes(vertexModel)
             });
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.VerticesCreated);
             const fullId = new Urn(AuditableItemGraphService.NAMESPACE, id).toString();
             await this._eventBusComponent?.publish(AuditableItemGraphTopics.VertexCreated, { id: fullId });
             return fullId;
@@ -183,14 +199,21 @@ export class AuditableItemGraphService {
             await this.updateAliasList(context, newEntity, vertex.aliases);
             await this.updateResourceList(context, newEntity, vertex.resources);
             await this.updateEdgeList(context, newEntity, vertex.edges);
-            const patches = await this.addChangeset(context, originalEntity, newEntity, false);
+            const nextVersion = Is.empty(vertexEntity.version)
+                ? (await this.internalGetChangesets(vertexId)).length
+                : vertexEntity.version + 1;
+            const patches = await this.addChangeset(context, originalEntity, newEntity, false, nextVersion);
             if (patches.length > 0) {
                 newEntity.dateModified = context.now;
+                newEntity.version = nextVersion;
                 const indexes = this.buildIndexes(newEntity);
                 await this._vertexStorage.set({
                     ...newEntity,
                     ...indexes
                 });
+                await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.VerticesUpdated, {
+                    patchCount: patches.length
+                });
                 await this._eventBusComponent?.publish(AuditableItemGraphTopics.VertexUpdated, { id: vertex.id, patches });
             }
         }
@@ -287,6 +310,14 @@ export class AuditableItemGraphService {
                 throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", id);
             }
             const chunk = await this.verifyChangesetChunk(vertexId, options?.verifySignatureDepth ?? VerifyDepth.None, cursor, limit);
+            if ((options?.verifySignatureDepth ?? VerifyDepth.None) !== VerifyDepth.None) {
+                if (chunk.verified) {
+                    await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.VerificationsSucceeded);
+                }
+                else {
+                    await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.VerificationsFailed);
+                }
+            }
             const changesetList = {
                 "@context": [
                     SchemaOrgContexts.Context,
@@ -340,6 +371,14 @@ export class AuditableItemGraphService {
             if (verifySignatureDepth !== VerifyDepth.None) {
                 changesetModel["@context"]?.push(ImmutableProofContexts.Context);
                 changesetModel.verification = await this.verifyChangesetSignature(changesetModel);
+                if (changesetModel.verification?.verified) {
+                    await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.VerificationsSucceeded);
+                }
+                else {
+                    await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.VerificationsFailed, {
+                        failureReason: changesetModel.verification?.failure
+                    });
+                }
             }
             const result = await JsonLdProcessor.compact(changesetModel, changesetModel["@context"]);
             return result;
@@ -348,6 +387,105 @@ export class AuditableItemGraphService {
             throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "getFailed", undefined, error);
         }
     }
+    /**
+     * Get a graph vertex at a specific version.
+     * @param id The id of the vertex.
+     * @param versionId The id of the version (changeset id) to retrieve.
+     * @returns The vertex reconstructed at that version.
+     * @throws NotFoundError if the vertex or version is not found.
+     */
+    async getVersion(id, versionId) {
+        Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "id", id);
+        Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "versionId", versionId);
+        const urnParsed = Urn.fromValidString(id);
+        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService.NAMESPACE) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "namespaceMismatch", {
+                namespace: AuditableItemGraphService.NAMESPACE,
+                id
+            });
+        }
+        try {
+            const vertexId = urnParsed.namespaceSpecific(0);
+            const vertexEntity = await this._vertexStorage.get(vertexId);
+            if (Is.empty(vertexEntity)) {
+                throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", id);
+            }
+            const targetChangeset = await this._changesetStorage.get(versionId);
+            if (Is.empty(targetChangeset) || targetChangeset.vertexId !== vertexId) {
+                throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "versionNotFound", versionId);
+            }
+            const changesets = await this.internalGetChangesets(vertexId, {
+                maxVersion: targetChangeset.version
+            });
+            let entityState = {
+                id: vertexEntity.id,
+                dateCreated: vertexEntity.dateCreated,
+                organizationIdentity: vertexEntity.organizationIdentity
+            };
+            for (const changeset of changesets) {
+                entityState = JsonHelper.patch(entityState, changeset.patches);
+            }
+            const vertexModel = this.vertexEntityToJsonLd(entityState);
+            vertexModel.version = targetChangeset.version;
+            const result = await JsonLdProcessor.compact(vertexModel, vertexModel["@context"]);
+            return result;
+        }
+        catch (error) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "getVersionFailed", undefined, error);
+        }
+    }
+    /**
+     * Get all versions of a graph vertex.
+     * @param id The id of the vertex.
+     * @param options Additional options for the operation.
+     * @param options.after Only return versions created after this ISO 8601 timestamp (exclusive).
+     * @param options.before Only return versions created before this ISO 8601 timestamp (exclusive).
+     * @returns The list of vertex versions.
+     * @throws NotFoundError if the vertex is not found.
+     */
+    async getVersions(id, options) {
+        Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "id", id);
+        const urnParsed = Urn.fromValidString(id);
+        if (urnParsed.namespaceIdentifier() !== AuditableItemGraphService.NAMESPACE) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "namespaceMismatch", {
+                namespace: AuditableItemGraphService.NAMESPACE,
+                id
+            });
+        }
+        try {
+            const vertexId = urnParsed.namespaceSpecific(0);
+            const vertexEntity = await this._vertexStorage.get(vertexId);
+            if (Is.empty(vertexEntity)) {
+                throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", id);
+            }
+            const beforeDate = Coerce.dateTime(options?.before);
+            const afterDate = Coerce.dateTime(options?.after);
+            const allChangesets = await this.internalGetChangesets(vertexId, {
+                before: beforeDate?.toISOString()
+            });
+            const versions = [];
+            for (const changeset of allChangesets) {
+                const changesetDate = Coerce.dateTime(changeset.dateCreated);
+                const afterExcluded = !Is.empty(afterDate) && !Is.empty(changesetDate) && changesetDate <= afterDate;
+                if (!afterExcluded) {
+                    versions.push(changeset.version ?? 0);
+                }
+            }
+            const versionList = {
+                "@context": [
+                    SchemaOrgContexts.Context,
+                    AuditableItemGraphContexts.Context,
+                    AuditableItemGraphContexts.ContextCommon
+                ],
+                type: [SchemaOrgTypes.ItemList, AuditableItemGraphTypes.VertexVersionList],
+                [SchemaOrgTypes.ItemListElement]: versions
+            };
+            return await JsonLdProcessor.compact(versionList, versionList["@context"]);
+        }
+        catch (error) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "getVersionsFailed", undefined, error);
+        }
+    }
     /**
      * Remove the verifiable storage for an item.
      * @param id The id of the vertex to get.
@@ -474,6 +612,10 @@ export class AuditableItemGraphService {
                 [SchemaOrgTypes.ItemListElement]: models
             };
             const result = await JsonLdProcessor.compact(vertexList, vertexList["@context"]);
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.QueriesExecuted, {
+                resultCount: models.length,
+                hasMore: Is.stringValue(results.cursor)
+            });
             return {
                 entries: result,
                 cursor: results.cursor
@@ -599,10 +741,47 @@ export class AuditableItemGraphService {
                 patchFrom: p.from,
                 patchValue: p.value
             })),
-            proofId: changesetEntity.proofId
+            proofId: changesetEntity.proofId,
+            version: changesetEntity.version
         };
         return model;
     }
+    /**
+     * Fetch all changesets for a vertex in ascending date order.
+     * @param vertexId The internal vertex id.
+     * @param options Optional filtering options.
+     * @param options.before Only fetch changesets created strictly before this ISO 8601 timestamp.
+     * @param options.maxVersion Only fetch changesets with version <= this value.
+     * @returns All changeset entities sorted ascending by dateCreated.
+     * @internal
+     */
+    async internalGetChangesets(vertexId, options) {
+        const all = [];
+        let cursor;
+        const conditions = [
+            { property: "vertexId", value: vertexId, comparison: ComparisonOperator.Equals }
+        ];
+        if (Is.stringValue(options?.before)) {
+            conditions.push({
+                property: "dateCreated",
+                value: options.before,
+                comparison: ComparisonOperator.LessThan
+            });
+        }
+        if (!Is.empty(options?.maxVersion)) {
+            conditions.push({
+                property: "version",
+                value: options.maxVersion,
+                comparison: ComparisonOperator.LessThanOrEqual
+            });
+        }
+        do {
+            const result = await this._changesetStorage.query({ conditions, logicalOperator: LogicalOperator.And }, [{ property: "dateCreated", sortDirection: SortDirection.Ascending }], undefined, cursor);
+            all.push(...result.entities);
+            cursor = result.cursor;
+        } while (Is.stringValue(cursor));
+        return all;
+    }
     /**
      * Update the aliases of a vertex model.
      * @param context The context for the operation.
@@ -617,6 +796,7 @@ export class AuditableItemGraphService {
             for (const alias of active) {
                 if (!aliases?.find(a => a.id === alias.id)) {
                     alias.dateDeleted = context.now;
+                    await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.AliasesDeleted);
                 }
             }
         }
@@ -662,6 +842,7 @@ export class AuditableItemGraphService {
                 unique: alias.unique
             };
             vertex.aliases.push(model);
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.AliasesAdded);
         }
         else if (existing.aliasFormat !== alias.aliasFormat ||
             !ObjectHelper.equal(existing.annotationObject, alias.annotationObject, false) ||
@@ -671,6 +852,7 @@ export class AuditableItemGraphService {
             existing.aliasFormat = alias.aliasFormat;
             existing.annotationObject = alias.annotationObject;
             existing.unique = alias.unique;
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.AliasesModified);
         }
     }
     /**
@@ -697,6 +879,7 @@ export class AuditableItemGraphService {
             for (const resource of active) {
                 if (!resources?.find(a => this.getResourceId(a) === this.getResourceId(resource))) {
                     resource.dateDeleted = context.now;
+                    await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.ResourcesDeleted);
                 }
             }
         }
@@ -731,11 +914,13 @@ export class AuditableItemGraphService {
                 resourceObject: resource.resourceObject
             };
             vertex.resources.push(model);
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.ResourcesAdded);
         }
         else if (!ObjectHelper.equal(existing.resourceObject, resource.resourceObject, false)) {
             // Existing resource found, update the resourceObject.
             existing.dateModified = context.now;
             existing.resourceObject = resource.resourceObject;
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.ResourcesModified);
         }
     }
     /**
@@ -752,6 +937,7 @@ export class AuditableItemGraphService {
             for (const edge of active) {
                 if (!edges?.find(e => Is.stringValue(e.id) && this.reduceEdgeId(e.id) === edge.id)) {
                     edge.dateDeleted = context.now;
+                    await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.EdgesDeleted);
                 }
             }
         }
@@ -803,6 +989,7 @@ export class AuditableItemGraphService {
                 edgeRelationships: edge.edgeRelationships
             };
             vertex.edges.push(model);
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.EdgesAdded);
         }
         else if (existing.targetId !== edge.targetId ||
             !ArrayHelper.matches(existing.edgeRelationships, edge.edgeRelationships) ||
@@ -812,6 +999,7 @@ export class AuditableItemGraphService {
             existing.dateModified = context.now;
             existing.edgeRelationships = edge.edgeRelationships;
             existing.annotationObject = edge.annotationObject;
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.EdgesModified);
         }
     }
     /**
@@ -820,10 +1008,11 @@ export class AuditableItemGraphService {
      * @param original The original vertex.
      * @param updated The updated vertex.
      * @param isNew Whether this is a new item.
+     * @param version The version number of the vertex after this changeset.
      * @returns True if there were changes.
      * @internal
      */
-    async addChangeset(context, original, updated, isNew) {
+    async addChangeset(context, original, updated, isNew, version) {
         const patches = JsonHelper.diff(original, updated);
         // If there is a diff set or this is the first time the item is created.
         if (patches.length > 0 || isNew) {
@@ -832,15 +1021,17 @@ export class AuditableItemGraphService {
                 vertexId: updated.id,
                 dateCreated: context.now,
                 userIdentity: context.contextIds?.[ContextIdKeys.User],
-                patches
+                patches,
+                version
             };
             // Create the JSON-LD object we want to use for the proof
             // this is a subset of fixed properties from the changeset object.
             const reducedChangesetJsonLd = this.changesetEntityToJsonLd(original.id, ObjectHelper.pick(changesetEntity, AuditableItemGraphService._PROOF_KEYS_CHANGESET));
             // Create the proof for the changeset object
-            changesetEntity.proofId = await this._immutableProofComponent.create(reducedChangesetJsonLd);
+            changesetEntity.proofId = await this._immutableProofComponent.create(JsonLdHelper.toNodeObject(reducedChangesetJsonLd));
             // Link the verifiable storage id to the changeset
             await this._changesetStorage.set(changesetEntity);
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.ChangesetsCreated);
             return patches;
         }
         return [];
@@ -865,6 +1056,12 @@ export class AuditableItemGraphService {
             }
             changesets.push(...chunk.changesets);
         } while (Is.stringValue(cursor));
+        if (verified) {
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.VerificationsSucceeded);
+        }
+        else {
+            await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.VerificationsFailed);
+        }
         return {
             verified,
             changesets