processcube-etw-library 2026.1.22.120215b0__tar.gz

processcube_etw_library-2026.1.22.120215b0/.github/workflows/build_and_publish.yml

@@ -0,0 +1,55 @@
+name: Build and Publish
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          version: "0.9.26"
+
+      - name: Set version
+        id: set_version
+        run: |
+          DATE_VERSION=$(date +'%Y.%m.%d.%H%M%S')
+          if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
+            VERSION="${DATE_VERSION}"
+          else
+            VERSION="${DATE_VERSION}-beta"
+          fi
+          echo "VERSION=${VERSION}" >> $GITHUB_OUTPUT
+          echo "Setting version to: ${VERSION}"
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Build
+        run: uv build
+        env:
+          SETUPTOOLS_SCM_PRETEND_VERSION: ${{ steps.set_version.outputs.VERSION }}
+
+      - name: Publish to PyPI
+        run: uv publish --token ${{ secrets.PYPI_API_TOKEN }}

processcube_etw_library-2026.1.22.120215b0/.gitignore

@@ -0,0 +1,8 @@
+.DS_Store
+.env
+.env*
+.venv/
+__pycache__/
+*.xlsx
+*.egg-info/
+build/

processcube_etw_library-2026.1.22.120215b0/.python-version

@@ -0,0 +1 @@
+3.12

