@twin.org/dataspace-control-plane-service 0.0.3-next.47 → 0.0.3-next.49

package/dist/es/dataspaceControlPlaneService.js

@@ -1,15 +1,16 @@
 // Copyright 2025 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-import { HttpUrlHelper } from "@twin.org/api-models";
-import { ContextIdKeys, ContextIdStore, ContextIdHelper } from "@twin.org/context";
-import { ArrayHelper, AlreadyExistsError, BaseError, ComponentFactory, Converter, GeneralError, Guards, Is, NotFoundError, ObjectHelper, RandomHelper, StringHelper, UnauthorizedError, Url, Urn, ValidationError } from "@twin.org/core";
+import { HttpContextIdKeys, HttpUrlHelper } from "@twin.org/api-models";
+import { ContextIdHelper, ContextIdKeys, ContextIdStore } from "@twin.org/context";
+import { AlreadyExistsError, ArrayHelper, BaseError, ComponentFactory, Converter, GeneralError, Guards, Is, NotFoundError, ObjectHelper, RandomHelper, StringHelper, UnauthorizedError, Url, Urn, ValidationError } from "@twin.org/core";
 import { JsonLdHelper } from "@twin.org/data-json-ld";
-import { DataspaceAppFactory, DataspaceTransferFormat, TransferProcessRole, getJsonLdId, getJsonLdType } from "@twin.org/dataspace-models";
+import { DataspaceControlPlaneMetricIds, DataspaceControlPlaneMetrics, DataspaceTransferFormat, TransferProcessRole, getJsonLdId, getJsonLdType } from "@twin.org/dataspace-models";
 import { EngineCoreFactory } from "@twin.org/engine-models";
 import { ComparisonOperator } from "@twin.org/entity";
 import { EntityStorageConnectorFactory } from "@twin.org/entity-storage-models";
 import { OdrlPolicyHelper, PolicyRequesterFactory } from "@twin.org/rights-management-models";
 import { DataspaceProtocolContexts, DataspaceProtocolContractNegotiationTypes, DataspaceProtocolEndpointType, DataspaceProtocolHelper, DataspaceProtocolTransferProcessStateType, DataspaceProtocolTransferProcessTypes } from "@twin.org/standards-dataspace-protocol";
+import { MetricHelper } from "@twin.org/telemetry-models";
 import { TrustHelper } from "@twin.org/trust-models";
 import { DataspaceControlPlanePolicyRequester } from "./dataspaceControlPlanePolicyRequester.js";
 import { EndpointProperties } from "./models/endpointProperties.js";
