julee-polling 0.1.0__py3-none-any.whl

julee_polling/__init__.py

@@ -0,0 +1,60 @@
+"""Polling: watch an external endpoint for new data.
+
+A julee kit. It provides the domain model for a polling schedule, the
+service protocols a poller implements, an HTTP poller, and a Temporal
+pipeline that runs the whole thing durably.
+
+Install it, then adopt it::
+
+    [tool.julee]
+    kits = ["polling"]
+
+Example usage:
+    from julee_polling.domain.models.polling_config import (
+        PollingConfig,
+        PollingProtocol,
+    )
+    from julee_polling.infrastructure.services.polling.http import HttpPollerService
+    # Configure polling
+    config = PollingConfig(
+        endpoint_identifier="api-v1",
+        polling_protocol=PollingProtocol.HTTP,
+        connection_params={"url": "https://api.example.com/data"},
+        timeout_seconds=30
+    )
+
+    # Poll the endpoint
+    service = HttpPollerService()
+    result = await service.poll_endpoint(config)
+
+Note: All imports must be explicit to avoid import chains that can pull
+non-deterministic code into Temporal workflows. Import directly from
+the specific modules you need rather than using this convenience module.
+"""
+
+from julee.core.entities.kit import Kit
+
+# No re-exports to avoid import chains that pull non-deterministic code
+# into Temporal workflows. Import from specific submodules instead:
+#
+# Domain:
+# - from julee_polling.domain.models.polling_config import PollingConfig, PollingProtocol, PollingResult
+# - from julee_polling.domain.services.poller import PollerService
+#
+# Infrastructure:
+# - from julee_polling.infrastructure.services.polling.http import HttpPollerService
+# - from julee_polling.infrastructure.temporal.manager import PollingManager
+# - from julee_polling.infrastructure.temporal.proxies import WorkflowPollerServiceProxy
+# - from julee_polling.infrastructure.temporal.activities import TemporalPollerService
+
+kit = Kit(
+    slug="polling",
+    name="Polling",
+    package="julee_polling",
+    contributes={
+        "temporal.pipelines": "julee_polling.apps.worker.pipelines",
+        "temporal.activities": "julee_polling.infrastructure.temporal.activities",
+    },
+)
+
+__all__ = ["kit"]

julee_polling/apps/__init__.py

@@ -0,0 +1,17 @@
+"""
+Application entry points for the polling contrib module.
+
+This module contains the application-layer components that provide entry points
+for the polling contrib module, including worker pipelines, API routes, and
+CLI commands.
+
+Following the ADR contrib module structure, this layer wires together domain
+services and infrastructure implementations into runnable applications.
+
+No re-exports to avoid import chains that pull non-deterministic code
+into Temporal workflows. Import directly from specific modules:
+
+- from julee_polling.apps.worker.pipelines import NewDataDetectionPipeline
+"""
+
+__all__ = []

julee_polling/apps/worker/__init__.py

@@ -0,0 +1,17 @@
+"""
+Worker applications for the polling contrib module.
+
+This module contains worker-specific entry points for the polling contrib module,
+including Temporal workflows (pipelines) that orchestrate polling operations
+with durability guarantees.
+
+The worker applications in this module can be registered with Temporal workers
+to provide polling capabilities within workflow contexts.
+
+No re-exports to avoid import chains that pull non-deterministic code
+into Temporal workflows. Import directly from specific modules:
+
+- from julee_polling.apps.worker.pipelines import NewDataDetectionPipeline
+"""
+
+__all__ = []

julee_polling/apps/worker/pipelines.py

