@twin.org/dataspace-control-plane-service 0.0.3-next.33 → 0.0.3-next.35

package/dist/es/dataspaceControlPlaneService.js

@@ -120,6 +120,22 @@ export class DataspaceControlPlaneService {
      * @internal
      */
     _negotiationCallbacks;
+    /**
+     * Registered transfer callbacks from upstream callers, keyed by registration key.
+     * @internal
+     */
+    _transferCallbacks;
+    /**
+     * Internal transfer callback that fans out to all registered transfer callbacks.
+     * @internal
+     */
+    _internalTransferCallback;
+    /**
+     * Factory key used to create remote control plane REST client instances for outbound
+     * DSP transfer requests. Resolved via ComponentFactory.create() at call time.
+     * @internal
+     */
+    _remoteControlPlaneComponentType;
     /**
      * The component type name for the hosting component.
      * @internal
@@ -159,6 +175,10 @@ export class DataspaceControlPlaneService {
             options?.dataPlaneComponentType ?? "dataspace-data-plane-service";
         this._urlTransformerComponent = ComponentFactory.get(options?.urlTransformerComponentType ?? "url-transformer");
         this._negotiationCallbacks = new Map();
+        this._transferCallbacks = new Map();
+        this._internalTransferCallback = this.createInternalTransferCallback();
+        this._remoteControlPlaneComponentType =
+            options?.remoteControlPlaneComponentType ?? "dataspace-control-plane-rest-client";
         const internalCallback = this.createInternalCallback();
         this._policyRequester = new DataspaceControlPlanePolicyRequester(options?.loggingComponentType ?? "logging", internalCallback);
         PolicyRequesterFactory.register(DataspaceControlPlaneService._REQUESTER_TYPE, () => this._policyRequester);
@@ -188,6 +208,24 @@ export class DataspaceControlPlaneService {
         Guards.stringValue(DataspaceControlPlaneService.CLASS_NAME, "key", key);
         this._negotiationCallbacks.delete(key);
     }
+    /**
+     * Register a callback to receive transfer process state change notifications.
+     * @param key A unique key identifying this callback registration.
+     * @param callback The callback interface to register.
+     */
+    registerTransferCallback(key, callback) {
+        Guards.stringValue(DataspaceControlPlaneService.CLASS_NAME, "key", key);
+        Guards.object(DataspaceControlPlaneService.CLASS_NAME, "callback", callback);
+        this._transferCallbacks.set(key, callback);
+    }
+    /**
+     * Unregister a previously registered transfer callback.
+     * @param key The key used when registering the callback.
+     */
+    unregisterTransferCallback(key) {
+        Guards.stringValue(DataspaceControlPlaneService.CLASS_NAME, "key", key);
+        this._transferCallbacks.delete(key);
+    }
     /**
      * The service needs to be started when the application is initialized.
      * Populates the Federated Catalogue with datasets from registered apps
@@ -406,6 +444,142 @@ export class DataspaceControlPlaneService {
             state: entity.state
         };
     }
+    /**
+     * Start a data transfer as a Consumer.
+     * Generates a consumerPid, POSTs a TransferRequestMessage to the provider's DSP endpoint,
+     * 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.
+     *
+     * **Engine configuration requirement:** The outbound call to the provider uses
+     * `ComponentFactory.create(remoteControlPlaneComponentType, { endpoint, pathPrefix })`.
+     * For the runtime `providerEndpoint` to be forwarded correctly, the engine **must** register
+     * the component type (default: `dataspace-control-plane-rest-client`) as a
+     * **multi-instance** component (`isMultiInstance: true` in engine config). A singleton
+     * registration ignores the runtime `endpoint` arg and silently POSTs to its
+     * static endpoint instead.
+     */
+    async startDataTransfer(agreementId, providerEndpoint, publicOrigin, 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);
+        if (!Object.values(DataspaceTransferFormat).includes(format)) {
+            throw new GeneralError(DataspaceControlPlaneService.CLASS_NAME, "unsupportedTransferFormat", {
+                format,
+                supported: Object.values(DataspaceTransferFormat)
+            });
+        }
+        const trustInfo = await TrustHelper.verifyTrust(this._trustComponent, trustPayload, "startDataTransfer");
+        await this._loggingComponent?.log({
+            level: "info",
+            source: DataspaceControlPlaneService.CLASS_NAME,
+            ts: Date.now(),
+            message: "startingDataTransfer",
+            data: { agreementId, providerEndpoint, format, identity: trustInfo.identity }
+        });
+        const agreement = await this.lookupAgreement(agreementId);
+        const assigneeIdentity = OdrlPolicyHelper.extractAssigneeIdentity(agreement);
+        const assigneeIds = ArrayHelper.fromObjectOrArray(assigneeIdentity);
+        const callerComposite = this.buildCallerComposite(trustInfo);
+        if (!assigneeIds.includes(callerComposite)) {
+            throw new UnauthorizedError(DataspaceControlPlaneService.CLASS_NAME, "callerNotAuthorizedForAgreement");
+        }
+        const assignerIdentity = OdrlPolicyHelper.extractAssignerIdentity(agreement);
+        const assignerIds = ArrayHelper.fromObjectOrArray(assignerIdentity);
+        if (assignerIds.length > 1) {
+            throw new GeneralError(DataspaceControlPlaneService.CLASS_NAME, "multipleAssignersNotSupported");
+        }
+        const providerIdentity = assignerIds[0];
+        const datasetId = this.extractDatasetId(agreement);
+        const consumerPid = `urn:uuid:${RandomHelper.generateUuidV7()}`;
+        const callbackAddress = StringHelper.trimTrailingSlashes(publicOrigin);
+        // Fetch context once and reuse across the PUSH dataAddress, trust token, and storage entity.
+        const contextIds = await ContextIdStore.getContextIds();
+        const nodeIdentity = contextIds?.[ContextIdKeys.Node];
+        Guards.stringValue(DataspaceControlPlaneService.CLASS_NAME, "nodeIdentity", nodeIdentity);
+        const tenantId = contextIds?.[ContextIdKeys.Tenant];
+        const organizationIdentity = contextIds?.[ContextIdKeys.Organization];
+        const transferRequestMessage = {
+            "@context": [DataspaceProtocolContexts.Context],
+            "@type": DataspaceProtocolTransferProcessTypes.TransferRequestMessage,
+            consumerPid,
+            agreementId,
+            callbackAddress,
+            format
+        };
+        // For consumer-initiated PUSH transfers the consumer must supply its /inbox endpoint as
+        // dataAddress so the provider knows where to push ActivityStreams objects. Without it the
+        // provider silently falls through to PULL mode on startTransfer.
+        if (format === DataspaceTransferFormat.HttpDataPush) {
+            if (!Is.stringValue(this._dataPlanePath)) {
+                throw new GeneralError(DataspaceControlPlaneService.CLASS_NAME, "pushTransferDataPathNotConfigured", { consumerPid });
+            }
+            let inboxEndpoint = `${callbackAddress}/${this._dataPlanePath}/inbox`;
+            if (Is.stringValue(tenantId)) {
+                inboxEndpoint = await this._urlTransformerComponent.addEncryptedQueryParamToUrl(inboxEndpoint, "tenant", tenantId);
+            }
+            transferRequestMessage.dataAddress = {
+                "@type": DataspaceProtocolTransferProcessTypes.DataAddress,
+                endpointType: DataspaceProtocolEndpointType.HttpsActivityStreamEndpoint,
+                endpoint: inboxEndpoint
+            };
+        }
+        // Generate outbound trust token to authenticate this node to the provider.
+        const outboundToken = await this._trustComponent.generate(nodeIdentity, this._overrideTrustGeneratorType, { subject: { consumerPid, agreementId } }, Is.stringValue(tenantId) ? TrustHelper.hashTenantId(tenantId) : undefined, organizationIdentity);
+        // 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, outboundToken);
+        if (getJsonLdType(result) === DataspaceProtocolTransferProcessTypes.TransferError) {
+            const transferError = result;
+            throw new GeneralError(DataspaceControlPlaneService.CLASS_NAME, "transferRequestRejectedByProvider", {
+                agreementId,
+                providerEndpoint,
+                code: transferError.code
+            });
+        }
+        const transferProcess = result;
+        if (!Is.stringValue(transferProcess.providerPid)) {
+            throw new GeneralError(DataspaceControlPlaneService.CLASS_NAME, "providerPidMissingInResponse", { consumerPid });
+        }
+        const now = new Date();
+        const storageEntity = {
+            id: Converter.bytesToHex(RandomHelper.generate(32)),
+            consumerPid,
+            providerPid: transferProcess.providerPid,
+            state: DataspaceProtocolTransferProcessStateType.REQUESTED,
+            agreementId,
+            datasetId,
+            consumerIdentity: callerComposite,
+            providerIdentity,
+            offerId: agreementId,
+            policies: [agreement],
+            callbackAddress,
+            format,
+            dataAddress: transferRequestMessage.dataAddress,
+            tenantId: Is.stringValue(tenantId) ? tenantId : undefined,
+            dateCreated: now.toISOString(),
+            dateModified: now.toISOString()
+        };
+        await this._transferProcessStorage.set(storageEntity);
+        await this._loggingComponent?.log({
+            level: "info",
+            source: DataspaceControlPlaneService.CLASS_NAME,
+            ts: Date.now(),
+            message: "dataTransferStarted",
+            data: {
+                consumerPid,
+                providerPid: storageEntity.providerPid,
+                agreementId,
+                format
+            }
+        });
+        return { consumerPid };
+    }
     // ----------------------------------------------------------------------------
     // PROVIDER SIDE OPERATIONS
     // ----------------------------------------------------------------------------