@@ -88,7 +89,7 @@ export class DataspaceControlPlaneService {
     _overrideTrustGeneratorType;
     /**
      * Data plane endpoint path (path only, not full URL).
-     * Will be combined with public origin from hosting component.
+     * Will be combined with public origin.
      * If not configured, PULL transfers are not supported.
      * @internal
      */
@@ -120,6 +121,11 @@ export class DataspaceControlPlaneService {
      * @internal
      */
     _platformComponent;
+    /**
+     * The optional telemetry component for metrics.
+     * @internal
+     */
+    _telemetryComponent;
     /**
      * Registered negotiation callbacks from upstream callers, keyed by registration key.
      * @internal
@@ -169,6 +175,7 @@ export class DataspaceControlPlaneService {
             : undefined;
         this._taskScheduler = ComponentFactory.getIfExists(options?.taskSchedulerComponentType ?? "task-scheduler");
         this._platformComponent = ComponentFactory.getIfExists(options?.platformComponentType ?? "platform");
+        this._telemetryComponent = ComponentFactory.getIfExists(options?.telemetryComponentType);
         // Data plane component is optional and resolved lazily. The control plane is initialised
         // BEFORE the data plane in engine startup order, so `getRegisteredInstanceTypeOptional`
         // returns undefined when the engine constructs us — the wiring override can't fire here.
@@ -235,6 +242,7 @@ export class DataspaceControlPlaneService {
      * @returns A promise that resolves when the federated catalogue is populated and the cleanup task is scheduled.
      */
     async start(nodeLoggingComponentType) {
+        await MetricHelper.createMetrics(this._telemetryComponent, DataspaceControlPlaneMetrics);
         const engine = EngineCoreFactory.getIfExists("engine");
         // Skip if no engine exists OR if this is a clone instance
         if (Is.empty(engine) || engine.isClone()) {
@@ -256,7 +264,7 @@ export class DataspaceControlPlaneService {
         let errorCount = 0;
         let totalDatasets = 0;
         // The platform component execute is used so that the dataset publication runs in the
-        // tenant context of the hosting component, also works in single tenant mode
+        // tenant context, also works in single tenant mode
         await this._platformComponent?.execute(async () => {
             // The tenant context id is set here for each system tenant
             let cursor;
@@ -341,18 +349,16 @@ export class DataspaceControlPlaneService {
      * Request a Transfer Process.
      * Creates a new Transfer Process in REQUESTED state.
      * @param request Transfer request message (DSP compliant).
-     * @param publicOrigin The public origin of this provider node, resolved by the REST route from the
-     * hosting component; used to build the data-plane endpoint when auto-starting.
      * @param options Request options.
      * @param options.autoStart When true, the provider immediately starts the requested transfer (scheduled
      * on the next tick); when omitted/false the provider start must be triggered explicitly.
-     * @param trustPayload Trust payload containing authorization information (Base64-encoded token).
+     * @param trustPayload Trust payload containing authorization information.
      * @returns Transfer Process (DSP compliant) with state REQUESTED, or TransferError if the operation fails.
      *
      * Role Performed: Provider
      * Called by: Consumer when it wants to request a new Transfer Process
      */
-    async requestTransfer(request, publicOrigin, options, trustPayload) {
+    async requestTransfer(request, options, trustPayload) {
         const trustInfo = await TrustHelper.verifyTrust(this._trustComponent, trustPayload, "requestTransfer");
         const validationFailures = await DataspaceProtocolHelper.validate(JsonLdHelper.toNodeObject(request));
         if (Is.arrayValue(validationFailures)) {
@@ -379,14 +385,10 @@ export class DataspaceControlPlaneService {
                     ts: Date.now(),
                     message: "agreementNotFound",
                     data: {
-                        agreementId: request.agreementId,
-                        hint: "Agreement must exist before transfer. Use contract negotiation to create agreement first."
+                        notFoundId: request.agreementId
                     }
                 });
-                throw new NotFoundError(DataspaceControlPlaneService.CLASS_NAME, "agreementNotFound", request.agreementId, {
-                    agreementId: request.agreementId,
-                    hint: "Perform contract negotiation first to create an agreement"
-                });
+                throw new NotFoundError(DataspaceControlPlaneService.CLASS_NAME, "agreementNotFound", request.agreementId);
             }
             const assigneeIdentity = OdrlPolicyHelper.extractAssigneeIdentity(agreement);
             const assigneeIds = ArrayHelper.fromObjectOrArray(assigneeIdentity);
@@ -448,12 +450,14 @@ export class DataspaceControlPlaneService {
         // setTimeout follow-up). The timer runs inside the request's ALS context, so the [Node, Tenant] + org
         // partition propagates to the deferred start.
         if (options?.autoStart) {
+            const contextIds = await ContextIdStore.getContextIds();
             const consumerPid = request.consumerPid;
             setTimeout(async () => {
                 // runProviderStart catches internally and can't reject; awaiting satisfies no-floating-promises.
-                await this.runProviderStart(consumerPid, publicOrigin);
+                await this.runProviderStart(consumerPid, contextIds?.[HttpContextIdKeys.PublicOrigin]);
             }, 0);
         }
+        await MetricHelper.metricIncrement(this._telemetryComponent, DataspaceControlPlaneMetricIds.TransfersRequested);
         return {
             "@context": [DataspaceProtocolContexts.Context],
             "@type": DataspaceProtocolTransferProcessTypes.TransferProcess,
@@ -468,7 +472,6 @@ export class DataspaceControlPlaneService {
      * and (only if the provider accepts) persists a local TransferProcess in REQUESTED state.
      * @param agreementId The finalized agreement ID from contract negotiation.
      * @param providerEndpoint The provider's DSP control plane base URL.
-     * @param publicOrigin The public origin URL of this control plane (used as callbackAddress).
      * @param format The transfer format (e.g. "HttpData-PULL", "HttpData-PUSH").
      * @param trustPayload Trust payload for authenticating this call.
      * @returns The consumerPid of the newly created TransferProcess.
@@ -481,11 +484,13 @@ export class DataspaceControlPlaneService {
      * registration ignores the runtime `endpoint` arg and silently POSTs to its
      * static endpoint instead.
      */
-    async prepareTransfer(agreementId, providerEndpoint, publicOrigin, format, trustPayload) {
+    async prepareTransfer(agreementId, providerEndpoint, format, trustPayload) {
         Guards.stringValue(DataspaceControlPlaneService.CLASS_NAME, "agreementId", agreementId);
         Guards.stringValue(DataspaceControlPlaneService.CLASS_NAME, "providerEndpoint", providerEndpoint);
-        Guards.stringValue(DataspaceControlPlaneService.CLASS_NAME, "publicOrigin", publicOrigin);
         Guards.stringValue(DataspaceControlPlaneService.CLASS_NAME, "format", format);
+        const contextIds = await ContextIdStore.getContextIds();
+        ContextIdHelper.guard(contextIds, HttpContextIdKeys.PublicOrigin);
+        const publicOrigin = contextIds[HttpContextIdKeys.PublicOrigin];
         if (!Object.values(DataspaceTransferFormat).includes(format)) {
             throw new GeneralError(DataspaceControlPlaneService.CLASS_NAME, "unsupportedTransferFormat", {
                 format,
@@ -555,7 +560,7 @@ export class DataspaceControlPlaneService {
         const outboundToken = await this._trustComponent.generate(organizationIdentity, this._overrideTrustGeneratorType, { subject: { consumerPid, agreementId } });
         // Create a remote REST client pointed at the provider endpoint and call requestTransfer.
         const remoteControlPlane = ComponentFactory.create(this._remoteControlPlaneComponentType, { endpoint: providerEndpoint, pathPrefix: "" });
-        const result = await remoteControlPlane.requestTransfer(transferRequestMessage, "", undefined, outboundToken);
+        const result = await remoteControlPlane.requestTransfer(transferRequestMessage, undefined, outboundToken);
         if (getJsonLdType(result) === DataspaceProtocolTransferProcessTypes.TransferError) {
             const transferError = result;
             throw new GeneralError(DataspaceControlPlaneService.CLASS_NAME, "transferRequestRejectedByProvider", {
@@ -601,6 +606,7 @@ export class DataspaceControlPlaneService {
                 format
             }
         });
+        await MetricHelper.metricIncrement(this._telemetryComponent, DataspaceControlPlaneMetricIds.TransfersPrepared);
         return { consumerPid };
     }
     // ----------------------------------------------------------------------------
@@ -610,14 +616,15 @@ export class DataspaceControlPlaneService {
      * Start a Transfer Process.
      * Transitions Transfer Process from REQUESTED to STARTED state or resumes from SUSPENDED state.
      * @param message Transfer start message (DSP compliant).
-     * @param publicOrigin The public origin URL of this service.
-     * @param trustPayload Trust payload containing authorization information (Base64-encoded token).
+     * @param trustPayload Trust payload containing authorization information.
      * @returns Transfer Start Message (DSP compliant) with dataAddress for PULL transfers, or TransferError if the operation fails.
      *
      * Role Performed: Provider / Consumer
      */
-    async startTransfer(message, publicOrigin, trustPayload) {
-        publicOrigin = StringHelper.trimTrailingSlashes(publicOrigin);
+    async startTransfer(message, trustPayload) {
+        const contextIds = await ContextIdStore.getContextIds();
+        ContextIdHelper.guard(contextIds, HttpContextIdKeys.PublicOrigin);
+        const publicOrigin = contextIds[HttpContextIdKeys.PublicOrigin];
         const trustInfo = await TrustHelper.verifyTrust(this._trustComponent, trustPayload, "startTransfer");
         const validationFailures = await DataspaceProtocolHelper.validate(JsonLdHelper.toNodeObject(message));
         if (Is.arrayValue(validationFailures)) {
@@ -667,6 +674,7 @@ export class DataspaceControlPlaneService {
                 });
                 await this._internalTransferCallback.onStateChanged(entity.consumerPid, DataspaceProtocolTransferProcessStateType.STARTED);
                 await this._internalTransferCallback.onStarted(entity.consumerPid, message);
+                await MetricHelper.metricIncrement(this._telemetryComponent, DataspaceControlPlaneMetricIds.TransfersStarted);
                 return message;
             }
             // PROVIDER-ACT (role === Provider): build the dataAddress, transition to STARTED, deliver below.
@@ -888,7 +896,8 @@ export class DataspaceControlPlaneService {
             });
             // Notify the consumer by POSTing the TransferStart (with its dataAddress) to the callback.
             // Best-effort: a delivery failure must not roll back the STARTED transition.
-            await this.deliverToConsumerCallback(entity, "start", async (remoteControlPlane, token) => remoteControlPlane.startTransfer(response, "", token));
+            await this.deliverToConsumerCallback(entity, "start", async (remoteControlPlane, token) => remoteControlPlane.startTransfer(response, token));
+            await MetricHelper.metricIncrement(this._telemetryComponent, DataspaceControlPlaneMetricIds.TransfersStarted);
             return response;
         }
         catch (error) {
@@ -904,16 +913,14 @@ export class DataspaceControlPlaneService {
      * the provider, builds the dataAddress for PULL, persists STARTED, and delivers to the consumer).
      * This is the provider-side mirror of prepareTransfer.
      * @param pid The Process ID (consumerPid or providerPid) identifying the transfer to start.
-     * @param publicOrigin The public origin URL of this provider node (used to build the data plane endpoint for PULL transfers).
      * @param trustPayload Trust payload proving the caller is the provider.
      * @returns Transfer Start Message (DSP compliant) with dataAddress for PULL transfers, or TransferError if the operation fails.
      */
-    async transferStarted(pid, publicOrigin, trustPayload) {
+    async transferStarted(pid, trustPayload) {
         let consumerPid;
         let providerPid;
         try {
             Guards.stringValue(DataspaceControlPlaneService.CLASS_NAME, "pid", pid);
-            Guards.stringValue(DataspaceControlPlaneService.CLASS_NAME, "publicOrigin", publicOrigin);
             const { entity, role } = await this.lookupTransferByPid(pid);
             consumerPid = entity.consumerPid;
             providerPid = entity.providerPid;
@@ -934,7 +941,7 @@ export class DataspaceControlPlaneService {
             // startTransfer verifies trustPayload is the provider, checks org ownership, applies the
             // REQUESTED|SUSPENDED state guard, builds the dataAddress, persists STARTED, and delivers the
             // TransferStartMessage to the consumer callback.
-            return await this.startTransfer(startMessage, publicOrigin, trustPayload);
+            return await this.startTransfer(startMessage, trustPayload);
         }
         catch (error) {
             return transformToTransferError(error, { consumerPid, providerPid });
@@ -946,7 +953,7 @@ export class DataspaceControlPlaneService {
     /**
      * Complete a Transfer Process.
      * @param message Transfer completion message (DSP compliant).
-     * @param trustPayload Trust payload containing authorization information (Base64-encoded token).
+     * @param trustPayload Trust payload containing authorization information.
      * @returns Transfer Process (DSP compliant) with state COMPLETED, or TransferError if the operation fails.
      */
     async completeTransfer(message, trustPayload) {
@@ -1026,6 +1033,7 @@ export class DataspaceControlPlaneService {
                 await this._internalTransferCallback.onStateChanged(entity.consumerPid, DataspaceProtocolTransferProcessStateType.COMPLETED);
                 await this._internalTransferCallback.onCompleted(entity.consumerPid);
             }
+            await MetricHelper.metricIncrement(this._telemetryComponent, DataspaceControlPlaneMetricIds.TransfersCompleted);
             return {
                 "@context": [DataspaceProtocolContexts.Context],
                 "@type": DataspaceProtocolTransferProcessTypes.TransferProcess,
@@ -1041,7 +1049,7 @@ export class DataspaceControlPlaneService {
     /**
      * Suspend a Transfer Process.
      * @param message Transfer suspension message (DSP compliant).
-     * @param trustPayload Trust payload containing authorization information (Base64-encoded token).
+     * @param trustPayload Trust payload containing authorization information.
      * @returns Transfer Process (DSP compliant) with state SUSPENDED, or TransferError if the operation fails.
      */
     async suspendTransfer(message, trustPayload) {
@@ -1128,6 +1136,7 @@ export class DataspaceControlPlaneService {
                 // PROVIDER-ACT: forward the suspension (with its reason) to the consumer callback.
                 await this.deliverToConsumerCallback(entity, "suspension", async (remoteControlPlane, token) => remoteControlPlane.suspendTransfer(message, token));
             }
+            await MetricHelper.metricIncrement(this._telemetryComponent, DataspaceControlPlaneMetricIds.TransfersSuspended);
             return {
                 "@context": [DataspaceProtocolContexts.Context],
                 "@type": DataspaceProtocolTransferProcessTypes.TransferProcess,
@@ -1143,7 +1152,7 @@ export class DataspaceControlPlaneService {
     /**
      * Terminate a Transfer Process.
      * @param message Transfer termination message (DSP compliant).
-     * @param trustPayload Trust payload containing authorization information (Base64-encoded token).
+     * @param trustPayload Trust payload containing authorization information.
      * @returns Transfer Process (DSP compliant) with state TERMINATED, or TransferError if the operation fails.
      */
     async terminateTransfer(message, trustPayload) {
@@ -1224,6 +1233,7 @@ export class DataspaceControlPlaneService {
                 // PROVIDER-ACT: forward the termination (with its reason) to the consumer callback.
                 await this.deliverToConsumerCallback(entity, "termination", async (remoteControlPlane, token) => remoteControlPlane.terminateTransfer(message, token));
             }
+            await MetricHelper.metricIncrement(this._telemetryComponent, DataspaceControlPlaneMetricIds.TransfersTerminated);
             return {
                 "@context": [DataspaceProtocolContexts.Context],
                 "@type": DataspaceProtocolTransferProcessTypes.TransferProcess,
@@ -1239,7 +1249,7 @@ export class DataspaceControlPlaneService {
     /**
      * Get Transfer Process state.
      * @param pid Process ID (consumerPid or providerPid).
-     * @param trustPayload Trust payload containing authorization information (Base64-encoded token).
+     * @param trustPayload Trust payload containing authorization information.
      * @returns Transfer Process (DSP compliant) with current state, or TransferError if the operation fails.
      */
     async getTransferProcess(pid, trustPayload) {
@@ -1284,15 +1294,16 @@ export class DataspaceControlPlaneService {
      * @param datasetId The dataset ID from the provider's catalog.
      * @param offerId The offer ID from the provider's catalog.
      * @param providerEndpoint The provider's contract negotiation endpoint URL.
-     * @param publicOrigin The public origin URL of this control plane (for callbacks).
      * @param trustPayload The trust payload for authentication.
      * @returns The negotiation ID. Use the registered callback for completion notification.
      */
-    async negotiateAgreement(datasetId, offerId, providerEndpoint, publicOrigin, trustPayload) {
+    async negotiateAgreement(datasetId, offerId, providerEndpoint, trustPayload) {
         Guards.stringValue(DataspaceControlPlaneService.CLASS_NAME, "datasetId", datasetId);
         Guards.stringValue(DataspaceControlPlaneService.CLASS_NAME, "offerId", offerId);
         Guards.stringValue(DataspaceControlPlaneService.CLASS_NAME, "providerEndpoint", providerEndpoint);
-        Guards.stringValue(DataspaceControlPlaneService.CLASS_NAME, "publicOrigin", publicOrigin);
+        const contextIds = await ContextIdStore.getContextIds();
+        ContextIdHelper.guard(contextIds, HttpContextIdKeys.PublicOrigin);
+        const publicOrigin = contextIds[HttpContextIdKeys.PublicOrigin];
         const trustInfo = await TrustHelper.verifyTrust(this._trustComponent, trustPayload, "negotiateAgreement");
         await this._loggingComponent?.log({
             level: "info",
@@ -1372,6 +1383,7 @@ export class DataspaceControlPlaneService {
             });
         }
         this._policyRequester.trackNegotiation(negotiationId);
+        await MetricHelper.metricIncrement(this._telemetryComponent, DataspaceControlPlaneMetricIds.NegotiationsInitiated);
         await this._loggingComponent?.log({
             level: "info",
             source: DataspaceControlPlaneService.CLASS_NAME,
@@ -1464,7 +1476,7 @@ export class DataspaceControlPlaneService {
     /**
      * Resolve consumerPid to Transfer Context.
      * @param consumerPid Consumer Process ID.
-     * @param trustPayload Trust payload containing authorization information (Base64-encoded token).
+     * @param trustPayload Trust payload containing authorization information.
      * @returns Transfer Context with Agreement, datasetId, and Transfer Process metadata.
      */
     async resolveConsumerPid(consumerPid, trustPayload) {
@@ -1521,7 +1533,7 @@ export class DataspaceControlPlaneService {
     /**
      * Resolve providerPid to Transfer Context.
      * @param providerPid Provider Process ID.
-     * @param trustPayload Trust payload containing authorization information (Base64-encoded token).
+     * @param trustPayload Trust payload containing authorization information.
      * @returns Transfer Context with Agreement, datasetId, and Transfer Process metadata.
      */
     async resolveProviderPid(providerPid, trustPayload) {
@@ -1631,6 +1643,7 @@ export class DataspaceControlPlaneService {
         // Side effect first, primary storage last
         await this.publishAppDataset(entity);
         await this._dataspaceAppDatasetStorage.set(entity);
+        await MetricHelper.metricIncrement(this._telemetryComponent, DataspaceControlPlaneMetricIds.AppDatasetsCreated);
         return resolvedId;
     }
     /**
@@ -1709,6 +1722,7 @@ export class DataspaceControlPlaneService {
         // Side effect first, primary storage last
         await this.publishAppDataset(updated);
         await this._dataspaceAppDatasetStorage.set(updated);
+        await MetricHelper.metricIncrement(this._telemetryComponent, DataspaceControlPlaneMetricIds.AppDatasetsUpdated);
     }
     /**
      * Delete a dataspace app dataset owned by the calling organization.
@@ -1735,6 +1749,7 @@ export class DataspaceControlPlaneService {
             });
         }
         await this._dataspaceAppDatasetStorage.remove(id);
+        await MetricHelper.metricIncrement(this._telemetryComponent, DataspaceControlPlaneMetricIds.AppDatasetsDeleted);
     }
     // ============================================================================
     // PRIVATE HELPER METHODS
@@ -1829,7 +1844,7 @@ export class DataspaceControlPlaneService {
                     agreementId: entity.agreementId
                 }
             });
-            const result = await this.transferStarted(consumerPid, publicOrigin, selfToken);
+            const result = await this.transferStarted(consumerPid, selfToken);
             if (getJsonLdType(result) === DataspaceProtocolTransferProcessTypes.TransferError) {
                 await this._loggingComponent?.log({
                     level: "error",
@@ -2438,12 +2453,8 @@ export class DataspaceControlPlaneService {
         const contextIds = await ContextIdStore.getContextIds();
         const tenantContextIds = { ...contextIds, [ContextIdKeys.Tenant]: appDataset.tenantId };
         await ContextIdStore.run(tenantContextIds, async () => {
-            const app = DataspaceAppFactory.get(appDataset.appId);
             const datasetPayload = this.restampDatasetId(appDataset.dataset, appDataset.id);
-            const overrideHandler = app.datasetsHandled?.bind(app);
-            const rawDatasets = overrideHandler
-                ? await overrideHandler(datasetPayload)
-                : [datasetPayload];
+            const rawDatasets = [datasetPayload];
             const datasets = await Promise.all(rawDatasets.map(async (d) => this.populateDefaults(d)));
             for (const dataset of datasets) {
                 const publishResult = await this._federatedCatalogueComponent.set(dataset, localTrustPayload);