app.services package

Submodules

app.services.assets_service module

Assets service.

This module defines the core business logic for managing Asset entities within the EDC Studio Backend. It handles database operations, API requests to the EDC management endpoints, and validation of connector references.

Each function encapsulates a specific responsibility, such as creating, updating, deleting, or retrieving assets, both from the internal MongoDB database and from the EDC connectors via HTTP requests.

async app.services.assets_service.create_asset(data)

Creates a new asset and registers it with the corresponding EDC connector.

The function validates the existence of the connector in the database, transforms the asset data into the required EDC format, and calls the EDC management API to register the asset.

Parameters:

data (Asset) – Asset information to be created and registered.

Returns:

JSON response from the EDC connector containing the asset ID.

Return type:

dict

Raises:

HTTPException – If the EDC connector is not found or the HTTP request fails.

async app.services.assets_service.register_asset_with_edc(asset, connector)

Registers a new asset directly with the EDC management API.

Parameters:

  • asset (dict) – Asset data in dictionary format.

  • connector (dict) – Connector configuration retrieved from the database.

Returns:

JSON response from the EDC management API.

Return type:

dict

async app.services.assets_service.get_asset_by_asset_id_service(edc_id, asset_id)

Retrieves an asset by its ID directly from the EDC connector.

Parameters:

  • edc_id (str) – ID of the EDC connector.

  • asset_id (str) – Asset identifier within the EDC system.

Returns:

Asset object retrieved from the EDC.

Return type:

Asset

Raises:

HTTPException – If the connector is not found or the EDC request fails.

async app.services.assets_service.update_asset(asset, edc_id)

Updates an existing asset in the EDC connector.

Parameters:

  • asset (Asset) – Updated asset data.

  • edc_id (str) – ID of the EDC connector.

Returns:

True if the update succeeded.

Return type:

bool

Raises:

HTTPException – If the connector is not found or the HTTP request fails.

async app.services.assets_service.delete_asset(asset_id, edc_id)

Deletes an asset from the EDC connector.

Parameters:

  • asset_id (str) – Identifier of the asset to delete.

  • edc_id (str) – Identifier of the EDC connector.

Returns:

True if the asset was successfully deleted.

Return type:

bool

Raises:

HTTPException – If the connector is not found or the HTTP request fails.

async app.services.assets_service.get_assets_by_edc_id(edc_id)

Retrieves all assets registered in a specific EDC connector.

Parameters:

edc_id (str) – ID of the EDC connector.

Returns:

List of Asset objects registered in the EDC.

Return type:

list[Asset]

Raises:

HTTPException – If the connector is not found or the HTTP request fails.

app.services.connectors_service module

Connectors service.

This module implements the business logic for managing EDC connectors within the EDC Studio Backend. It handles database interactions, Docker lifecycle management, and port validation for locally managed EDC instances.

The service supports creating, starting, stopping, updating, and deleting connectors, as well as verifying their operational state and uniqueness of ports.

async app.services.connectors_service.create_connector(connector)

Creates a new connector and stores it in the MongoDB database.

The function first validates that the connector’s ports are unique and not already in use. If validation passes, the connector is inserted into the database.

Parameters:

connector (Connector) – Connector configuration data.

Returns:

The inserted connector’s MongoDB ID as a string.

Return type:

str

Raises:

HTTPException – If one or more ports are already in use.

async app.services.connectors_service.check_ports_unique(connector, db)

Validates that the ports used by a connector are unique.

Ensures no other connector in the database or process in the system is already using any of the specified ports.

Parameters:

  • connector (Connector) – Connector to validate.

  • db – Database client instance.

Raises:

HTTPException – If any port is already assigned or in use.

app.services.connectors_service.is_port_in_use(port)

Checks whether a given port is already in use on the host machine.

Parameters:

port (int) – The port number to check.

Returns:

True if the port is in use, False otherwise.

Return type:

bool