@@ -492,10 +666,10 @@ export class DataspaceControlPlaneService {
             //
             // See: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1-err1/#transfer-start-message
             // ============================================================================
-            if (Is.empty(entity.dataAddress) && entity.format === DataspaceTransferFormat.HttpProxyPost) {
+            if (Is.empty(entity.dataAddress) && entity.format === DataspaceTransferFormat.HttpDataPost) {
                 // PROVIDER-INITIATED PUSH: Consumer requested push but did not supply an /inbox.
                 // Provider returns its own /inbox URL + a signed JWT so the consumer can verify
-                // the incoming activities (HttpProxy-POST / DataspaceTransferFormat.HttpProxyPost).
+                // the incoming activities (HttpData-POST / DataspaceTransferFormat.HttpDataPost).
                 if (!Is.stringValue(this._dataPlanePath)) {
                     return transformToTransferError(new GeneralError(DataspaceControlPlaneService.CLASS_NAME, "pushTransferDataPathNotConfigured", { consumerPid: entity.consumerPid }), message);
                 }
@@ -549,7 +723,7 @@ export class DataspaceControlPlaneService {
                         consumerPid: entity.consumerPid,
                         providerPid: entity.providerPid,
                         endpoint: fullEndpoint,
-                        transferMode: DataspaceTransferFormat.HttpProxyPost
+                        transferMode: DataspaceTransferFormat.HttpDataPost
                     }
                 });
             }
