@twin.org/auditable-item-graph-service 0.9.2 → 0.10.0

package/dist/es/auditableItemGraphService.js

@@ -1,7 +1,7 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 import { HealthCategory, HealthStatus } from "@twin.org/api-models";
-import { AuditableItemGraphContexts, AuditableItemGraphDataTypes, AuditableItemGraphMetricIds, AuditableItemGraphMetrics, AuditableItemGraphTopics, AuditableItemGraphTypes, VerifyDepth } from "@twin.org/auditable-item-graph-models";
+import { AuditableItemGraphAuditMode, AuditableItemGraphContexts, AuditableItemGraphDataTypes, AuditableItemGraphMetricIds, AuditableItemGraphMetrics, AuditableItemGraphTopics, AuditableItemGraphTypes, VerifyDepth } from "@twin.org/auditable-item-graph-models";
 import { ContextIdHelper, ContextIdKeys, ContextIdStore } from "@twin.org/context";
 import { ArrayHelper, BaseError, Coerce, ComponentFactory, GeneralError, Guards, Is, JsonHelper, Mutex, NotFoundError, ObjectHelper, RandomHelper, StringHelper, Urn, Validation } from "@twin.org/core";
 import { DataTypeHelper } from "@twin.org/data-core";
@@ -151,6 +151,7 @@ export class AuditableItemGraphService {
     /**
      * Create a new graph vertex.
      * @param vertex The vertex to create.
+     * @param vertex.auditMode How the mutations of the vertex are recorded, defaults to audited.
      * @param vertex.annotationObject The annotation object for the vertex as JSON-LD.
      * @param vertex.aliases Alternative aliases that can be used to identify the vertex.
      * @param vertex.resources The resources attached to the vertex.
@@ -159,6 +160,9 @@ export class AuditableItemGraphService {
      */
     async create(vertex) {
         Guards.object(AuditableItemGraphService.CLASS_NAME, "vertex", vertex);
+        if (Is.notEmpty(vertex.auditMode)) {
+            Guards.arrayOneOf(AuditableItemGraphService.CLASS_NAME, "vertex.auditMode", vertex.auditMode, Object.values(AuditableItemGraphAuditMode));
+        }
         const contextIds = await ContextIdStore.getContextIds();
         ContextIdHelper.guard(contextIds, ContextIdKeys.Organization);
         try {
@@ -186,14 +190,18 @@ export class AuditableItemGraphService {
                 dateCreated: context.now
             };
             const originalEntity = ObjectHelper.clone(vertexModel);
+            vertexModel.auditMode = vertex.auditMode;
             vertexModel.annotationObject = vertex.annotationObject;
             await this.updateAliasList(context, vertexModel, vertex.aliases);
             await this.updateResourceList(context, vertexModel, vertex.resources);
             await this.updateEdgeList(context, vertexModel, vertex.edges);
-            delete originalEntity.aliasIndex;
-            delete originalEntity.resourceTypeIndex;
-            await this.addChangeset(context, originalEntity, vertexModel, true, 0);
-            vertexModel.version = 0;
+            // Bypass vertices keep no changeset history, so there is no baseline version to record.
+            if (vertex.auditMode !== AuditableItemGraphAuditMode.Bypass) {
+                delete originalEntity.aliasIndex;
+                delete originalEntity.resourceTypeIndex;
+                await this.addChangeset(context, originalEntity, vertexModel, true, 0);
+                vertexModel.version = 0;
+            }
             await this._vertexStorage.set({
                 ...vertexModel,
                 ...this.buildIndexes(vertexModel)
@@ -212,10 +220,14 @@ export class AuditableItemGraphService {
      * Concurrent updates for the same vertex are serialized via `Mutex` on the vertex id.
      * @param vertex The vertex to update.
      * @returns A promise that resolves when the vertex has been updated.
+     * @throws GeneralError If a bypass vertex is being switched back to audited.
      */
     async update(vertex) {
         Guards.object(AuditableItemGraphService.CLASS_NAME, "vertex", vertex);
         Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "vertex.id", vertex.id);
+        if (Is.notEmpty(vertex.auditMode)) {
+            Guards.arrayOneOf(AuditableItemGraphService.CLASS_NAME, "vertex.auditMode", vertex.auditMode, Object.values(AuditableItemGraphAuditMode));
+        }
         const vertexId = this.parseVertexId(vertex.id);
         await Mutex.lock(vertexId, { throwOnTimeout: true, timeoutMs: this._mutexTimeoutMs });
         try {
@@ -241,6 +253,7 @@ export class AuditableItemGraphService {
                     organizationIdentity: ownerOrganizationId,
                     userIdentity: contextIds?.[ContextIdKeys.User]
                 };
+                const auditModeTransition = this.resolveAuditModeTransition(vertexEntity, vertex.auditMode);
                 delete vertexEntity.aliasIndex;
                 const originalEntity = ObjectHelper.clone(vertexEntity);
                 const newEntity = ObjectHelper.clone(vertexEntity);
@@ -248,7 +261,7 @@ export class AuditableItemGraphService {
                 await this.updateAliasList(context, newEntity, vertex.aliases);
                 await this.updateResourceList(context, newEntity, vertex.resources);
                 await this.updateEdgeList(context, newEntity, vertex.edges);
-                await this.persistVertexChanges(context, vertexId, vertex.id, originalEntity, newEntity);
+                await this.persistVertexChanges(context, vertexId, vertex.id, originalEntity, newEntity, auditModeTransition);
             }
             catch (error) {
                 throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "updatingFailed", undefined, error);
@@ -263,10 +276,14 @@ export class AuditableItemGraphService {
      * Serialized with `update` via `Mutex` on the same vertex id within this instance.
      * @param partial The partial vertex update.
      * @returns A promise that resolves when the partial update has been applied.
+     * @throws GeneralError If a bypass vertex is being switched back to audited.
      */
     async updatePartial(partial) {
         Guards.object(AuditableItemGraphService.CLASS_NAME, "partial", partial);
         Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "partial.id", partial.id);
+        if (Is.notEmpty(partial.auditMode)) {
+            Guards.arrayOneOf(AuditableItemGraphService.CLASS_NAME, "partial.auditMode", partial.auditMode, Object.values(AuditableItemGraphAuditMode));
+        }
         const vertexId = this.parseVertexId(partial.id);
         await Mutex.lock(vertexId, { throwOnTimeout: true, timeoutMs: this._mutexTimeoutMs });
         try {
@@ -289,6 +306,7 @@ export class AuditableItemGraphService {
                     organizationIdentity: ownerOrganizationId,
                     userIdentity: contextIds?.[ContextIdKeys.User]
                 };
+                const auditModeTransition = this.resolveAuditModeTransition(vertexEntity, partial.auditMode);
                 delete vertexEntity.aliasIndex;
                 const originalEntity = ObjectHelper.clone(vertexEntity);
                 const newEntity = ObjectHelper.clone(vertexEntity);
@@ -307,7 +325,7 @@ export class AuditableItemGraphService {
                     const edgePatch = this.validateListPatch("partial.edgePatches", partial.edgePatches);
                     await this.applyEdgePatch(context, newEntity, edgePatch);
                 }
-                await this.persistVertexChanges(context, vertexId, partial.id, originalEntity, newEntity);
+                await this.persistVertexChanges(context, vertexId, partial.id, originalEntity, newEntity, auditModeTransition);
             }
             catch (error) {
                 throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "updatingFailed", undefined, error);
@@ -342,7 +360,10 @@ export class AuditableItemGraphService {
                 throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", id);
             }
             const vertexModel = this.vertexEntityToJsonLd(vertexEntity);
-            const verifySignatureDepth = options?.verifySignatureDepth ?? VerifyDepth.None;
+            // Bypass vertices have no changesets to verify, so verification is never reported for them.
+            const verifySignatureDepth = this.isBypass(vertexEntity)
+                ? VerifyDepth.None
+                : (options?.verifySignatureDepth ?? VerifyDepth.None);
             let verified;
             if (verifySignatureDepth === VerifyDepth.Current ||
                 verifySignatureDepth === VerifyDepth.All) {
@@ -407,8 +428,12 @@ export class AuditableItemGraphService {
             if (Is.empty(vertexEntity)) {
                 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) {
+            // Bypass vertices maintain no changeset history.
+            const chunk = this.isBypass(vertexEntity)
+                ? { changesets: [], verified: true, cursor: undefined }
+                : await this.verifyChangesetChunk(vertexId, options?.verifySignatureDepth ?? VerifyDepth.None, cursor, limit);
+            if (!this.isBypass(vertexEntity) &&
+                (options?.verifySignatureDepth ?? VerifyDepth.None) !== VerifyDepth.None) {
                 if (chunk.verified) {
                     await MetricHelper.metricIncrement(this._telemetryComponent, AuditableItemGraphMetricIds.VerificationsSucceeded);
                 }
@@ -462,6 +487,10 @@ export class AuditableItemGraphService {
             if (Is.empty(vertexEntity)) {
                 throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", id);
             }
+            // Bypass vertices maintain no changeset history.
+            if (this.isBypass(vertexEntity)) {
+                throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "changesetNotFound", id);
+            }
             const changesetEntity = await this._changesetStorage.get(changesetId);
             if (Is.empty(changesetEntity)) {
                 throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "changesetNotFound", id);
@@ -494,7 +523,7 @@ export class AuditableItemGraphService {
      * @param id The id of the vertex.
      * @param version The version number to retrieve.
      * @returns The vertex reconstructed at that version.
-     * @throws NotFoundError if the vertex or version is not found.
+     * @throws NotFoundError if the vertex or version is not found, a bypass vertex never has versions.
      */
     async getVersion(id, version) {
         Guards.stringValue(AuditableItemGraphService.CLASS_NAME, "id", id);
@@ -512,6 +541,10 @@ export class AuditableItemGraphService {
             if (Is.empty(vertexEntity)) {
                 throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "vertexNotFound", id);
             }
+            // Bypass vertices maintain no version chain.
+            if (this.isBypass(vertexEntity)) {
+                throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "versionNotFound", version.toString());
+            }
             const currentVersion = vertexEntity.version ?? 0;
             if (version > currentVersion || version < 0) {
                 throw new NotFoundError(AuditableItemGraphService.CLASS_NAME, "versionNotFound", version.toString());
@@ -552,7 +585,8 @@ export class AuditableItemGraphService {
      * @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.
+     * @returns The list of vertex versions, a bypass vertex returns a single baseline entry for its
+     * current state when that falls within the requested range.
      * @throws NotFoundError if the vertex is not found.
      */
     async getVersions(id, options) {
@@ -572,20 +606,9 @@ export class AuditableItemGraphService {
             }
             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({
-                        version: changeset.version ?? 0,
-                        dateCreated: changeset.dateCreated
-                    });
-                }
-            }
+            const versions = this.isBypass(vertexEntity)
+                ? this.bypassVersions(vertexEntity, afterDate, beforeDate)
+                : await this.auditedVersions(vertexId, afterDate, beforeDate);
             const versionList = {
                 "@context": [
                     SchemaOrgContexts.Context,
@@ -795,6 +818,47 @@ export class AuditableItemGraphService {
         Guards.object(AuditableItemGraphService.CLASS_NAME, propertyName, patch);
         return patch;
     }
+    /**
+     * Resolve the audit mode for an update, bypass is terminal so it can not return to audited.
+     * @param vertexEntity The stored vertex entity.
+     * @param requestedMode The audit mode requested by the caller, when absent the stored mode is kept.
+     * @returns The audit mode to apply and whether the existing history must be compacted.
+     * @throws GeneralError If a bypass vertex is being switched back to audited.
+     * @internal
+     */
+    resolveAuditModeTransition(vertexEntity, requestedMode) {
+        const currentMode = vertexEntity.auditMode ?? AuditableItemGraphAuditMode.Audited;
+        if (Is.empty(requestedMode)) {
+            return { auditMode: currentMode, compactHistory: false };
+        }
+        if (currentMode === AuditableItemGraphAuditMode.Bypass &&
+            requestedMode === AuditableItemGraphAuditMode.Audited) {
+            throw new GeneralError(AuditableItemGraphService.CLASS_NAME, "auditModeTransitionNotAllowed", {
+                currentMode,
+                requestedMode
+            });
+        }
+        return {
+            auditMode: requestedMode,
+            compactHistory: currentMode === AuditableItemGraphAuditMode.Audited &&
+                requestedMode === AuditableItemGraphAuditMode.Bypass
+        };
+    }
+    /**
+     * Discard the changeset history for a vertex along with any proofs the changesets reference.
+     * @param vertexId The compact vertex id.
+     * @returns A promise that resolves when the history and its proofs have been removed.
+     * @internal
+     */
+    async compactVertexHistory(vertexId) {
+        const changesets = await this.internalGetChangesets(vertexId);
+        for (const changeset of changesets) {
+            await this._changesetStorage.remove(changeset.id);
+            if (Is.stringValue(changeset.proofId)) {
+                await this._immutableProofComponent.remove(changeset.proofId);
+            }
+        }
+    }
     /**
      * Persist vertex changes after update or partial update.
      * @param context The context for the operation.
@@ -802,10 +866,17 @@ export class AuditableItemGraphService {
      * @param vertexUrn The vertex URN for events.
      * @param originalEntity The entity before changes.
      * @param newEntity The entity after changes.
+     * @param auditModeTransition The audit mode to apply and whether the history must be compacted.
+     * @param auditModeTransition.auditMode The audit mode to apply.
+     * @param auditModeTransition.compactHistory Whether the existing history must be discarded.
      * @returns A promise that resolves when the changes have been persisted and events published.
      * @internal
      */
-    async persistVertexChanges(context, vertexId, vertexUrn, originalEntity, newEntity) {
+    async persistVertexChanges(context, vertexId, vertexUrn, originalEntity, newEntity, auditModeTransition) {
+        if (auditModeTransition.auditMode === AuditableItemGraphAuditMode.Bypass) {
+            await this.persistBypassChanges(context, vertexId, vertexUrn, originalEntity, newEntity, auditModeTransition.compactHistory);
+            return;
+        }
         const nextVersion = Is.empty(originalEntity.version)
             ? (await this.internalGetChangesets(vertexId)).length
             : originalEntity.version + 1;
@@ -824,6 +895,47 @@ export class AuditableItemGraphService {
             await this._eventBusComponent?.publish(AuditableItemGraphTopics.VertexUpdated, { id: vertexUrn, patches });
         }
     }
+    /**
+     * Persist vertex changes for a bypass vertex, overwriting the stored state with no changeset.
+     * @param context The context for the operation.
+     * @param vertexId The compact vertex id.
+     * @param vertexUrn The vertex URN for events.
+     * @param originalEntity The entity before changes.
+     * @param newEntity The entity after changes.
+     * @param compactHistory Whether the vertex is switching from audited and must discard its history.
+     * @returns A promise that resolves when the changes have been persisted and events published.
+     * @internal
+     */
+    async persistBypassChanges(context, vertexId, vertexUrn, originalEntity, newEntity, compactHistory) {
+        newEntity.auditMode = AuditableItemGraphAuditMode.Bypass;
+        delete newEntity.version;
+        const patches = JsonHelper.diff(originalEntity, newEntity);
+        if (patches.length === 0) {
+            return;
+        }
+        if (compactHistory) {
+            await this.compactVertexHistory(vertexId);
+        }
+        newEntity.dateModified = context.now;
+        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: vertexUrn, patches });
+    }
+    /**
+     * Whether the vertex records its mutations in place with no audit trail.
+     * @param vertexEntity The stored vertex entity.
+     * @returns True if the vertex is in bypass mode.
+     * @internal
+     */
+    isBypass(vertexEntity) {
+        return vertexEntity.auditMode === AuditableItemGraphAuditMode.Bypass;
+    }
     /**
      * Map the vertex entity to JSON-LD.
      * @param vertexEntity The vertex entity.
@@ -842,6 +954,7 @@ export class AuditableItemGraphService {
             dateCreated: vertexEntity.dateCreated,
             dateModified: vertexEntity.dateModified,
             organizationIdentity: vertexEntity.organizationIdentity,
+            auditMode: vertexEntity.auditMode,
             annotationObject: vertexEntity.annotationObject
         };
         if (Is.arrayValue(vertexEntity.aliases)) {
@@ -981,6 +1094,53 @@ export class AuditableItemGraphService {
         } while (Is.stringValue(cursor));
         return all;
     }
+    /**
+     * Build the version list for an audited vertex from its changesets.
+     * @param vertexId The compact vertex id.
+     * @param afterDate Only include versions created after this date, exclusive.
+     * @param beforeDate Only include versions created before this date, exclusive.
+     * @returns The matching versions in ascending order.
+     * @internal
+     */
+    async auditedVersions(vertexId, afterDate, beforeDate) {
+        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({
+                    version: changeset.version ?? 0,
+                    dateCreated: changeset.dateCreated
+                });
+            }
+        }
+        return versions;
+    }
+    /**
+     * Build the version list for a bypass vertex, which only exposes its current state as
+     * a single baseline entry numbered zero.
+     * @param vertexEntity The stored vertex entity.
+     * @param afterDate Only include the state when it was modified after this date, exclusive.
+     * @param beforeDate Only include the state when it was modified before this date, exclusive.
+     * @returns The baseline entry when the state falls within the range, otherwise empty.
+     * @internal
+     */
+    bypassVersions(vertexEntity, afterDate, beforeDate) {
+        const stateDate = vertexEntity.dateModified ?? vertexEntity.dateCreated;
+        const stateDateTime = Coerce.dateTime(stateDate);
+        if (!Is.empty(stateDateTime)) {
+            if (!Is.empty(beforeDate) && stateDateTime >= beforeDate) {
+                return [];
+            }
+            if (!Is.empty(afterDate) && stateDateTime <= afterDate) {
+                return [];
+            }
+        }
+        return [{ version: 0, dateCreated: stateDate }];
+    }
     /**
      * Replace the aliases of a vertex model (PUT).
      * @param context The context for the operation.