async app.services.connectors_service.start_edc_service(connector_id)

Starts a managed EDC connector by generating its runtime configuration and launching the associated Docker containers.

Parameters:

connector_id (str) – The MongoDB ID of the connector to start.

Raises:

  • ValueError – If the connector does not exist.

  • RuntimeError – If the Docker launch process fails.

async app.services.connectors_service.stop_edc_service(connector_id)

Stops a running managed EDC connector and updates its state.

Parameters:

connector_id (str) – The MongoDB ID of the connector to stop.

Raises:

  • ValueError – If the runtime directory does not exist.

  • RuntimeError – If stopping the connector fails.

async app.services.connectors_service.get_all_connectors()

Retrieves all connectors from the database and checks their runtime state.

For managed connectors, it inspects Docker to determine if the containers are running and updates the connector state in the database accordingly.

Returns:

A list of connector objects with updated runtime states.

Return type:

list[dict]

async app.services.connectors_service.get_connector_by_id(id)

Retrieves a connector by its MongoDB ID.

Parameters:

id (str) – Connector ID as a string.

Returns:

Connector data.

Return type:

dict

Raises:

ValueError – If the connector is not found.

async app.services.connectors_service.update_connector(id, update_data)

Updates an existing connector with new data.

Parameters:

  • id (str) – The MongoDB ID of the connector.

  • update_data (dict) – Dictionary containing the fields to update.

Raises:

ValueError – If the connector does not exist.

async app.services.connectors_service.delete_connector(id)

Deletes a connector and its associated runtime folder.

The runtime directory under runtime/{connector_id} is removed from disk before the database record is deleted.

Parameters:

id (str) – The MongoDB ID of the connector.

Raises:

ValueError – If the runtime folder or connector record does not exist.

app.services.contracts_service module

Contracts service.

This module implements the business logic for managing contract definitions within the EDC Studio Backend. It handles the interaction between the API, the MongoDB database, and the EDC Management API for creating, reading, updating, and deleting contract definitions.

Contracts link assets with access and usage policies to define the conditions under which data can be exchanged between EDC connectors.

async app.services.contracts_service.create_contract(data)

Creates a new contract definition in the EDC system.

The function retrieves the connector configuration from the database and registers the new contract definition via the EDC Management API.

Parameters:

data (Contract) – Contract definition data to be created.

Returns:

JSON response from the EDC Management API.

Return type:

str

Raises:

HTTPException – If the connector is not found or registration fails.

async app.services.contracts_service._register_contract_with_edc(contract, connector)

Registers a contract definition in the EDC Management API.

Parameters:

  • contract (dict) – Contract data to register.

  • connector (dict) – Connector configuration data.

Returns:

Response from the EDC Management API.

Return type:

dict

Raises:

HTTPException – If the EDC returns an error response.

app.services.contracts_service._convert_contract_to_edc_format(contract)

Converts a contract from the internal format to the EDC API format.

Parameters:

contract (dict) – Internal contract representation.

Returns:

Contract formatted according to the EDC Management API specification.

Return type:

dict

async app.services.contracts_service.get_contracts_by_edc_id(edc_id)

Retrieves all contract definitions from a given EDC connector.

Parameters:

edc_id (str) – MongoDB ID of the connector.

Returns:

List of contract definitions available in the connector.

Return type:

list[Contract]

Raises:

HTTPException – If the connector is not found or communication fails.

async app.services.contracts_service.get_contract_by_contract_id_service(edc_id, contract_id)

Retrieves a single contract definition by its ID.

Parameters:

  • edc_id (str) – Connector MongoDB ID.

  • contract_id (str) – Contract definition ID in the EDC system.

Returns:

Parsed contract object.

Return type:

Contract

Raises:

HTTPException – If the connector or contract cannot be found.

async app.services.contracts_service.update_contract(contract, edc_id)

Updates an existing contract definition in the EDC system.

Parameters:

  • contract (Contract) – Contract data to update.

  • edc_id (str) – MongoDB ID of the connector.

