processcube-etw-library 2025.8.22__tar.gz → 2026.1.19b0__tar.gz

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

@@ -0,0 +1,61 @@
+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: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          version: "0.9.26"
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version-file: ".python-version"
+
+      - name: Set version
+        run: |
+          DATE_VERSION=$(date +'%Y.%m.%d')
+          if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
+            VERSION="${DATE_VERSION}"
+          else
+            VERSION="${DATE_VERSION}-beta"
+          fi
+          echo "VERSION=${VERSION}" >> $GITHUB_ENV
+          echo "Setting version to: ${VERSION}"
+
+      - name: Debug GitHub context
+        run: |
+          echo "GITHUB EVENT: ${{ github.event_name }}"
+          echo "GITHUB REF: ${{ github.ref }}"
+          echo "GITHUB BASE REF: ${{ github.base_ref }}"
+          echo "GITHUB HEAD REF: ${{ github.head_ref }}"
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Build
+        run: uv build
+        env:
+          SETUPTOOLS_SCM_PRETEND_VERSION: ${{ env.VERSION }}
+
+      - name: Publish to PyPI
+        run: uv publish --token ${{ secrets.PYPI_API_TOKEN }}

processcube_etw_library-2026.1.19b0/.gitignore

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

processcube_etw_library-2026.1.19b0/.python-version

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

processcube_etw_library-2026.1.19b0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: processcube-etw-library
+Version: 2026.1.19b0
+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
+
+## Installation
+
+## Usage
+
+### Start the ETW application
+
+### Subscribe to External Task Topics
+
+### Add a custom health check

processcube_etw_library-2026.1.19b0/README.md

@@ -0,0 +1,11 @@
+# ProcessCube ETW Library
+
+## Installation
+
+## Usage
+
+### Start the ETW application
+
+### Subscribe to External Task Topics
+
+### Add a custom health check

processcube_etw_library-2026.1.19b0/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.19b0/src/processcube_etw_library/__init__.py

@@ -0,0 +1,19 @@
+from .health import (
+    create_url_health_check,
+    HealthCheck,
+    HealthCheckModel,
+    HealthCheckRegistry,
+    HealthConditionInfo,
+    LivezResponse,
+)
+from .etw_app import new_external_task_worker_app
+
+__all__ = [
+    "create_url_health_check",
+    "HealthCheck",
+    "HealthCheckModel",
+    "HealthCheckRegistry",
+    "HealthConditionInfo",
+    "LivezResponse",
+    "new_external_task_worker_app",
+]

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

@@ -0,0 +1,44 @@
+from os import getenv
+
+# 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 processcube_client.app_info import AppInfoClient
+
+from .identity_provider import IdentityProvider
+
+
+def _determine_authority_url(engine_url: str) -> str:
+    if authority := getenv("PROCESSCUBE_AUTHORITY_URL"):
+        return authority
+
+    app_info_client = AppInfoClient(engine_url)
+    authority_url = app_info_client.get_authority()
+    return authority_url # type: ignore
+
+
+def create_external_task_client(
+    engine_url: str,
+    client_name: str,
+    client_secret: str,
+    client_scopes: str,
+    max_get_oauth_access_token_retries: int,
+) -> ExternalTaskClient:
+    authority_url = _determine_authority_url(engine_url)
+
+    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.19b0/src/processcube_etw_library/etw_app.py

@@ -0,0 +1,115 @@
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import asynccontextmanager
+import os
+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:
+    engine_url = os.getenv("PROCESSCUBE_ENGINE_URL", "http://localhost:56000")
+    etw_client_name = os.getenv("PROCESSCUBE_ETW_CLIENT_ID", "test_etw")
+    etw_client_secret = os.getenv(
+        "PROCESSCUBE_ETW_CLIENT_SECRET", "3ef62eb3-fe49-4c2c-ba6f-73e4d234321b"
+    )
+    etw_client_scopes = os.getenv("PROCESSCUBE_ETW_CLIENT_SCOPES", "engine_etw")
+    max_get_oauth_access_token_retries = int(
+        os.getenv("MAX_GET_OAUTH_ACCESS_TOKEN_RETRIES", 10)
+    )
+
+    external_task_client = create_external_task_client(
+        engine_url,
+        etw_client_name,
+        etw_client_secret,
+        etw_client_scopes,
+        max_get_oauth_access_token_retries,
+    )
+
+    return ExternalTaskWorkerApp(
+        external_task_client, built_in_health_checks=built_in_health_checks
+    )

processcube_etw_library-2026.1.19b0/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.19b0/src/processcube_etw_library/health/built_in.py

@@ -0,0 +1,32 @@
+import os
+
+from .check import HealthCheck, create_url_health_check
+from .registry import HealthCheckRegistry
+
+
+def add_built_in_health_checks(registry: HealthCheckRegistry) -> None:
+    engine_url = (
+        os.getenv("PROCESSCUBE_ENGINE_URL", "http://localhost:56000").strip("/")
+        + "/atlas_engine/api/v1/info"
+    )
+    authority_url = (
+        os.getenv("PROCESSCUBE_AUTHORITY_URL", "http://localhost:56020").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"],
+        )
+    )