@@ -651,7 +825,7 @@ export class DataspaceControlPlaneService {
                         consumerPid: entity.consumerPid,
                         providerPid: entity.providerPid,
                         endpoint: fullEndpoint,
-                        transferMode: DataspaceTransferFormat.HttpProxyPush
+                        transferMode: DataspaceTransferFormat.HttpDataPush
                     }
                 });
                 try {
@@ -670,6 +844,10 @@ export class DataspaceControlPlaneService {
                     throw setupError;
                 }
             }
+            if (role === TransferProcessRole.Consumer) {
+                await this._internalTransferCallback.onStateChanged(entity.consumerPid, DataspaceProtocolTransferProcessStateType.STARTED);
+                await this._internalTransferCallback.onStarted(entity.consumerPid, response);
+            }
             return response;
         }
         catch (error) {
@@ -757,6 +935,10 @@ export class DataspaceControlPlaneService {
                     throw teardownError;
                 }
             }
+            if (role === TransferProcessRole.Consumer) {
+                await this._internalTransferCallback.onStateChanged(entity.consumerPid, DataspaceProtocolTransferProcessStateType.COMPLETED);
+                await this._internalTransferCallback.onCompleted(entity.consumerPid);
+            }
             return {
                 "@context": [DataspaceProtocolContexts.Context],
                 "@type": DataspaceProtocolTransferProcessTypes.TransferProcess,
@@ -846,6 +1028,15 @@ export class DataspaceControlPlaneService {
                     throw suspendError;
                 }
             }
+            if (role === TransferProcessRole.Consumer) {
+                await this._internalTransferCallback.onStateChanged(entity.consumerPid, DataspaceProtocolTransferProcessStateType.SUSPENDED);
+                // DSP reason is typed any[] — forward only the first entry since the callback
+                // contract is reason?: string. Additional entries are intentionally dropped.
+                const suspendReason = Array.isArray(message.reason)
+                    ? message.reason[0]
+                    : message.reason;
+                await this._internalTransferCallback.onSuspended(entity.consumerPid, suspendReason);
+            }
             return {
                 "@context": [DataspaceProtocolContexts.Context],
                 "@type": DataspaceProtocolTransferProcessTypes.TransferProcess,
@@ -929,6 +1120,15 @@ export class DataspaceControlPlaneService {
                     throw teardownError;
                 }
             }