Returns:

True if the update succeeded, False otherwise.

Return type:

bool

async app.services.contracts_service.delete_contract(contract_id, edc_id)

Deletes a contract definition from the EDC system.

Parameters:

  • contract_id (str) – Contract ID to delete.

  • edc_id (str) – MongoDB ID of the connector.

Returns:

True if deletion succeeded, False otherwise.

Return type:

bool

async app.services.contracts_service._get_connector(edc_id)

Retrieves connector configuration from the database.

Parameters:

edc_id (str) – MongoDB ID of the connector.

Returns:

Connector document.

Return type:

dict

Raises:

HTTPException – If the connector does not exist.

app.services.contracts_service._parse_contract_item(item, edc_id)

Parses a raw contract JSON object into a Contract model.

Parameters:

  • item (dict) – Raw contract data returned by the EDC.

  • edc_id (str) – ID of the connector associated with the contract.

Returns:

Parsed contract model.

Return type:

Contract

app.services.edc_launcher_service module

EDC Launcher service.

This module manages the local lifecycle of EDC connectors by generating runtime configuration files, certificates, and Docker Compose setups.

It handles:

  • File and certificate generation

  • PostgreSQL database initialization

  • Docker Compose orchestration

  • Docker network creation

These utilities are used when launching managed connectors through the EDC Studio Backend.

app.services.edc_launcher_service.keystore_password = 'm_rHiewOa5CbEE87490pSQ'

Randomly generated keystore password for EDC connector certificates.

app.services.edc_launcher_service._generate_files(connector, base_path)

Generates all necessary runtime artifacts for a given EDC connector, including configuration files, certificates, and Docker Compose setup.

This function performs the following steps:

  1. Creates the required runtime folder structure under the given base path.

  2. Generates the EDC runtime configuration file (config.properties) with dynamic port assignments, authentication key, and database connection details.

  3. Generates a PKCS#12 keystore (cert.pfx) used by the connector for secure communication.

  4. Creates a docker-compose.yml file to launch the connector in Docker. The connector services are exposed internally (via expose) but not published to the host system, allowing multiple connectors to run simultaneously without port conflicts.

    Each connector is connected to a shared Docker network where an automatic reverse proxy container (nginx-proxy) is also attached. This proxy detects new containers via environment variables (VIRTUAL_HOST, VIRTUAL_PORT) and automatically generates the corresponding Nginx configuration files under /etc/nginx/conf.d/.

    As a result:

    • Each connector becomes reachable through its own domain name, without manual Nginx configuration.

    • The proxy forwards external requests to the correct internal service and port (for example, /management or /public).

    • The use of expose ensures that only the proxy can access connector services, enhancing network isolation and security.

  5. (For provider connectors) Appends an additional configuration line in config.properties to declare the public data plane endpoint.

Parameters:

  • connector (dict) – MongoDB connector document containing fields such as _id, name, type, ports, api_key, and domain.

  • base_path (Path) – Base directory where the connector’s runtime files and Docker configuration will be created.

Raises:

RuntimeError – If the certificate generation command (keytool) fails.

app.services.edc_launcher_service._wait_for_postgres()

Waits until the PostgreSQL service becomes available.

The function attempts to connect to PostgreSQL periodically until a timeout of 30 seconds is reached.

Raises:

TimeoutError – If PostgreSQL is not available within 30 seconds.

app.services.edc_launcher_service._run_docker_compose(path, db_name)

Initializes PostgreSQL, prepares the database schema, and starts Docker Compose.

This function:

  1. Waits for PostgreSQL availability.

  2. Creates a database for the connector if it does not exist.

  3. Executes the initialization SQL script.

  4. Launches the Docker Compose stack for the connector.

Parameters:

  • path (Path) – Path to the connector’s runtime directory.

  • db_name (str) – Name of the database to create.

