constellation-node-sdk 1.0.1__py3-none-any.whl

constellation_node_sdk/orchestrator/base.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from constellation_node_sdk.gate.client import GateClient
+from constellation_node_sdk.transport.packet import TransportPacket
+
+from .state import OrchestratorState
+from .step_executor import StepExecutor
+
+
+class BaseOrchestrator(ABC):
+    """
+    Base class for packet-native orchestrators.
+
+    Orchestrators are stateful internal clients of Gate. They never resolve
+    peer nodes directly and never send step packets to peer URLs.
+    """
+
+    def __init__(self, *, gate_client: GateClient, source_node: str) -> None:
+        normalized_source = source_node.strip().lower()
+        if not normalized_source:
+            raise ValueError("source_node must not be empty")
+
+        self._gate_client = gate_client
+        self._source_node = normalized_source
+        self._step_executor = StepExecutor(
+            gate_client=gate_client,
+            source_node=normalized_source,
+        )
+
+    @property
+    def gate_client(self) -> GateClient:
+        return self._gate_client
+
+    @property
+    def source_node(self) -> str:
+        return self._source_node
+
+    @property
+    def step_executor(self) -> StepExecutor:
+        return self._step_executor
+
+    def initial_state(self, packet: TransportPacket) -> OrchestratorState:
+        """
+        Build the default initial workflow state from the inbound packet.
+        """
+        return OrchestratorState.from_packet(
+            packet=packet,
+            orchestrator_node=self._source_node,
+        )
+
+    @abstractmethod
+    async def execute(self, packet: TransportPacket) -> TransportPacket:
+        """
+        Execute the orchestrator workflow and return a canonical response packet.
+        """

constellation_node_sdk/orchestrator/merge.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Any
+
+from constellation_node_sdk.transport.packet import TransportPacket
+
+
+def _payload_copy(packet: TransportPacket) -> dict[str, Any]:
+    return dict(packet.payload)
+
+
+def _response_payload(response: TransportPacket) -> dict[str, Any]:
+    return dict(response.payload)
+
+
+def merge_identity(current: TransportPacket, response: TransportPacket) -> dict[str, Any]:
+    """
+    Replace accumulated payload with the full response payload.
+    """
+    del current
+    return _response_payload(response)
+
+
+def merge_results(current: TransportPacket, response: TransportPacket) -> dict[str, Any]:
+    """
+    Merge response.payload["data"] into current payload when present.
+    Fall back to merging the full response payload.
+    """
+    merged = _payload_copy(current)
+    response_payload = _response_payload(response)
+
+    response_data = response_payload.get("data")
+    if isinstance(response_data, dict):
+        merged.update(response_data)
+        return merged
+
+    merged.update(response_payload)
+    return merged
+
+
+def merge_payload(current: TransportPacket, response: TransportPacket) -> dict[str, Any]:
+    """
+    Merge the full response payload into current payload.
+    """
+    merged = _payload_copy(current)
+    merged.update(_response_payload(response))
+    return merged

constellation_node_sdk/orchestrator/packet_builder.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Any
+
+from constellation_node_sdk.transport.packet import TransportPacket
+from constellation_node_sdk.transport.provenance import RoutingProvenance
+
+
+def build_step_packet(
+    *,
+    parent: TransportPacket,
+    action: str,
+    payload: dict[str, Any],
+    source_node: str,
+    reply_to: str,
+) -> TransportPacket:
+    """
+    Build a child step packet for orchestrator -> Gate execution.
+
+    This function enforces the architectural constraint that every step packet
+    emitted by an orchestrator targets Gate, never a peer node.
+    """
+    normalized_action = action.strip().lower()
+    if not normalized_action:
+        raise ValueError("action must not be empty")
+
+    normalized_source = source_node.strip().lower()
+    normalized_reply_to = reply_to.strip().lower()
+    if not normalized_source:
+        raise ValueError("source_node must not be empty")
+    if not normalized_reply_to:
+        raise ValueError("reply_to must not be empty")
+
+    provenance = RoutingProvenance(
+        origin_kind="node",
+        requested_action=normalized_action,
+        resolved_by_gate=False,
+        original_source_node=normalized_source,
+    )
+
+    return parent.derive(
+        packet_type="request",
+        action=normalized_action,
+        source_node=normalized_source,
+        destination_node="gate",
+        reply_to=normalized_reply_to,
+        payload=dict(payload),
+        provenance=provenance,
+    )