processcube_etw_library-2026.1.19b0/src/processcube_etw_library/health/check.py

@@ -0,0 +1,45 @@
+from collections.abc import Awaitable, Callable
+from datetime import timedelta
+from time import perf_counter
+import inspect
+
+import httpx
+
+from .models import HealthCheckResult
+
+
+type HealthCheckCondition = Callable[[], bool | Awaitable[bool]]
+
+class HealthCheck:
+    def __init__(
+        self,
+        condition: HealthCheckCondition,
+        service_name: str,
+        tags: list[str] | None = None,
+        comments: list[str] | None = None,
+    ):
+        self.condition = condition
+        self.service_name = service_name
+        self.tags = tags or []
+        self.comments = comments or []
+
+    async def run(self) -> HealthCheckResult:
+        start = perf_counter()
+        try:
+            result = self.condition()
+            if inspect.isawaitable(result):
+                result = await result
+            healthy = bool(result)
+        except Exception:
+            healthy = False
+        elapsed = perf_counter() - start
+        return HealthCheckResult(healthy=healthy, time_taken=timedelta(seconds=elapsed))
+
+
+def create_url_health_check(url: str, timeout: float = 5.0) -> HealthCheckCondition:
+    async def check():
+        async with httpx.AsyncClient() as client:
+            response = await client.get(url, timeout=timeout)
+            return True if response.status_code == 200 else False
+
+    return check

processcube_etw_library-2026.1.19b0/src/processcube_etw_library/health/handlers.py

@@ -0,0 +1,44 @@
+import asyncio
+from datetime import timedelta
+from time import perf_counter
+
+from fastapi.responses import JSONResponse
+
+from .check import HealthCheck
+from .models import (
+    HealthCheckEntityModel,
+    HealthCheckModel,
+)
+from .registry import HealthCheckRegistry
+
+
+async def _run_health_checks(checks: list[HealthCheck]) -> HealthCheckModel:
+    total_start = perf_counter()
+    results = await asyncio.gather(*(check.run() for check in checks))
+    total_elapsed = perf_counter() - total_start
+
+    entities = []
+    all_healthy = True
+    for check, result in zip(checks, results):
+        if not result.healthy:
+            all_healthy = False
+        entity = HealthCheckEntityModel(
+            service=check.service_name,
+            status="healthy" if result.healthy else "unhealthy",
+            time_taken=result.time_taken,
+            tags=check.tags,
+            comments=check.comments,
+        )
+        entities.append(entity)
+
+    return HealthCheckModel(
+        status="healthy" if all_healthy else "unhealthy",
+        total_time_taken=timedelta(seconds=total_elapsed),
+        entities=entities,
+    )
+
+
+async def health_check(registry: HealthCheckRegistry) -> HealthCheckModel:
+    health_result = await _run_health_checks(registry.get_all())
+    status_code = 200 if health_result.status == "healthy" else 503
+    return JSONResponse(content=health_result.model_dump(), status_code=status_code)

processcube_etw_library-2026.1.19b0/src/processcube_etw_library/health/models.py

@@ -0,0 +1,43 @@
+from datetime import timedelta
+
+from pydantic import BaseModel, Field, field_serializer
+
+
+class HealthCheckEntityModel(BaseModel):
+    service: str
+    status: str = "healthy"
+    time_taken: timedelta = Field(default=timedelta())
+    tags: list[str] = Field(default_factory=list)
+    comments: list[str] = Field(default_factory=list)
+
+    @field_serializer("time_taken")
+    def serialize_time_taken(self, time: timedelta) -> str:
+        return str(time)
+
+
+class HealthCheckModel(BaseModel):
+    status: str = "healthy"
+    total_time_taken: timedelta = Field(default=timedelta())
+    entities: list[HealthCheckEntityModel] = Field(default_factory=list)
+
+    @field_serializer("total_time_taken")
+    def serialize_total_time_taken(self, time: timedelta) -> str:
+        return str(time)
+
+
+class LivezResponse(BaseModel):
+    status: str = Field(default="alive", description="Liveness status")
+
+
+class HealthConditionInfo(BaseModel):
+    service_name: str = Field(..., description="Name of the service")
+    tags: list[str] = Field(default_factory=list, description="Tags for categorization")
+    comments: list[str] = Field(default_factory=list, description="Comments describing the check")
+
+class HealthCheckResult(BaseModel):
+    healthy: bool = Field(..., description="Indicates if the health check passed")
+    time_taken: timedelta = Field(..., description="Time taken to perform the health check")
+
+    @field_serializer("time_taken")
+    def serialize_time_taken(self, time: timedelta) -> str:
+        return str(time)

processcube_etw_library-2026.1.19b0/src/processcube_etw_library/health/registry.py