Raises:

  • ValueError – If the runtime folder does not exist.

  • FileNotFoundError – If init.sql is missing.

  • Exception – If database creation or Docker startup fails.

app.services.edc_launcher_service._run_docker_compose_down(path)

Stops and removes Docker Compose services for a connector.

Parameters:

path (Path) – Path to the connector’s runtime directory.

app.services.edc_launcher_service._create_docker_network_if_not_exists(network_name)

Ensures that a given Docker network exists, creating it if necessary.

Parameters:

network_name (str) – Name of the Docker network to validate or create.

app.services.policies_service module

Policies Service.

This module provides functionality to manage policy definitions within the EDC (Eclipse Dataspace Connector) ecosystem. It includes operations for creating, retrieving, and deleting policies via the connector’s Management API.

These policies define permissions, prohibitions, and obligations according to the ODRL (Open Digital Rights Language) model and are essential to enforce access control rules for assets exchanged between EDC participants.

Handled responsibilities:

  • Policy creation and registration in EDC

  • Conversion between internal models and EDC-compatible JSON-LD

  • Policy retrieval by connector or policy ID

  • Policy deletion from EDC Management API

async app.services.policies_service.create_policy(data)

Creates and registers a policy definition in a specific EDC connector.

Parameters:

data (Policy) – Policy data model containing permissions, prohibitions, and obligations following the ODRL schema.

Raises:

HTTPException – If the connector is not found or EDC registration fails.

Returns:

JSON response from the EDC API confirming the created policy.

Return type:

str

async app.services.policies_service.register_policy_with_edc(policy, connector)

Registers a new policy in the EDC Management API.

Parameters:

  • policy (dict) – Dictionary containing the policy data to register.

  • connector (dict) – EDC connector document containing configuration and API endpoint details.

Raises:

httpx.HTTPStatusError – If the EDC Management API returns an error.

Returns:

JSON response from the EDC confirming registration.

Return type:

dict

app.services.policies_service.convert_policy_to_edc_format(policy)

Converts an internal Policy model into EDC-compatible JSON-LD format.

Parameters:

policy (dict) – Internal policy representation.

Returns:

Policy formatted according to EDC Management API schema.

Return type:

dict

app.services.policies_service._convert_rules(rules)

Converts a list of internal rule objects into EDC ODRL-compliant rules.

Parameters:

rules (list) – List of permission, prohibition, or obligation rules.

Returns:

EDC-compatible rule dictionaries.

Return type:

list

app.services.policies_service.normalize_odrl_list(value)

Ensures that an ODRL property is always returned as a list.

Parameters:

value (Any) – Raw ODRL property (dict, list, or None).

Returns:

A normalized list of elements or an empty list.

Return type:

list

app.services.policies_service.convert_rules_get(rule_list)

Converts a list of ODRL rules from EDC API format to internal Rule models.

Parameters:

rule_list (list) – ODRL-formatted rule list from EDC API.

Returns:

List of internal Rule objects.

Return type:

list[Rule]

async app.services.policies_service.get_policies_by_edc_id(edc_id)

Retrieves all policy definitions from a given EDC connector.

Parameters:

edc_id (str) – ID of the connector from which to retrieve policies.

Raises:

HTTPException – If the connector does not exist or communication fails.

Returns:

List of Policy objects retrieved from the EDC.

Return type:

list[Policy]

async app.services.policies_service.get_policy_by_policy_id_service(edc_id, policy_id)

Retrieves a single policy definition by its ID from an EDC connector.

Parameters:

  • edc_id (str) – EDC connector ID.

  • policy_id (str) – Unique policy identifier.

Raises:

HTTPException – If the connector or policy cannot be found.

Returns:

The corresponding Policy model.

Return type:

Policy

async app.services.policies_service.delete_policy(policy_id, edc_id)

Deletes a policy definition from a specific EDC connector.

Parameters:

  • policy_id (str) – Policy identifier to remove.

  • edc_id (str) – Connector ID.

