@twin.org/dataspace-control-plane-service 0.9.0 → 0.9.1-next.10

package/docs/reference/index.md

@@ -4,12 +4,18 @@
 
 - [DataspaceControlPlanePolicyRequester](classes/DataspaceControlPlanePolicyRequester.md)
 - [DataspaceControlPlaneService](classes/DataspaceControlPlaneService.md)
+- [HttpDataPostTransferHandler](classes/HttpDataPostTransferHandler.md)
+- [HttpDataPullTransferHandler](classes/HttpDataPullTransferHandler.md)
+- [HttpDataPushTransferHandler](classes/HttpDataPushTransferHandler.md)
 
 ## Interfaces
 
 - [IDataspaceControlPlaneServiceConfig](interfaces/IDataspaceControlPlaneServiceConfig.md)
 - [IDataspaceControlPlaneServiceConstructorOptions](interfaces/IDataspaceControlPlaneServiceConstructorOptions.md)
 - [INegotiationState](interfaces/INegotiationState.md)
+- [ITransferHandler](interfaces/ITransferHandler.md)
+- [ITransferHandlerPrepareContext](interfaces/ITransferHandlerPrepareContext.md)
+- [ITransferHandlerStartContext](interfaces/ITransferHandlerStartContext.md)
 
 ## Type Aliases
 
@@ -18,6 +24,7 @@
 ## Variables
 
 - [tagsDataspaceControlPlane](variables/tagsDataspaceControlPlane.md)
+- [TransferHandlerFactory](variables/TransferHandlerFactory.md)
 - [EndpointProperties](variables/EndpointProperties.md)
 - [restEntryPoints](variables/restEntryPoints.md)
 

package/docs/reference/interfaces/IDataspaceControlPlaneServiceConfig.md

@@ -17,13 +17,18 @@ If not specified, the default trust generator configured in the trust component
 
 > `optional` **dataPlanePath?**: `string`
 
-Data plane endpoint path for PULL transfers (path only, not full URL).
-Will be combined with the public origin.
+Base route path for the data plane service (path only, not full URL).
+Combined with the public origin to form the `dataAddress.endpoint` sent to PULL consumers
+and the inbox URL sent to PUSH providers.
 
-REQUIRED if PULL transfers are supported.
-If not specified, PULL transfers will not be available.
+This must be the mount-point prefix of the data plane routes, NOT a specific route path.
+Do NOT append sub-paths such as `/entities` or `/inbox` — those are appended automatically
+by each transfer handler and by the data plane REST client.
 
-Example: "data-plane/data" or "api/data-plane/data"
+REQUIRED if PULL or PUSH transfers are supported.
+If not specified, PULL and PUSH transfers will not be available.
+
+Example: "dataspace"
 
 ***
 

package/docs/reference/interfaces/ITransferHandler.md