processcube_etw_library-2026.1.22.120215b0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: processcube-etw-library
+Version: 2026.1.22.120215b0
+Summary: A library to create ETW apps with the ProcessCube platform.
+Author-email: Jeremy Hill <jeremy.hill@profection.de>
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi[standard]>=0.128.0
+Requires-Dist: oauth2-client>=1.4.2
+Requires-Dist: processcube-client>=5.0.0
+Requires-Dist: tenacity>=9.1.2
+
+# ProcessCube ETW Library
+
+Build External Task Workers (ETW) for ProcessCube, featuring health checks, typed handlers, and environment-based configuration.
+
+## Installation
+
+```bash
+uv add processcube-etw-library
+```
+
+## Configuration
+
+### Environment Variables
+
+The library uses environment variables for configuration. You can set these in your environment or in a `.env` file in your project root.
+
+| Variable                             | Default                                | Description                                      |
+| ------------------------------------ | -------------------------------------- | ------------------------------------------------ |
+| `PROCESSCUBE_ENGINE_URL`             | `http://localhost:56000`               | URL of the ProcessCube Engine                    |
+| `PROCESSCUBE_AUTHORITY_URL`          | Auto-discovered from engine            | URL of the ProcessCube Authority (OAuth server)  |
+| `PROCESSCUBE_ETW_CLIENT_ID`          | `test_etw`                             | OAuth client ID for the External Task Worker     |
+| `PROCESSCUBE_ETW_CLIENT_SECRET`      | `3ef62eb3-fe49-4c2c-ba6f-73e4d234321b` | OAuth client secret for the External Task Worker |
+| `PROCESSCUBE_ETW_CLIENT_SCOPES`      | `engine_etw`                           | OAuth scopes for the External Task Worker        |
+| `MAX_GET_OAUTH_ACCESS_TOKEN_RETRIES` | `10`                                   | Maximum retries for obtaining OAuth access token |
+| `ENVIRONMENT`                        | `development`                          | Environment mode (`development` or `production`) |
+
+#### Example `.env` File
+
+```env
+PROCESSCUBE_ENGINE_URL=http://localhost:56000
+PROCESSCUBE_ETW_CLIENT_ID=my_etw_client
+PROCESSCUBE_ETW_CLIENT_SECRET=my_secret_key
+PROCESSCUBE_ETW_CLIENT_SCOPES=engine_etw
+ENVIRONMENT=production
+```
+
+### Extending Settings
+
+You can extend the base settings class to add your own environment variables:
+
+```python
+from pydantic import Field
+from processcube_etw_library.settings import ETWSettings, load_settings
+
+class MyAppSettings(ETWSettings):
+    database_url: str = Field(default="sqlite:///app.db")
+    api_key: str = Field(default="")
+
+# Load settings with your custom class
+settings = load_settings(MyAppSettings)
+```
+
+## Usage
+
+### Start the ETW Application
+
+```python
+from processcube_etw_library import new_external_task_worker_app
+
+# Create the application
+app = new_external_task_worker_app()
+
+# Run the application
+app.run()
+```
+
+### Subscribe to External Task Topics
+
+```python
+from processcube_etw_library import new_external_task_worker_app
+
+app = new_external_task_worker_app()
+
+def my_handler(task):
+    # Process the task
+    result = {"processed": True}
+    return result
+
+# Subscribe to a topic
+app.subscribe_to_external_task_for_topic("my-topic", my_handler)
+
+app.run()
+```
+
+### Typed Handlers
+
+Use typed handlers for automatic payload validation with Pydantic models:
+
+```python
+from pydantic import BaseModel
+from processcube_etw_library import new_external_task_worker_app
+
+class MyInput(BaseModel):
+    name: str
+    value: int
+
+class MyOutput(BaseModel):
+    result: str
+
+app = new_external_task_worker_app()
+
+def my_typed_handler(payload: MyInput) -> MyOutput:
+    return MyOutput(result=f"Processed {payload.name} with value {payload.value}")
+
+app.subscribe_to_external_task_for_topic_typed("my-typed-topic", my_typed_handler)
+
+app.run()
+```
+
+### Add a Custom Health Check
+
+```python
+from processcube_etw_library import new_external_task_worker_app
+from processcube_etw_library.health import HealthCheck, create_url_health_check
+
+app = new_external_task_worker_app()
+
+# Add a URL-based health check
+app.add_health_check(
+    HealthCheck(
+        create_url_health_check("http://my-service:8080/health"),
+        service_name="My Service",
+        tags=["backend", "api"],
+        comments=["Checks if My Service is reachable"],
+    )
+)
+
+# Add a custom health check function
+def check_database():
+    # Return True if healthy, False otherwise
+    try:
+        # Your database check logic here
+        return True
+    except Exception:
+        return False
+
+app.add_health_check(
+    HealthCheck(
+        check_database,
+        service_name="Database",
+        tags=["backend", "database"],
+        comments=["Checks database connectivity"],
+    )
+)
+
+app.run()
+```
+
+### Managing Health Checks
+
+```python
+# Get all registered health checks
+checks = app.get_health_checks()
+
+# Get a specific health check by service name
+db_check = app.get_health_check("Database")
+
+# Remove a health check
+app.remove_health_check("Database")
+```
+
+### Disabling Built-in Health Checks
+
+By default, the library registers health checks for the ProcessCube Engine and Authority. You can disable these:
+
+```python
+app = new_external_task_worker_app(built_in_health_checks=False)
+```
+
+## Health Endpoints
+
+The application exposes health endpoints at `/healthyz` and `/readyz` that return the status of all registered health checks.
+To check if the application is running without performing health checks, use `/livez`.
+
+## Server Configuration
+
+The server configuration is determined by the `ENVIRONMENT` variable:
+
+| Setting    | Development | Production |
+| ---------- | ----------- | ---------- |
+| Host       | `0.0.0.0`   | `0.0.0.0`  |
+| Port       | `8000`      | `8000`     |
+| Log Level  | `debug`     | `warning`  |
+| Access Log | `true`      | `false`    |

processcube_etw_library-2026.1.22.120215b0/README.md