@@ -0,0 +1,28 @@
+from .check import HealthCheck
+
+
+class HealthCheckRegistry:
+    def __init__(self):
+        self._checks: list[HealthCheck] = []
+
+    def register(self, check: HealthCheck) -> None:
+        existing_names = {c.service_name for c in self._checks}
+        if check.service_name in existing_names:
+            raise ValueError(f"Health check with service name '{check.service_name}' already exists")
+        self._checks.append(check)
+
+    def unregister(self, service_name: str) -> bool:
+        for i, check in enumerate(self._checks):
+            if check.service_name == service_name:
+                self._checks.pop(i)
+                return True
+        return False
+
+    def get_all(self) -> list[HealthCheck]:
+        return self._checks.copy()
+
+    def get_by_name(self, service_name: str) -> HealthCheck | None:
+        for check in self._checks:
+            if check.service_name == service_name:
+                return check
+        return None

processcube_etw_library-2026.1.19b0/src/processcube_etw_library/health/routes.py

@@ -0,0 +1,27 @@
+from fastapi import FastAPI
+
+from .registry import HealthCheckRegistry
+from .handlers import health_check
+from .models import (
+    HealthCheckModel,
+    LivezResponse,
+)
+
+
+def setup_health_routes(app: FastAPI, registry: HealthCheckRegistry) -> None:
+    @app.get(
+        "/healthyz",
+        response_model=HealthCheckModel,
+        responses={503: {"model": HealthCheckModel}},
+    )
+    @app.get(
+        "/readyz",
+        response_model=HealthCheckModel,
+        responses={503: {"model": HealthCheckModel}},
+    )
+    async def health_check_route() -> HealthCheckModel:
+        return await health_check(registry)
+
+    @app.get("/livez", response_model=LivezResponse)
+    def livez() -> LivezResponse:
+        return LivezResponse(status="alive")

processcube_etw_library-2026.1.19b0/src/processcube_etw_library/identity_provider.py

@@ -0,0 +1,87 @@
+import logging
+import sys
+
+from oauth2_client.credentials_manager import CredentialManager, ServiceInformation
+from tenacity import (
+    retry,
+    stop_after_attempt,
+    wait_exponential,
+    retry_if_exception_type,
+)
+from requests import exceptions
+
+logger = logging.getLogger("processcube.oauth")
+
+
+def exit_after_retries(retry_state):
+    logger.error(
+        f"Failed to obtain OAuth access token after {retry_state} attempts. Exiting."
+    )
+    sys.exit(1)
+
+
+def log_failed_attempt(retry_state):
+    logger.warning(
+        f"Attempt {retry_state.attempt_number} to obtain OAuth access token failed: {retry_state.outcome.exception()}"
+    )
+
+
+class IdentityProvider:
+
+    def __init__(
+        self,
+        authority_url: str,
+        client_name: str,
+        client_secret: str,
+        client_scopes: str,
+        max_get_oauth_access_token_retries: int,
+    ):
+        self._authority_url = authority_url
+        self._client_name = client_name
+        self._client_secret = client_secret
+        self._client_scopes = client_scopes
+        self._max_get_oauth_access_token_retries = max_get_oauth_access_token_retries
+
+        self._access_token_caller = self._prepare_get_access_token_caller()
+        logger.debug(
+            f"Prepare identity provider with (authority_url={authority_url}, client_name={client_name}, client_secret=***, client_scopes={client_scopes})."
+        )
+
+    def __call__(self):
+        return self._access_token_caller()
+
+    def _prepare_get_access_token_caller(self):
+
+        @retry(
+            stop=stop_after_attempt(self._max_get_oauth_access_token_retries),
+            wait=wait_exponential(multiplier=1, min=2, max=30),
+            retry=retry_if_exception_type(exceptions.ConnectionError),
+            after=log_failed_attempt,
+            retry_error_callback=exit_after_retries,
+        )
+        def get_access_token(authority_url, client_name, client_secret, client_scopes):
+            logger.debug(
+                f"Get access token from ProcessCube (authority_url={authority_url}, client_name={client_name}, client_secret=***, client_scopes={client_scopes})."
+            )
+
+            client_scopes = client_scopes.split(" ")
+
+            service_information = ServiceInformation(
+                f"{authority_url}/auth",
+                f"{authority_url}/token",
+                client_name,
+                client_secret,
+                client_scopes,
+            )
+            manager = CredentialManager(service_information)
+
+            manager.init_with_client_credentials()
+
+            return {"token": manager._access_token}
+
+        return lambda: get_access_token(
+            self._authority_url,
+            self._client_name,
+            self._client_secret,
+            self._client_scopes,
+        )

processcube_etw_library-2026.1.19b0/src/processcube_etw_library/server_config.py

@@ -0,0 +1,27 @@
+from os import getenv
+from typing import TypedDict
+
+
+class ServerConfig(TypedDict, total=False):
+    host: str
+    port: int
+    log_level: str
+    access_log: bool
+    reload: bool
+
+
+def get_server_config() -> ServerConfig:
+    if getenv("ENVIRONMENT") == "production":
+        return ServerConfig(
+            host="0.0.0.0",
+            port=8000,
+            log_level="warning",
+            access_log=False,
+        )
+    else:
+        return ServerConfig(
+            host="0.0.0.0",
+            port=8000,
+            log_level="debug",
+            access_log=True,
+        )