constellation_node_sdk/orchestrator/retry.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class RetryPolicy(BaseModel):
+    """
+    Deterministic retry policy for orchestrator step execution.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    max_attempts: int = Field(default=3, ge=1)
+    initial_delay_seconds: float = Field(default=0.25, ge=0.0)
+    backoff_multiplier: float = Field(default=2.0, ge=1.0)
+    max_delay_seconds: float = Field(default=5.0, ge=0.0)
+    retryable_error_types: tuple[str, ...] = (
+        "TimeoutError",
+        "TransportAuthenticationError",
+        "TransportAuthorizationError",
+        "TransportValidationError",
+        "TransportIntegrityError",
+        "GateClientError",
+    )
+
+    @field_validator("retryable_error_types")
+    @classmethod
+    def validate_retryable_error_types(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        normalized = tuple(item.strip() for item in value if item.strip())
+        if len(set(normalized)) != len(normalized):
+            raise ValueError("retryable_error_types must not contain duplicates")
+        return normalized
+
+    def delay_for_attempt(self, attempt: int) -> float:
+        """
+        Return the backoff delay for the next retry after `attempt`.
+        """
+        if attempt < 1:
+            raise ValueError("attempt must be >= 1")
+        if self.max_attempts <= 1:
+            return 0.0
+
+        delay = self.initial_delay_seconds * (self.backoff_multiplier ** (attempt - 1))
+        return min(delay, self.max_delay_seconds)
+
+
+def should_retry(*, attempt: int, error: Exception, policy: RetryPolicy) -> bool:
+    """
+    Return True when the given error should be retried under the policy.
+
+    `attempt` is 1-indexed and represents the attempt that just failed.
+    """
+    if attempt < 1:
+        raise ValueError("attempt must be >= 1")
+
+    if attempt >= policy.max_attempts:
+        return False
+
+    error_type_names = {cls.__name__ for cls in type(error).mro()}
+    retryable = set(policy.retryable_error_types)
+    return bool(error_type_names & retryable)

constellation_node_sdk/orchestrator/state.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from constellation_node_sdk.transport.packet import TransportPacket
+
+
+class OrchestratorState(BaseModel):
+    """
+    Immutable-ish workflow state container for orchestrators.
+
+    The orchestrator owns workflow-local accumulation state. Gate owns routing.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    root_id: UUID
+    current_packet_id: UUID
+    current_generation: int = Field(ge=0)
+    orchestrator_node: str
+    workflow_name: str | None = None
+    accumulated_payload: dict[str, Any] = Field(default_factory=dict)
+    step_results: tuple[dict[str, Any], ...] = ()
+    completed_steps: tuple[str, ...] = ()
+    failed_steps: tuple[str, ...] = ()
+
+    @classmethod
+    def from_packet(
+        cls,
+        *,
+        packet: TransportPacket,
+        orchestrator_node: str,
+        workflow_name: str | None = None,
+    ) -> OrchestratorState:
+        return cls(
+            root_id=packet.lineage.root_id,
+            current_packet_id=packet.header.packet_id,
+            current_generation=packet.lineage.generation,
+            orchestrator_node=orchestrator_node.strip().lower(),
+            workflow_name=None if workflow_name is None else workflow_name.strip(),
+            accumulated_payload=dict(packet.payload),
+            step_results=(),
+            completed_steps=(),
+            failed_steps=(),
+        )
+
+    def with_step_success(
+        self,
+        *,
+        step_name: str,
+        response_packet: TransportPacket,
+        merged_payload: dict[str, Any],
+    ) -> OrchestratorState:
+        response_snapshot = {
+            "step_name": step_name.strip().lower(),
+            "packet_id": str(response_packet.header.packet_id),
+            "action": response_packet.header.action,
+            "payload": dict(response_packet.payload),
+        }
+        return self.model_copy(
+            update={
+                "current_packet_id": response_packet.header.packet_id,
+                "current_generation": response_packet.lineage.generation,
+                "accumulated_payload": dict(merged_payload),
+                "step_results": self.step_results + (response_snapshot,),
+                "completed_steps": self.completed_steps + (step_name.strip().lower(),),
+            }
+        )
+
+    def with_step_failure(self, *, step_name: str) -> OrchestratorState:
+        return self.model_copy(
+            update={
+                "failed_steps": self.failed_steps + (step_name.strip().lower(),),
+            }
+        )