Raises:

HTTPException – If the connector does not exist or deletion fails.

Returns:

True if deletion succeeded, False otherwise.

Return type:

bool

app.services.transfers_service module

Transfers Service.

This module handles the complete data exchange lifecycle between EDC connectors, including catalog retrieval, contract negotiation, agreement validation, and data transfer initiation (PUSH or PULL).

It acts as the orchestration layer for data transactions in the EDC Studio Backend, communicating with the connectors’ Management and Protocol APIs.

Main responsibilities:

  • Requesting and parsing asset catalogs between connectors.

  • Negotiating and validating contract agreements.

  • Starting, monitoring, and managing data transfers.

  • Managing local transfer metadata and HTTP logger containers.

All operations follow the EDC protocol specifications and use the dataspace-protocol-http communication channel.

async app.services.transfers_service.catalog_request_service(consumer_id, provider_id)

Requests the asset catalog from a provider connector through an EDC consumer.

Parameters:

  • consumer_id (str) – MongoDB ID of the consumer connector.

  • provider_id (str) – MongoDB ID of the provider connector.

Raises:

ValueError – If either connector is not found.

Returns:

Catalog response from the provider connector.

Return type:

dict

async app.services.transfers_service.catalog_request_curl(consumer, provider)

Sends an HTTP request to retrieve the catalog of available assets from a provider.

Depending on the consumer’s mode (managed or remote), it builds the proper management and protocol URLs.

Parameters:

  • consumer (dict) – Consumer connector document.

  • provider (dict) – Provider connector document.

Raises:

HTTPException – If API key is missing or EDC communication fails.

Returns:

JSON response containing the provider’s catalog.

Return type:

dict

async app.services.transfers_service.negotiate_contract_service(consumer_id, provider_id, contract_offer_id, asset)

Starts a contract negotiation between a consumer and provider connector.

Parameters:

  • consumer_id (str) – Consumer connector ID.

  • provider_id (str) – Provider connector ID.

  • contract_offer_id (str) – Contract offer identifier.

  • asset (str) – Asset identifier.

Raises:

ValueError – If connectors are not found.

Returns:

EDC negotiation response.

Return type:

dict

async app.services.transfers_service.negotiate_contract_curl(consumer, provider, contract_offer_id, asset)

Performs an HTTP request to the EDC Management API to initiate contract negotiation.

Parameters:

  • consumer (dict) – Consumer connector data.

  • provider (dict) – Provider connector data.

  • contract_offer_id (str) – Contract offer identifier.

  • asset (str) – Asset identifier.

Returns:

JSON response from the EDC Management API.

Return type:

dict

async app.services.transfers_service.get_contract_agreement_service(consumer_id, id_contract_negotiation)

Retrieves a contract agreement based on a negotiation ID.

Parameters:

  • consumer_id (str) – Consumer connector ID.

  • id_contract_negotiation (str) – Contract negotiation ID.

Returns:

Agreement details from EDC.

Return type:

dict

async app.services.transfers_service.get_contract_agreement_curl(consumer, id_contract_negotiation)

Performs a GET request to the EDC API to retrieve contract agreement details.

Parameters:

  • consumer (dict) – Consumer connector data.

  • id_contract_negotiation (str) – Contract negotiation ID.

Returns:

Agreement data from EDC.

Return type:

dict

app.services.transfers_service.start_http_server_service()

Starts or restarts the HTTP logger Docker container used to receive data transfer callbacks.

The container is built from util/http-request-logger and automatically joins the configured EDC Docker network.

app.services.transfers_service.stop_http_server_service()

Stops and removes the HTTP logger Docker container if running.

async app.services.transfers_service.start_transfer_service(consumer_id, provider_id, contract_agreement_id)

Initiates a PUSH data transfer from provider to consumer.

Parameters:

  • consumer_id (str) – Consumer connector ID.

  • provider_id (str) – Provider connector ID.

  • contract_agreement_id (str) – Agreement ID that authorizes transfer.