@@ -0,0 +1,173 @@
+"""
+Temporal workflows for polling operations in the Julee polling contrib module.
+
+This module contains workflows that orchestrate polling operations with
+Temporal's durability guarantees, providing retry logic, state management,
+and reliable execution for endpoint polling and change detection.
+"""
+
+import logging
+from abc import abstractmethod
+from typing import Any
+
+from temporalio import workflow
+
+from julee_polling.domain.models.polling_config import PollingConfig
+from julee_polling.domain.services.new_data_analyzer import NewDataAnalyzer
+from julee_polling.domain.services.polling_result_handler import (
+    PollingResultHandler,
+)
+from julee_polling.infrastructure.temporal.proxies import (
+    WorkflowPollerServiceProxy,
+)
+from julee_polling.usecases.poll_data import (
+    PollDataRequest,
+    PollDataUseCase,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@workflow.defn
+class NewDataDetectionPipeline:
+    """
+    Temporal workflow for endpoint polling with new data detection.
+
+    This workflow:
+    1. Polls an endpoint using the configured polling service
+    2. Compares result with previous completion to detect changes
+    3. Runs the analyzer to identify new item IDs (if provided)
+    4. Hands off to result handler when new data is detected
+    5. Returns completion result for next scheduled execution
+
+    The workflow uses Temporal's schedule last completion result feature
+    to automatically receive the previous execution's result for comparison.
+
+    Subclasses must implement get_handler() and get_analyzer() to supply the
+    appropriate objects for each polling use case (credential, product, etc.).
+    """
+
+    def __init__(self) -> None:
+        self.current_step = "initialized"
+        self.endpoint_id: str | None = None
+        self.has_new_data: bool = False
+
+    @abstractmethod
+    def get_handler(self) -> PollingResultHandler:
+        """Return the PollingResultHandler for this pipeline."""
+        ...
+
+    @abstractmethod
+    def get_analyzer(self) -> NewDataAnalyzer:
+        """Return the NewDataAnalyzer for this pipeline."""
+        ...
+
+    @workflow.query
+    def get_current_step(self) -> str:
+        """Query method to get the current workflow step."""
+        return self.current_step
+
+    @workflow.query
+    def get_endpoint_id(self) -> str | None:
+        """Query method to get the endpoint ID being polled."""
+        return self.endpoint_id
+
+    @workflow.query
+    def get_has_new_data(self) -> bool:
+        """Query method to check if new data was detected."""
+        return self.has_new_data
+
+    @workflow.run
+    async def run(
+        self,
+        config: PollingConfig | dict[str, Any],
+    ) -> dict[str, Any]:
+        """
+        Execute the new data detection workflow.
+
+        Args:
+            config: Configuration for the polling operation (PollingConfig or dict
+                    from Temporal schedule serialisation)
+
+        Returns:
+            Completion result containing polling result and detection metadata
+
+        Raises:
+            RuntimeError: If polling fails after retries
+        """
+        # Temporal schedules serialise arguments as dicts, so accept either
+        # and work with the validated entity from here on.
+        polling_config = (
+            PollingConfig.model_validate(config) if isinstance(config, dict) else config
+        )
+
+        self.endpoint_id = polling_config.endpoint_identifier
+
+        previous_completion = workflow.get_last_completion_result()
+
+        workflow.logger.info(
+            "Starting new data detection pipeline",
+            extra={
+                "endpoint_id": self.endpoint_id,
+                "polling_protocol": polling_config.polling_protocol.value,
+                "has_previous_completion": previous_completion is not None,
+                "workflow_id": workflow.info().workflow_id,
+                "run_id": workflow.info().run_id,
+            },
+        )
+
+        self.current_step = "polling_endpoint"
+
+        try:
+            request = PollDataRequest(
+                config=polling_config,
+                previous_completion=previous_completion,
+            )
+            use_case = PollDataUseCase(
+                poller=WorkflowPollerServiceProxy(),  # type: ignore[abstract]
+                handler=self.get_handler(),
+                analyzer=self.get_analyzer(),
+            )
+            response = await use_case.execute(request)
+
+            self.endpoint_id = response.endpoint_id
+            self.has_new_data = response.new_items_found
+            self.current_step = "completed"
+
+            workflow.logger.info(
+                "New data detection pipeline completed successfully",
+                extra={
+                    "endpoint_id": self.endpoint_id,
+                    "has_new_data": self.has_new_data,
+                },
+            )
+
+            return {
+                "polling_result": {
+                    "content_hash": response.content_hash,
+                    "content": response.content,
+                    "polled_at": response.polled_at,
+                },
+                "detection_result": {
+                    "has_new_data": response.new_items_found,
+                    "current_hash": response.content_hash,
+                },
+                "endpoint_id": response.endpoint_id,
+                "completed_at": workflow.now().isoformat(),
+            }
+
+        except Exception as e:
+            self.current_step = "failed"
+
+            workflow.logger.error(
+                "New data detection pipeline failed",
+                extra={
+                    "endpoint_id": self.endpoint_id,
+                    "error": str(e),
+                    "error_type": type(e).__name__,
+                    "current_step": self.current_step,
+                },
+                exc_info=True,
+            )
+
+            raise

julee_polling/domain/__init__.py

@@ -0,0 +1,15 @@
+"""
+Domain layer for the polling contrib module.
+
+This module contains the core domain models, services, and business rules
+for the polling contrib module. It defines the fundamental concepts and
+protocols that govern polling operations.
+
+No re-exports to avoid import chains that pull non-deterministic code
+into Temporal workflows. Import directly from specific modules:
+
+- from julee_polling.domain.models.polling_config import PollingConfig, PollingProtocol, PollingResult
+- from julee_polling.domain.services.poller import PollerService
+"""
+
+__all__ = []

julee_polling/domain/models/__init__.py

@@ -0,0 +1,12 @@
+"""
+Polling domain models.
+
+This module contains the core domain models for the polling contrib module.
+
+No re-exports to avoid import chains that pull non-deterministic code
+into Temporal workflows. Import directly from specific modules:
+
+- from julee_polling.domain.models.polling_config import PollingConfig, PollingProtocol, PollingResult, SchedulingPolicy
+"""
+
+__all__ = []

julee_polling/domain/models/polling_config.py

@@ -0,0 +1,69 @@
+"""
+Polling domain models.
+
+This module contains the core domain models for polling operations,
+including configuration and result models.
+"""
+
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Any
+
+from julee.core.entities.entity import Entity
+from pydantic import Field, field_validator
+
+
+class PollingProtocol(StrEnum):
+    """Supported polling protocols."""
+
+    HTTP = "http"
+
+
+class SchedulingPolicy(StrEnum):
+    """Scheduling policy for polling operations."""
+
+    ALLOW_OVERLAP = "allow_overlap"
+    SKIP_IF_RUNNING = "skip_if_running"
+
+
+class PollingConfig(Entity):
+    """Configuration for a polling operation."""
+
+    endpoint_identifier: str = Field(description="Unique identifier for this endpoint")
+    polling_protocol: PollingProtocol
+    connection_params: Mapping[str, Any] = Field(default_factory=dict)
+    polling_params: Mapping[str, Any] = Field(default_factory=dict)
+    timeout_seconds: int | None = Field(default=30)
+    scheduling_policy: SchedulingPolicy = Field(
+        default=SchedulingPolicy.ALLOW_OVERLAP,
+        description="Policy for handling overlapping polling operations",
+    )
+
+
+class PollingResult(Entity):
+    """Result of a polling operation."""
+
+    success: bool
+    content: bytes
+    metadata: Mapping[str, Any] = Field(default_factory=dict)
+    polled_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    content_hash: str | None = None
+    error_message: str | None = None
+
+    @field_validator("content", mode="before")
+    @classmethod
+    def validate_content(cls, v):
+        """Convert list of integers to bytes (for Temporal serialization compatibility)."""
+        if isinstance(v, list):
+            # Temporal may serialize bytes as list of integers
+            return bytes(v)
+        elif isinstance(v, str):
+            # Handle string input
+            return v.encode("utf-8")
+        elif isinstance(v, bytes):
+            return v
+        else:
+            raise ValueError(
+                f"Content must be bytes, string, or list of integers, got {type(v)}"
+            )

julee_polling/domain/services/new_data_analyzer.py

@@ -0,0 +1,50 @@
+"""
+NewDataAnalyzer protocol for converting raw polling bytes into item IDs.
+
+This protocol is the counterpart to PollingResultHandler. Where the handler
+decides what to *do* when new items are found, the analyzer decides *what*
+items are new by comparing previous and current polling payloads.
+
+Separating analysis from handling keeps each concern to a single class and
+allows the NewDataDetectionPipeline to complete data→domain translation
+before any application-level dispatch occurs.
+"""
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class NewDataAnalyzer(Protocol):
+    """
+    Converts raw polling bytes into a list of new item identifiers.
+
+    The analyzer is responsible for:
+    - Parsing the raw bytes from the polling response
+    - Comparing with the previous response (if any)
+    - Returning the IDs of items that are new or changed
+
+    The returned IDs are opaque strings from the polling system's perspective.
+    Their meaning is defined by the bounded context that provides the analyzer.
+    """
+
+    async def identify_new_items(
+        self,
+        previous_data: bytes | None,
+        new_data: bytes,
+    ) -> list[str]:
+        """
+        Identify items that are new or changed since the previous poll.
+
+        Args:
+            previous_data: Previous polling response content.
+                           None if this is the first polling run.
+            new_data: Current polling response content.
+
+        Returns:
+            List of item identifier strings that are new or changed.
+            Empty list if nothing is new.
+
+        Raises:
+            ValueError: If the data cannot be parsed or is in an unexpected format.
+        """
+        ...

julee_polling/domain/services/poller.py

@@ -0,0 +1,39 @@
+"""
+PollerService protocol for external endpoint polling operations.
+
+This module defines the PollerService protocol that handles interactions
+with various types of external endpoints for data polling and change detection.
+
+Concrete implementations of this protocol are provided for different polling
+mechanisms and are created via factory functions.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from ..models.polling_config import PollingConfig, PollingResult
+
+
+@runtime_checkable
+class PollerService(Protocol):
+    """
+    Protocol for polling external endpoints for data.
+
+    This protocol defines the interface for a poller service that can perform
+    individual poll operations on different endpoint types. Implementations
+    handle the specifics of different polling mechanisms.
+    """
+
+    async def poll_endpoint(self, config: PollingConfig) -> PollingResult:
+        """
+        Poll an endpoint according to the provided configuration.
+
+        Args:
+            config: PollingConfig containing endpoint details and parameters
+
+        Returns:
+            PollingResult with success status, content, and metadata
+
+        Raises:
+            PollingError: When polling operation fails
+        """
+        ...

julee_polling/domain/services/polling_result_handler.py

@@ -0,0 +1,75 @@
+"""
+PollingResultHandler protocol for cross-bounded-context polling orchestration.
+
+This module defines the PollingResultHandler protocol that enables cross-BC
+coordination when new data is detected during polling operations. Following
+ADR 003, this handler accepts domain-relevant arguments and allows the
+solution provider to decide what happens with newly detected data.
+
+The polling system recognizes the condition (new data detected) and hands off
+to the handler without knowing what the handler does - this is the
+"green-dotted-egg-handler" principle.
+
+By the time handle_new_data() is called, the NewDataDetectionPipeline has
+already translated raw bytes into item IDs via the NewDataAnalyzer. Handlers
+therefore work with structured identifiers, not raw content.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from julee.core.entities.acknowledgement import Acknowledgement
+
+
+@runtime_checkable
+class PollingResultHandler(Protocol):
+    """
+    Handler for new data detected during polling operations.
+
+    This protocol enables cross-bounded-context orchestration by allowing
+    polling systems to hand off newly detected item IDs to solution-specific
+    processing without knowing what that processing entails.
+
+    Handlers may implement any orchestration pattern:
+    - Start Temporal workflows
+    - Queue messages
+    - Trigger use cases directly
+    - Log and notify
+    - Complex multi-step processing
+
+    The handler receives item IDs (strings) rather than raw bytes because the
+    NewDataDetectionPipeline runs a NewDataAnalyzer before calling the handler.
+    This keeps use-case logic out of handlers and makes handlers pure dispatchers.
+    """
+
+    async def handle_new_data(
+        self,
+        endpoint_id: str,
+        new_item_ids: list[str],
+        content_hash: str,
+    ) -> Acknowledgement:
+        """
+        Handle newly detected items from a polling operation.
+
+        This method is called when the polling system detects that data at
+        an endpoint has changed and the analyzer has identified the new items.
+        The handler decides what to do with the item IDs — whether to start
+        processing workflows, queue work, send notifications, or any other
+        domain-specific action.
+
+        Args:
+            endpoint_id: Unique identifier for the polled endpoint
+            new_item_ids: List of item IDs identified as new or changed by the analyzer
+            content_hash: SHA256 hash of the new content for deduplication/tracking
+
+        Returns:
+            Acknowledgement indicating handler response:
+            - wilco: Handler will process the new data
+            - unable: Handler cannot process (resource constraints, invalid state, etc.)
+            - roger: Handler acknowledges but makes no processing commitment
+
+        Raises:
+            Exception: Handlers may raise exceptions for critical failures,
+                      but should prefer returning Acknowledgement.unable() with
+                      error details to avoid failing the polling workflow.
+        """
+        ...

julee_polling/infrastructure/__init__.py

@@ -0,0 +1,16 @@
+"""
+Infrastructure layer for the polling contrib module.
+
+This module contains the concrete implementations of domain protocols
+and external system integrations for the polling contrib module.
+
+No re-exports to avoid import chains that pull non-deterministic code
+into Temporal workflows. Import directly from specific modules:
+
+- from julee_polling.infrastructure.services.polling.http import HttpPollerService
+- from julee_polling.infrastructure.temporal.manager import PollingManager
+- from julee_polling.infrastructure.temporal.proxies import WorkflowPollerServiceProxy
+- from julee_polling.infrastructure.temporal.activities import TemporalPollerService
+"""
+
+__all__ = []

julee_polling/infrastructure/services/__init__.py

@@ -0,0 +1,13 @@
+"""
+Infrastructure services for the polling contrib module.
+
+This module contains the concrete implementations of domain services
+for the polling contrib module.
+
+No re-exports to avoid import chains that pull non-deterministic code
+into Temporal workflows. Import directly from specific modules:
+
+- from julee_polling.infrastructure.services.polling.http import HttpPollerService
+"""
+
+__all__ = []

julee_polling/infrastructure/services/polling/__init__.py

@@ -0,0 +1,13 @@
+"""
+Polling infrastructure services.
+
+This module contains the concrete implementations of polling services
+for different protocols and mechanisms.
+
+No re-exports to avoid import chains that pull non-deterministic code
+into Temporal workflows. Import directly from specific modules:
+
+- from julee_polling.infrastructure.services.polling.http import HttpPollerService
+"""
+
+__all__ = []

julee_polling/infrastructure/services/polling/http/__init__.py

@@ -0,0 +1,13 @@
+"""
+HTTP polling implementation.
+
+This module provides HTTP-specific polling functionality for the polling
+contrib module.
+
+No re-exports to avoid import chains that pull non-deterministic code
+into Temporal workflows. Import directly from specific modules:
+
+- from julee_polling.infrastructure.services.polling.http.http_poller_service import HttpPollerService
+"""
+
+__all__ = []