@@ -0,0 +1,180 @@
+# Interface: ITransferHandler
+
+Format-specific handler for transfer process operations.
+One implementation exists per DataspaceTransferFormat value; the TransferHandlerFactory
+returns the correct instance keyed on the format string.
+
+## Extends
+
+- `IComponent`
+
+## Methods
+
+### buildConsumerDataAddress() {#buildconsumerdataaddress}
+
+> **buildConsumerDataAddress**(`ctx`): `IDataspaceProtocolDataAddress` \| `undefined`
+
+Optionally build a consumer dataAddress for the TransferRequestMessage.
+Called during prepareTransfer. Returns undefined for formats that do not
+require a consumer-supplied dataAddress (PULL and POST).
+
+#### Parameters
+
+##### ctx
+
+[`ITransferHandlerPrepareContext`](ITransferHandlerPrepareContext.md)
+
+The prepare context.
+
+#### Returns
+
+`IDataspaceProtocolDataAddress` \| `undefined`
+
+The consumer dataAddress, or undefined if not required for this format.
+
+***
+
+### buildProviderStartDataAddress() {#buildproviderstartdataaddress}
+
+> **buildProviderStartDataAddress**(`ctx`): `Promise`\<`IDataspaceProtocolDataAddress` \| `undefined`\>
+
+Build the provider dataAddress for the TransferStartMessage.
+Called during startTransfer (provider role). Throws a GeneralError when
+required configuration (e.g. dataPlanePath) is absent.
+
+#### Parameters
+
+##### ctx
+
+[`ITransferHandlerStartContext`](ITransferHandlerStartContext.md)
+
+The start context.
+
+#### Returns
+
+`Promise`\<`IDataspaceProtocolDataAddress` \| `undefined`\>
+
+The provider dataAddress, or undefined if not applicable.
+
+***
+
+### onProviderStart() {#onproviderstart}
+
+> **onProviderStart**(`dataPlaneComponent`, `consumerPid`, `previousState`): `Promise`\<`void`\>
+
+Post-start hook for the provider role. Called after state has been persisted
+to STARTED. PUSH transfers set up (or resume) the data-plane push subscription
+here; all other formats are no-ops.
+
+#### Parameters
+
+##### dataPlaneComponent
+
+`IDataspaceDataPlaneComponent`
+
+The data plane component instance.
+
+##### consumerPid
+
+`string`
+
+The consumer process ID.
+
+##### previousState
+
+`DataspaceProtocolTransferProcessStateType`
+
+The state before the STARTED transition.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the hook completes.
+
+***
+
+### onComplete() {#oncomplete}
+
+> **onComplete**(`dataPlaneComponent`, `consumerPid`): `Promise`\<`void`\>
+
+Called after a transfer transitions to COMPLETED.
+PUSH and POST tear down the push subscription; PULL is a no-op.
+
+#### Parameters
+
+##### dataPlaneComponent
+
+`IDataspaceDataPlaneComponent`
+
+The data plane component instance.
+
+##### consumerPid
+
+`string`
+
+The consumer process ID.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the hook completes.
+
+***
+
+### onSuspend() {#onsuspend}
+
+> **onSuspend**(`dataPlaneComponent`, `consumerPid`): `Promise`\<`void`\>
+
+Called after a transfer transitions to SUSPENDED.
+PUSH and POST suspend the push subscription; PULL is a no-op.
+
+#### Parameters
+
+##### dataPlaneComponent
+
+`IDataspaceDataPlaneComponent`
+
+The data plane component instance.
+
+##### consumerPid
+
+`string`
+
+The consumer process ID.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the hook completes.
+
+***
+
+### onTerminate() {#onterminate}
+
+> **onTerminate**(`dataPlaneComponent`, `consumerPid`): `Promise`\<`void`\>
+
+Called after a transfer transitions to TERMINATED.
+PUSH and POST tear down the push subscription; PULL is a no-op.
+
+#### Parameters
+
+##### dataPlaneComponent
+
+`IDataspaceDataPlaneComponent`
+
+The data plane component instance.
+
+##### consumerPid
+
+`string`
+
+The consumer process ID.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the hook completes.

package/docs/reference/interfaces/ITransferHandlerPrepareContext.md

@@ -0,0 +1,35 @@
+# Interface: ITransferHandlerPrepareContext
+
+Context supplied to buildConsumerDataAddress during prepareTransfer.
+
+## Properties
+
+### consumerPid {#consumerpid}
+
+> **consumerPid**: `string`
+
+The consumer process ID.
+
+***
+
+### origin {#origin}
+
+> **origin**: `string`
+
+The consumer's base origin URL.
+
+***
+
+### dataPlanePath {#dataplanepath}
+
+> **dataPlanePath**: `string` \| `undefined`
+
+The data plane path segment, if configured.
+
+***
+
+### organizationIdentity {#organizationidentity}
+
+> **organizationIdentity**: `string`
+
+The organization identity resolved from the current context.

package/docs/reference/interfaces/ITransferHandlerStartContext.md

@@ -0,0 +1,51 @@
+# Interface: ITransferHandlerStartContext
+
+Context supplied to buildProviderStartDataAddress during startTransfer (provider role).
+
+## Properties
+
+### entity {#entity}
+
+> **entity**: `ITransferProcess`
+
+The transfer process entity.
+
+***
+
+### publicOrigin {#publicorigin}
+
+> **publicOrigin**: `string`
+
+The provider's public origin URL.
+
+***
+
+### dataPlanePath {#dataplanepath}
+
+> **dataPlanePath**: `string` \| `undefined`
+
+The data plane path segment, if configured.
+
+***
+
+### organizationIdentity {#organizationidentity}
+
+> **organizationIdentity**: `string`
+
+The organization identity resolved from the current context.
+
+***
+
+### trustComponent {#trustcomponent}
+
+> **trustComponent**: `ITrustComponent`
+
+The trust component for generating access tokens.
+
+***
+
+### overrideTrustGeneratorType {#overridetrustgeneratortype}
+
+> **overrideTrustGeneratorType**: `string` \| `undefined`
+
+The override trust generator type, if configured.