@@ -0,0 +1,184 @@
+# ProcessCube ETW Library
+
+Build External Task Workers (ETW) for ProcessCube, featuring health checks, typed handlers, and environment-based configuration.
+
+## Installation
+
+```bash
+uv add processcube-etw-library
+```
+
+## Configuration
+
+### Environment Variables
+
+The library uses environment variables for configuration. You can set these in your environment or in a `.env` file in your project root.
+
+| Variable                             | Default                                | Description                                      |
+| ------------------------------------ | -------------------------------------- | ------------------------------------------------ |
+| `PROCESSCUBE_ENGINE_URL`             | `http://localhost:56000`               | URL of the ProcessCube Engine                    |
+| `PROCESSCUBE_AUTHORITY_URL`          | Auto-discovered from engine            | URL of the ProcessCube Authority (OAuth server)  |
+| `PROCESSCUBE_ETW_CLIENT_ID`          | `test_etw`                             | OAuth client ID for the External Task Worker     |
+| `PROCESSCUBE_ETW_CLIENT_SECRET`      | `3ef62eb3-fe49-4c2c-ba6f-73e4d234321b` | OAuth client secret for the External Task Worker |
+| `PROCESSCUBE_ETW_CLIENT_SCOPES`      | `engine_etw`                           | OAuth scopes for the External Task Worker        |
+| `MAX_GET_OAUTH_ACCESS_TOKEN_RETRIES` | `10`                                   | Maximum retries for obtaining OAuth access token |
+| `ENVIRONMENT`                        | `development`                          | Environment mode (`development` or `production`) |
+
+#### Example `.env` File
+
+```env
+PROCESSCUBE_ENGINE_URL=http://localhost:56000
+PROCESSCUBE_ETW_CLIENT_ID=my_etw_client
+PROCESSCUBE_ETW_CLIENT_SECRET=my_secret_key
+PROCESSCUBE_ETW_CLIENT_SCOPES=engine_etw
+ENVIRONMENT=production
+```
+
+### Extending Settings
+
+You can extend the base settings class to add your own environment variables:
+
+```python
+from pydantic import Field
+from processcube_etw_library.settings import ETWSettings, load_settings
+
+class MyAppSettings(ETWSettings):
+    database_url: str = Field(default="sqlite:///app.db")
+    api_key: str = Field(default="")
+
+# Load settings with your custom class
+settings = load_settings(MyAppSettings)
+```
+
+## Usage
+
+### Start the ETW Application
+
+```python
+from processcube_etw_library import new_external_task_worker_app
+
+# Create the application
+app = new_external_task_worker_app()
+
+# Run the application
+app.run()
+```
+
+### Subscribe to External Task Topics
+
+```python
+from processcube_etw_library import new_external_task_worker_app
+
+app = new_external_task_worker_app()
+
+def my_handler(task):
+    # Process the task
+    result = {"processed": True}
+    return result
+
+# Subscribe to a topic
+app.subscribe_to_external_task_for_topic("my-topic", my_handler)
+
+app.run()
+```
+
+### Typed Handlers
+
+Use typed handlers for automatic payload validation with Pydantic models:
+
+```python
+from pydantic import BaseModel
+from processcube_etw_library import new_external_task_worker_app
+
+class MyInput(BaseModel):
+    name: str
+    value: int
+
+class MyOutput(BaseModel):
+    result: str
+
+app = new_external_task_worker_app()
+
+def my_typed_handler(payload: MyInput) -> MyOutput:
+    return MyOutput(result=f"Processed {payload.name} with value {payload.value}")
+
+app.subscribe_to_external_task_for_topic_typed("my-typed-topic", my_typed_handler)
+
+app.run()
+```
+
+### Add a Custom Health Check
+
+```python
+from processcube_etw_library import new_external_task_worker_app
+from processcube_etw_library.health import HealthCheck, create_url_health_check
+
+app = new_external_task_worker_app()
+
+# Add a URL-based health check
+app.add_health_check(
+    HealthCheck(
+        create_url_health_check("http://my-service:8080/health"),
+        service_name="My Service",
+        tags=["backend", "api"],
+        comments=["Checks if My Service is reachable"],
+    )
+)
+
+# Add a custom health check function
+def check_database():
+    # Return True if healthy, False otherwise
+    try:
+        # Your database check logic here
+        return True
+    except Exception:
+        return False
+
+app.add_health_check(
+    HealthCheck(
+        check_database,
+        service_name="Database",
+        tags=["backend", "database"],
+        comments=["Checks database connectivity"],
+    )
+)
+
+app.run()
+```
+
+### Managing Health Checks
+
+```python
+# Get all registered health checks
+checks = app.get_health_checks()
+
+# Get a specific health check by service name
+db_check = app.get_health_check("Database")
+
+# Remove a health check
+app.remove_health_check("Database")
+```
+
+### Disabling Built-in Health Checks
+
+By default, the library registers health checks for the ProcessCube Engine and Authority. You can disable these:
+
+```python
+app = new_external_task_worker_app(built_in_health_checks=False)
+```
+
+## Health Endpoints
+
+The application exposes health endpoints at `/healthyz` and `/readyz` that return the status of all registered health checks.
+To check if the application is running without performing health checks, use `/livez`.
+
+## Server Configuration
+
+The server configuration is determined by the `ENVIRONMENT` variable:
+
+| Setting    | Development | Production |
+| ---------- | ----------- | ---------- |
+| Host       | `0.0.0.0`   | `0.0.0.0`  |
+| Port       | `8000`      | `8000`     |
+| Log Level  | `debug`     | `warning`  |
+| Access Log | `true`      | `false`    |