constellation_node_sdk/orchestrator/step_executor.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from constellation_node_sdk.gate.client import GateClient
+from constellation_node_sdk.transport.packet import TransportPacket
+
+from .packet_builder import build_step_packet
+from .retry import RetryPolicy, should_retry
+
+
+class StepExecutionError(RuntimeError):
+    """
+    Raised when an orchestrator step cannot be completed successfully.
+    """
+
+
+class StepExecutor:
+    """
+    Execute atomic workflow steps by sending child TransportPackets to Gate.
+
+    This class never resolves peer nodes directly. It relies entirely on Gate
+    to route the requested action.
+    """
+
+    def __init__(self, *, gate_client: GateClient, source_node: str) -> None:
+        normalized_source = source_node.strip().lower()
+        if not normalized_source:
+            raise ValueError("source_node must not be empty")
+
+        self._gate_client = gate_client
+        self._source_node = normalized_source
+
+    @property
+    def source_node(self) -> str:
+        return self._source_node
+
+    async def execute_step(
+        self,
+        *,
+        parent: TransportPacket,
+        action: str,
+        payload: dict[str, Any],
+        retry_policy: RetryPolicy | None = None,
+    ) -> TransportPacket:
+        """
+        Execute a single orchestrator step through Gate with optional retries.
+        """
+        policy = retry_policy or RetryPolicy()
+        last_error: Exception | None = None
+
+        for attempt in range(1, policy.max_attempts + 1):
+            step_packet = build_step_packet(
+                parent=parent,
+                action=action,
+                payload=payload,
+                source_node=self._source_node,
+                reply_to=self._source_node,
+            )
+
+            try:
+                response = await self._gate_client.send_to_gate(step_packet)
+                _ensure_success_response(response)
+                return response
+            except Exception as exc:  # noqa: BLE001
+                last_error = exc
+                if not should_retry(attempt=attempt, error=exc, policy=policy):
+                    break
+                delay = policy.delay_for_attempt(attempt)
+                if delay > 0:
+                    await asyncio.sleep(delay)
+
+        message = f"step execution failed for action={action!r}"
+        if last_error is not None:
+            raise StepExecutionError(message) from last_error
+        raise StepExecutionError(message)
+
+
+def _ensure_success_response(packet: TransportPacket) -> None:
+    packet_type = packet.header.packet_type
+    if packet_type == "failure":
+        raise StepExecutionError("Gate returned a failure packet")
+
+    payload_status = str(packet.payload.get("status", "completed")).strip().lower()
+    if payload_status in {"failed", "failure", "error"}:
+        raise StepExecutionError("step response payload indicates failure")

constellation_node_sdk/runtime/__init__.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from constellation_node_sdk.runtime.app import create_node_app
+from constellation_node_sdk.runtime.config import NodeRuntimeConfig, get_runtime_config
+from constellation_node_sdk.runtime.errors import (
+    RuntimeConfigurationError,
+    RuntimeErrorDetail,
+    RuntimeExecutionError,
+    RuntimeValidationError,
+    classify_exception,
+    raise_http_exception,
+)
+from constellation_node_sdk.runtime.execution import (
+    create_error_transport_packet,
+    execute_transport_packet,
+)
+from constellation_node_sdk.runtime.handlers import (
+    clear_handlers,
+    get_handler,
+    register_handler,
+    registered_actions,
+)
+from constellation_node_sdk.runtime.inbound_policy import (
+    validate_execute_ingress_packet,
+    validate_relay_ingress_packet,
+)
+from constellation_node_sdk.runtime.lifecycle import LifecycleHook, NoOpLifecycle
+from constellation_node_sdk.runtime.preflight import PreflightFailure, run_preflight
+
+__all__ = [
+    "LifecycleHook",
+    "NoOpLifecycle",
+    "NodeRuntimeConfig",
+    "PreflightFailure",
+    "RuntimeConfigurationError",
+    "RuntimeErrorDetail",
+    "RuntimeExecutionError",
+    "RuntimeValidationError",
+    "classify_exception",
+    "clear_handlers",
+    "create_error_transport_packet",
+    "create_node_app",
+    "execute_transport_packet",
+    "validate_execute_ingress_packet",
+    "validate_relay_ingress_packet",
+    "get_handler",
+    "get_runtime_config",
+    "raise_http_exception",
+    "register_handler",
+    "registered_actions",
+    "run_preflight",
+]