Metadata-Version: 2.4
Name: pyedc-dataplane
Version: 0.1.0
Summary: Data plane signaling routers, services, and schemas for the EDC data plane.
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110.0
Requires-Dist: pyld>=2.0.0
Requires-Dist: pyedc-core>=0.1.0

# pyedc-dataplane

FastAPI routers, services, and JSON-LD/Pydantic models that implement the EDC data plane signaling API. The package lets you expose the `/signaling/v1/dataflows` contract that interacts with an Eclipse Dataspace Connector control plane, while keeping the JSON-LD expansion/compaction handled by `pyedc-core`.

## Highlights

- JSON-LD-first router (`pyedc_dataplane.routers.signaling`) that accepts `DataFlowStart/Suspend/Terminate` messages and returns the proper acknowledgements or `DataFlowResponse` payloads.
- Extensible `SignalingService` with hooks (`TransferInstructionConsumer`) so you can plug in your own provisioning logic, integrate with Vault, or fan out events.
- Repository abstraction with an in-memory implementation to track issued `DataAddress` objects per process; swap it with your own store for production.
- `create_signaling_api` helper that builds a fully-namespaced FastAPI application pre-wired with the router and dependency overrides, mirroring how the sample app in `apps/test_app` hosts the control API.

## Installation

```bash
pip install pyedc-dataplane
```

You will also get `pyedc-core`, which provides the JSON-LD middleware, constants, and app factory.

## Usage

Create a standalone service:

```python
from fastapi import FastAPI
from pyedc_dataplane import create_signaling_api

app: FastAPI = create_signaling_api()
```

Or mount the router inside your own application:

```python
from fastapi import FastAPI
from pyedc_dataplane.routers import signaling_router

app = FastAPI()
app.include_router(signaling_router, prefix="/control")
```

### Customizing dependencies

`create_signaling_api` accepts dependency objects directly, but you can also use FastAPI overrides:

```python
from pyedc_dataplane.api import create_signaling_api
from pyedc_dataplane.dependencies import get_instruction_consumer
from my_project.consumer import MyInstructionConsumer

app = create_signaling_api()
app.dependency_overrides[get_instruction_consumer] = lambda: MyInstructionConsumer()
```

Implement the `TransferInstructionConsumer` protocol to point to your storage endpoints, mint tokens, or forward START/SUSPEND/TERMINATE events to other systems. Provide your own `TransferRepository` to persist state anywhere (Postgres, Redis, etc.).

## Development & tests

Run the package tests with pytest:

```bash
pytest packages/pyedc-dataplane/tests
```

The tests exercise the router, service layer, and signaling integration contract. Use them as a starting point when adding new message types or persistence implementations.

## Related packages

- [`pyedc-core`](../pyedc-core) supplies the JSON-LD middleware, HTTP client, and FastAPI helpers used throughout this package.
- [`pyedc`](../pyedc) is an optional meta-package that depends on both the core and dataplane libraries if you prefer a single install.