package/docs/reference/variables/TransferHandlerFactory.md

@@ -0,0 +1,7 @@
+# Variable: TransferHandlerFactory
+
+> `const` **TransferHandlerFactory**: `Factory`\<[`ITransferHandler`](../interfaces/ITransferHandler.md)\>
+
+Factory for registering and retrieving format-specific ITransferHandler instances.
+Keys are DataspaceTransferFormat values (e.g. "HttpData-PULL").
+Throws GeneralError when get() is called with an unregistered format.

package/locales/en.json

@@ -4,7 +4,6 @@
 			"transferProcessInitiated": "Transfer Process initiated",
 			"transferProcessQueried": "Transfer Process queried (role: {role})",
 			"transferProcessStarted": "Transfer Process started",
-			"dataAccessTokenGenerated": "Data access token generated for PULL transfer",
 			"transferProcessCompleted": "Transfer Process completed",
 			"transferProcessSuspended": "Transfer Process suspended",
 			"transferProcessTerminated": "Transfer Process terminated",
@@ -12,8 +11,6 @@
 			"resolvedProviderPid": "Resolved providerPid to Transfer Context",
 			"catalogDatasetFound": "Dataset validated in Federated Catalogue",
 			"agreementMatchedOffer": "Agreement matched Catalog Offer",
-			"populatingFederatedCatalogue": "Populating Federated Catalogue with stored app datasets",
-			"federatedCataloguePopulated": "Federated Catalogue population completed (registered: {registeredCount}, errors: {errorCount}, datasets: {totalDatasets})",
 			"startingContractNegotiation": "Starting contract negotiation with provider",
 			"offerFoundInCatalog": "Offer found in Federated Catalogue and validated",
 			"negotiationInitiated": "Contract negotiation initiated successfully",
@@ -25,7 +22,6 @@
 			"negotiationHistoryRetrieved": "Negotiation history retrieved successfully",
 			"stalledNegotiationsCleanupComplete": "Stalled negotiations cleanup completed (cleanedUp: {cleanedUp})",
 			"stalledTransfersCleanupComplete": "Stalled transfers cleanup completed (cleanedUp: {cleanedUp})",
-			"pushTransferStarted": "PUSH transfer started (consumerPid: {consumerPid}, providerPid: {providerPid}, endpoint: {endpoint})",
 			"preparingTransfer": "Preparing consumer-initiated data transfer (agreementId: {agreementId}, providerEndpoint: {providerEndpoint}, format: {format})",
 			"transferPrepared": "Consumer data transfer prepared successfully (consumerPid: {consumerPid}, providerPid: {providerPid}, agreementId: {agreementId}, format: {format})"
 		},
@@ -39,8 +35,7 @@
 	},
 	"debug": {
 		"dataspaceControlPlaneService": {
-			"engineCloneStart": "Skipping Federated Catalogue population (engine clone or no engine)",
-			"datasetRegistered": "Dataset {datasetId} registered for app {appId} (tenant: {tenantId})"
+			"engineCloneStart": "Skipping control plane startup tasks (engine clone or no engine)"
 		}
 	},
 	"warn": {
@@ -62,7 +57,6 @@
 			"autoStartFailed": "Provider auto-start of a requested transfer failed (consumerPid: {consumerPid})",
 			"autoStartPublicOriginMissing": "Cannot auto-start the transfer: this node's public origin could not be resolved; holding the transfer in REQUESTED (consumerPid: {consumerPid})",
 			"transferProcessNotFound": "Transfer Process not found",
-			"pullTransfersNotSupported": "PULL transfers are not supported. Configure dataPlanePath in service configuration to enable PULL transfers.",
 			"transferProcessTerminated": "Transfer Process \"{consumerPid}\" is terminated and cannot be used",
 			"transferProcessTerminatedProvider": "Transfer Process \"{providerPid}\" is terminated and cannot be used",
 			"invalidTransferRequest": "Transfer Request does not conform to Dataspace Protocol specification",
@@ -103,9 +97,6 @@
 			"callerNotAuthorizedAsProvider": "The caller's verified identity does not match the provider for this transfer process",
 			"callerNotAuthorizedForTransfer": "The caller's verified identity does not match the consumer or provider for this transfer process",
 			"multipleAssignersNotSupported": "Multiple assigners found in agreement, which is not supported. Only single assigner agreements are supported.",
-			"invalidPushDataAddress": "PUSH transfer cannot start: consumer dataAddress is missing endpoint or endpointType (consumerPid: {consumerPid})",
-			"pushTransferDataPathNotConfigured": "PUSH transfer cannot start: dataPlanePath is not configured (consumerPid: {consumerPid})",
-			"dataPlaneNotRegistered": "Push-mode transfer requires the data plane component to be registered (factory key: \"dataspace-data-plane\"). This deployment was configured without a data plane — register one to enable push, or use pull-mode transfers only.",
 			"datasetPublishFailed": "Failed to publish dataset \"{datasetId}\" for app \"{appId}\" (tenant: \"{tenantId}\")",
 			"datasetRemoveFailed": "Failed to remove dataset \"{datasetId}\" from the Federated Catalogue (tenant: \"{tenantId}\")",
 			"datasetAlreadyExists": "A dataset with id \"{existingId}\" already exists.",
@@ -114,6 +105,18 @@
 			"transferWrongOrganization": "The calling organization does not own this transfer.",
 			"invalidDatasetId": "Dataset ID \"{id}\" is not a valid URN or URL"
 		},