processcube_etw_library-2026.1.22.120215b0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=42", "wheel", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "processcube-etw-library"
+dynamic = ["version"]
+description = "A library to create ETW apps with the ProcessCube platform."
+readme = "README.md"
+authors = [{ name = "Jeremy Hill", email = "jeremy.hill@profection.de" }]
+license = { text = "MIT" }
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi[standard]>=0.128.0",
+    "oauth2-client>=1.4.2",
+    "processcube-client>=5.0.0",
+    "tenacity>=9.1.2",
+]
+
+[tool.uv]
+override-dependencies = ["nest-asyncio>=1.6.0"]
+
+[tool.setuptools]
+packages = ["processcube_etw_library"]
+package-dir = { "" = "src" }
+
+[tool.setuptools_scm]

processcube_etw_library-2026.1.22.120215b0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

processcube_etw_library-2026.1.22.120215b0/src/processcube_etw_library/__init__.py

@@ -0,0 +1,25 @@
+# Prevent nest_asyncio from patching asyncio.run() in processcube_client - it breaks uvicorn's loop_factory
+import nest_asyncio
+nest_asyncio.apply = lambda *args, **kwargs: None
+
+from .health import (
+    create_url_health_check,
+    HealthCheck,
+    HealthCheckModel,
+    HealthCheckRegistry,
+    HealthConditionInfo,
+    LivezResponse,
+)
+from .etw_app import new_external_task_worker_app
+from .settings import load_settings, load_settings
+
+__all__ = [
+    "create_url_health_check",
+    "HealthCheck",
+    "HealthCheckModel",
+    "HealthCheckRegistry",
+    "HealthConditionInfo",
+    "LivezResponse",
+    "new_external_task_worker_app",
+    "load_settings",
+]

processcube_etw_library-2026.1.22.120215b0/src/processcube_etw_library/create_external_task_client.py

@@ -0,0 +1,33 @@
+# # Prevent nest_asyncio from patching asyncio.run() in processcube_client - it breaks uvicorn's loop_factory
+# import nest_asyncio
+# nest_asyncio.apply = lambda *args, **kwargs: None
+
+from processcube_client.external_task import ExternalTaskClient
+
+from .identity_provider import IdentityProvider
+from .settings import load_settings
+
+
+def create_external_task_client() -> ExternalTaskClient:
+    settings = load_settings()
+    authority_url = settings.processcube_authority_url
+    engine_url = settings.processcube_engine_url
+    client_name = settings.processcube_etw_client_id
+    client_secret = settings.processcube_etw_client_secret
+    client_scopes = settings.processcube_etw_client_scopes
+    max_get_oauth_access_token_retries = settings.max_get_oauth_access_token_retries
+
+    identity_provider = IdentityProvider(
+        authority_url,
+        client_name,
+        client_secret,
+        client_scopes,
+        max_get_oauth_access_token_retries,
+    )
+    client = ExternalTaskClient(
+        engine_url,
+        identity=identity_provider,
+        install_signals=False,
+    )
+
+    return client

processcube_etw_library-2026.1.22.120215b0/src/processcube_etw_library/etw_app.py