Returns:

JSON response from EDC transfer API.

Return type:

dict

async app.services.transfers_service.start_transfer_curl(consumer, provider, contract_agreement_id)

Executes the HTTP POST to the EDC API to start a PUSH transfer process.

Parameters:

  • consumer (dict) – Consumer connector data.

  • provider (dict) – Provider connector data.

  • contract_agreement_id (str) – Contract agreement ID.

Returns:

Transfer initiation response.

Return type:

dict

async app.services.transfers_service.check_transfer_service(consumer_id, transfer_process_id)

Retrieves the current status of a transfer process from the consumer connector.

Parameters:

  • consumer_id (str) – MongoDB ID of the consumer connector.

  • transfer_process_id (str) – Identifier of the transfer process in EDC.

Raises:

ValueError – If the consumer connector is not found.

Returns:

Transfer process details including current state and type.

Return type:

dict

async app.services.transfers_service.check_transfer_curl(consumer, transfer_process_id)

Sends an HTTP GET request to the EDC Management API to obtain the state of a given transfer process.

Parameters:

  • consumer (dict) – Consumer connector configuration document.

  • transfer_process_id (str) – Transfer process identifier.

Raises:

HTTPException – If EDC communication fails.

Returns:

JSON response describing the current transfer state.

Return type:

dict

async app.services.transfers_service.create_transfer_service(data)

Registers a new transfer in the local MongoDB collection.

Parameters:

data (Transfer) – Transfer object containing consumer, provider, and metadata details.

Raises:

HTTPException – If consumer or provider connector is not found.

Returns:

MongoDB ID of the created transfer document.

Return type:

str

async app.services.transfers_service.get_all_transfers_service()

Retrieves all transfers stored in the local database.

This function also populates each transfer with its corresponding consumer, provider, and asset documents, replacing ObjectIds with full document data.

Returns:

List of all transfer documents with populated fields.

Return type:

list[dict]

app.services.transfers_service.convert_objectids(doc)

Converts MongoDB ObjectId fields into string identifiers.

Parameters:

doc (dict) – MongoDB document with potential ObjectId values.

Returns:

Document with ObjectIds replaced by their string representation.

Return type:

dict

async app.services.transfers_service.start_transfer_service_pull(consumer_id, provider_id, contract_agreement_id)

Initiates a PULL data transfer from provider to consumer.

Parameters:

  • consumer_id (str) – Consumer connector ID.

  • provider_id (str) – Provider connector ID.

  • contract_agreement_id (str) – Agreement authorizing data transfer.

Raises:

ValueError – If connectors are not found.

Returns:

Transfer process response from the EDC Management API.

Return type:

dict

async app.services.transfers_service.start_transfer_curl_pull(consumer, provider, contract_agreement_id)

Executes a PULL data transfer request via the EDC Management API.

Parameters:

  • consumer (dict) – Consumer connector configuration.

  • provider (dict) – Provider connector configuration.

  • contract_agreement_id (str) – Valid contract agreement ID.

Returns:

JSON response from the EDC API confirming transfer initiation.

Return type:

dict

async app.services.transfers_service.check_transfer_data_pull_service(consumer_id, transfer_process_id)

Retrieves the endpoint (data address) of a PULL transfer once created.

Parameters:

  • consumer_id (str) – Consumer connector ID.

  • transfer_process_id (str) – EDC transfer process ID.

Raises:

ValueError – If the consumer connector is not found.

Returns:

Data address response from the EDC Management API.

Return type:

dict

async app.services.transfers_service.check_transfer_data_curl_pull(consumer, transfer_process_id)

Sends a GET request to fetch the data address (EDR) for a PULL transfer.

Parameters:

  • consumer (dict) – Consumer connector configuration.

  • transfer_process_id (str) – Transfer process ID.

Returns:

JSON data address from EDC if available.

Return type:

dict

Module contents