-		"dataspaceControlPlanePolicyRequester": {}
+		"dataspaceControlPlanePolicyRequester": {},
+		"httpDataPullTransferHandler": {
+			"pullTransfersNotSupported": "PULL transfers are not supported: dataPlanePath is not configured (consumerPid: {consumerPid}, providerPid: {providerPid})",
+			"providerIdentityMissing": "Provider identity (DID) is required to sign data access tokens but was not set on the Transfer Process"
+		},
+		"httpDataPushTransferHandler": {
+			"pushTransferDataPathNotConfigured": "PUSH transfer cannot start: dataPlanePath is not configured (consumerPid: {consumerPid})",
+			"invalidPushDataAddress": "PUSH transfer cannot start: consumer dataAddress is missing endpoint or endpointType (consumerPid: {consumerPid})"
+		},
+		"httpDataPostTransferHandler": {
+			"pushTransferDataPathNotConfigured": "POST transfer cannot start: dataPlanePath is not configured (consumerPid: {consumerPid})",
+			"providerIdentityMissing": "Provider identity (DID) is required to sign data access tokens but was not set on the Transfer Process"
+		}
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/dataspace-control-plane-service",
-	"version": "0.9.0",
+	"version": "0.9.1-next.10",
 	"description": "Implements agreement negotiation and transfer process lifecycle management for control plane operations.",
 	"repository": {
 		"type": "git",
@@ -14,23 +14,23 @@
 		"node": ">=20.0.0"
 	},
 	"dependencies": {
-		"@twin.org/api-models": "^0.9.0",
-		"@twin.org/api-tenant-processor": "^0.9.0",
-		"@twin.org/context": "^0.9.0",
-		"@twin.org/core": "^0.9.0",
-		"@twin.org/crypto": "^0.9.0",
-		"@twin.org/dataspace-models": "^0.9.0",
-		"@twin.org/entity": "^0.9.0",
-		"@twin.org/entity-storage-models": "^0.9.0",
-		"@twin.org/federated-catalogue-models": "^0.9.0",
-		"@twin.org/logging-models": "^0.9.0",
-		"@twin.org/nameof": "^0.9.0",
-		"@twin.org/rights-management-models": "^0.9.0",
-		"@twin.org/standards-dataspace-protocol": "^0.9.0",
-		"@twin.org/standards-w3c-odrl": "^0.9.0",
-		"@twin.org/telemetry-models": "^0.9.0",
-		"@twin.org/trust-models": "^0.9.0",
-		"@twin.org/vault-models": "^0.9.0"
+		"@twin.org/api-models": "next",
+		"@twin.org/api-tenant-processor": "next",
+		"@twin.org/context": "next",
+		"@twin.org/core": "next",
+		"@twin.org/crypto": "next",
+		"@twin.org/dataspace-models": "0.9.1-next.10",
+		"@twin.org/entity": "next",
+		"@twin.org/entity-storage-models": "next",
+		"@twin.org/federated-catalogue-models": "next",
+		"@twin.org/logging-models": "next",
+		"@twin.org/nameof": "next",
+		"@twin.org/rights-management-models": "next",
+		"@twin.org/standards-dataspace-protocol": "next",
+		"@twin.org/standards-w3c-odrl": "next",
+		"@twin.org/telemetry-models": "next",
+		"@twin.org/trust-models": "next",
+		"@twin.org/vault-models": "next"
 	},
 	"main": "./dist/es/index.js",
 	"types": "./dist/types/index.d.ts",