@@ -0,0 +1,98 @@
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import asynccontextmanager
+from typing import Callable, Optional
+
+from fastapi import FastAPI
+import uvicorn
+
+from .health import (
+    add_built_in_health_checks,
+    HealthCheck,
+    HealthCheckRegistry,
+    setup_health_routes
+    )
+from .create_external_task_client import create_external_task_client
+from .server_config import get_server_config
+from .typed_handler import create_typed_handler_wrapper
+from processcube_client.external_task import ExternalTaskClient
+
+
+class ExternalTaskWorkerApp:
+    _etw_client: ExternalTaskClient
+    _health_registry: HealthCheckRegistry
+    _executor: ThreadPoolExecutor
+    _etw_future: Optional[asyncio.Future]
+    _app: FastAPI
+
+    def __init__(
+        self, etw_client: ExternalTaskClient, built_in_health_checks: bool = True
+    ):
+        self._executor = ThreadPoolExecutor(max_workers=1)
+        self._etw_future = None
+        self._etw_client = etw_client
+        self._app = FastAPI(lifespan=self._lifespan)
+        self._health_registry = HealthCheckRegistry()
+        if built_in_health_checks:
+            add_built_in_health_checks(self._health_registry)
+        setup_health_routes(self._app, self._health_registry)
+
+    @asynccontextmanager
+    async def _lifespan(self, app: FastAPI):
+        loop = asyncio.get_running_loop()
+        self._etw_future = loop.run_in_executor(self._executor, self._etw_client.start)
+
+        yield
+
+        loop = asyncio.get_running_loop()
+        await loop.run_in_executor(None, self._etw_client.stop)
+
+        if self._etw_future is not None and not self._etw_future.done():
+            self._etw_future.cancel()
+            try:
+                await self._etw_future
+            except asyncio.CancelledError:
+                pass
+
+        self._executor.shutdown(wait=False)
+
+    @property
+    def fastapi_app(self) -> FastAPI:
+        return self._app
+
+    def run(self) -> None:
+        config = get_server_config()
+        uvicorn.run(self._app, **config)
+
+    def subscribe_to_external_task_for_topic(
+        self, topic: str, handler: Callable, **options
+    ) -> None:
+        self._etw_client.subscribe_to_external_task_topic(topic, handler, **options)
+
+    def subscribe_to_external_task_for_topic_typed(
+        self, topic: str, handler: Callable, **options
+    ) -> None:
+        wrapper = create_typed_handler_wrapper(handler)
+        self._etw_client.subscribe_to_external_task_topic(topic, wrapper, **options)
+
+    def add_health_check(self, check: HealthCheck) -> None:
+        self._health_registry.register(check)
+
+    def remove_health_check(self, service_name: str) -> bool:
+        return self._health_registry.unregister(service_name)
+
+    def get_health_checks(self) -> list[HealthCheck]:
+        return self._health_registry.get_all()
+
+    def get_health_check(self, service_name: str) -> Optional[HealthCheck]:
+        return self._health_registry.get_by_name(service_name)
+
+
+def new_external_task_worker_app(
+    built_in_health_checks: bool = True,
+) -> ExternalTaskWorkerApp:
+    external_task_client = create_external_task_client()
+
+    return ExternalTaskWorkerApp(
+        external_task_client, built_in_health_checks=built_in_health_checks
+    )

processcube_etw_library-2026.1.22.120215b0/src/processcube_etw_library/health/__init__.py

@@ -0,0 +1,23 @@
+from .check import HealthCheck, create_url_health_check
+from .handlers import health_check
+from .models import (
+    HealthCheckEntityModel,
+    HealthCheckModel,
+    HealthConditionInfo,
+    LivezResponse,
+)
+from .registry import HealthCheckRegistry
+from .built_in import add_built_in_health_checks
+from .routes import setup_health_routes
+
+__all__ = [
+    "add_built_in_health_checks",
+    "create_url_health_check",
+    "health_check",
+    "HealthCheck",
+    "HealthCheckEntityModel",
+    "HealthCheckModel",
+    "HealthCheckRegistry",
+    "HealthConditionInfo",
+    "LivezResponse",
+]

processcube_etw_library-2026.1.22.120215b0/src/processcube_etw_library/health/built_in.py

@@ -0,0 +1,34 @@
+from ..settings import load_settings
+from .check import HealthCheck, create_url_health_check
+from .registry import HealthCheckRegistry
+
+
+def add_built_in_health_checks(registry: HealthCheckRegistry) -> None:
+    settings = load_settings()
+
+    engine_url = (
+        settings.processcube_engine_url.strip("/")
+        + "/atlas_engine/api/v1/info"
+    )
+
+    authority_url = (
+        settings.processcube_authority_url.strip("/")
+        + "/.well-known/openid-configuration"
+    )
+
+    registry.register(
+        HealthCheck(
+            create_url_health_check(engine_url),
+            service_name="ProcessCube Engine",
+            tags=["core", "backend"],
+            comments=["Checks if the ProcessCube Engine is reachable"],
+        )
+    )
+    registry.register(
+        HealthCheck(
+            create_url_health_check(authority_url),
+            service_name="ProcessCube Authority",
+            tags=["core", "auth"],
+            comments=["Checks if the ProcessCube Authority is reachable"],
+        )
+    )