+            if (role === TransferProcessRole.Consumer) {
+                await this._internalTransferCallback.onStateChanged(entity.consumerPid, DataspaceProtocolTransferProcessStateType.TERMINATED);
+                // DSP reason is typed any[] — forward only the first entry since the callback
+                // contract is reason?: string. Additional entries are intentionally dropped.
+                const terminateReason = Array.isArray(message.reason)
+                    ? message.reason[0]
+                    : message.reason;
+                await this._internalTransferCallback.onTerminated(entity.consumerPid, terminateReason);
+            }
             return {
                 "@context": [DataspaceProtocolContexts.Context],
                 "@type": DataspaceProtocolTransferProcessTypes.TransferProcess,
@@ -1632,8 +1832,8 @@ export class DataspaceControlPlaneService {
      * @internal
      */
     isPushFormat(format) {
-        return (format === DataspaceTransferFormat.HttpProxyPush ||
-            format === DataspaceTransferFormat.HttpProxyPost);
+        return (format === DataspaceTransferFormat.HttpDataPush ||
+            format === DataspaceTransferFormat.HttpDataPost);
     }
     /**
      * Extract the dataset ID from an ODRL agreement's target.
@@ -1996,6 +2196,101 @@ export class DataspaceControlPlaneService {
             }
         };
     }
+    /**
+     * Creates the internal ITransferCallback that fans out to all registered transfer callbacks.
+     * Errors thrown by individual callbacks are logged and swallowed so they cannot affect
+     * the DSP protocol state machine or other registrants.
+     * @returns The internal transfer callback.
+     */
+    createInternalTransferCallback() {
+        return {
+            onStateChanged: async (consumerPid, state) => {
+                for (const [key, cb] of this._transferCallbacks.entries()) {
+                    try {
+                        await cb.onStateChanged(consumerPid, state);
+                    }
+                    catch (error) {
+                        await this._loggingComponent?.log({
+                            level: "error",
+                            source: DataspaceControlPlaneService.CLASS_NAME,
+                            ts: Date.now(),
+                            message: "transferCallbackError",
+                            error: BaseError.fromError(error),
+                            data: { key, consumerPid, state, method: "onStateChanged" }
+                        });
+                    }
+                }
+            },
+            onStarted: async (consumerPid, message) => {
+                for (const [key, cb] of this._transferCallbacks.entries()) {
+                    try {
+                        await cb.onStarted(consumerPid, message);
+                    }
+                    catch (error) {
+                        await this._loggingComponent?.log({
+                            level: "error",
+                            source: DataspaceControlPlaneService.CLASS_NAME,
+                            ts: Date.now(),
+                            message: "transferCallbackError",
+                            error: BaseError.fromError(error),
+                            data: { key, consumerPid, method: "onStarted" }
+                        });
+                    }
+                }
+            },
+            onCompleted: async (consumerPid) => {
+                for (const [key, cb] of this._transferCallbacks.entries()) {
+                    try {
+                        await cb.onCompleted(consumerPid);
+                    }
+                    catch (error) {
+                        await this._loggingComponent?.log({
+                            level: "error",
+                            source: DataspaceControlPlaneService.CLASS_NAME,
+                            ts: Date.now(),
+                            message: "transferCallbackError",
+                            error: BaseError.fromError(error),
+                            data: { key, consumerPid, method: "onCompleted" }
+                        });
+                    }
+                }
+            },
+            onSuspended: async (consumerPid, reason) => {
+                for (const [key, cb] of this._transferCallbacks.entries()) {
+                    try {
+                        await cb.onSuspended(consumerPid, reason);
+                    }
+                    catch (error) {
+                        await this._loggingComponent?.log({
+                            level: "error",
+                            source: DataspaceControlPlaneService.CLASS_NAME,
+                            ts: Date.now(),
+                            message: "transferCallbackError",
+                            error: BaseError.fromError(error),
+                            data: { key, consumerPid, method: "onSuspended" }
+                        });
+                    }
+                }
+            },
+            onTerminated: async (consumerPid, reason) => {
+                for (const [key, cb] of this._transferCallbacks.entries()) {
+                    try {
+                        await cb.onTerminated(consumerPid, reason);
+                    }
+                    catch (error) {
+                        await this._loggingComponent?.log({
+                            level: "error",
+                            source: DataspaceControlPlaneService.CLASS_NAME,
+                            ts: Date.now(),
+                            message: "transferCallbackError",
+                            error: BaseError.fromError(error),
+                            data: { key, consumerPid, method: "onTerminated" }
+                        });
+                    }
+                }
+            }
+        };
+    }
     /**
      * Re-stamp `@id` onto a stored payload blob using the entity primary key.
      * @param payload The stored payload blob (without `@id`).