openbox-temporal-sdk-python 1.1.0__py3-none-any.whl → 1.1.2__py3-none-any.whl

openbox/__init__.py

@@ -67,6 +67,17 @@ from .span_processor import WorkflowSpanProcessor
 
 from .workflow_interceptor import GovernanceInterceptor
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# Plugin (requires temporalio >= 1.23.0)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+try:
+    from temporalio.plugin import SimplePlugin  # noqa: F401 — probe only
+
+    from .plugin import OpenBoxPlugin
+except ImportError:
+    pass  # temporalio < 1.23.0, plugin not available
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # Verdict Handler
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -128,6 +139,8 @@ from .client import GovernanceClient
 __all__ = [
     # Simple Worker Factory (recommended)
     "create_openbox_worker",
+    # Plugin (recommended for temporalio >= 1.23.0)
+    "OpenBoxPlugin",
     # Configuration
     "initialize",
     "get_global_config",

openbox/activities.py

@@ -70,7 +70,9 @@ async def _terminate_workflow_for_halt(workflow_id: str, reason: str) -> None:
         except Exception as e:
             logger.warning(f"HALT: failed to terminate workflow {workflow_id}: {e}")
     else:
-        logger.warning(f"HALT: _temporal_client is None, cannot terminate workflow {workflow_id}")
+        logger.warning(
+            f"HALT: _temporal_client is None, cannot terminate workflow {workflow_id}"
+        )
 
     # Always raise to stop the current activity execution.
     # Even after successful terminate(), the activity code keeps running
@@ -82,7 +84,9 @@ async def _terminate_workflow_for_halt(workflow_id: str, reason: str) -> None:
     )
 
 
-def raise_governance_block(reason: str, policy_id: str = None, risk_score: float = None):
+def raise_governance_block(
+    reason: str, policy_id: str = None, risk_score: float = None
+):
     """Raise non-retryable ApplicationError for BLOCK verdict — blocks activity only."""
     details = {"policy_id": policy_id, "risk_score": risk_score}
     raise ApplicationError(
@@ -93,106 +97,154 @@ def raise_governance_block(reason: str, policy_id: str = None, risk_score: float
     )
 
 
-@activity.defn(name="send_governance_event")
-async def send_governance_event(input: Dict[str, Any]) -> Optional[Dict[str, Any]]:
-    """
-    Activity that sends governance events to OpenBox Core.
+def _build_verdict_result(verdict: Verdict, reason, policy_id, risk_score) -> dict:
+    """Build a success result dict from a governance verdict."""
+    return {
+        "success": True,
+        "verdict": verdict.value,
+        "action": verdict.value,  # backward compat
+        "reason": reason,
+        "policy_id": policy_id,
+        "risk_score": risk_score,
+    }
+
+
+async def _handle_stop_verdict(
+    verdict: Verdict, reason, policy_id, risk_score, event_type, event_payload
+) -> Optional[dict]:
+    """Handle BLOCK/HALT verdicts. Returns result for signals, raises for others."""
+    logger.info(
+        f"Governance {verdict.value} {event_type}: {reason} (policy: {policy_id})"
+    )
+
+    # SignalReceived: return result instead of raising
+    if event_type == "SignalReceived":
+        return _build_verdict_result(verdict, reason, policy_id, risk_score)
+
+    # HALT: terminate workflow + raise
+    if verdict == Verdict.HALT:
+        workflow_id = event_payload.get("workflow_id", "")
+        await _terminate_workflow_for_halt(workflow_id, reason or "No reason provided")
+
+    # BLOCK: fail this activity only
+    raise_governance_block(
+        reason=reason or "No reason provided",
+        policy_id=policy_id,
+        risk_score=risk_score,
+    )
+
 
-    This activity is called from WorkflowInboundInterceptor via workflow.execute_activity()
-    to maintain workflow determinism. HTTP calls cannot be made directly in workflow context.
+def _handle_api_error(event_type: str, error_msg: str, on_api_error: str) -> dict:
+    """Handle non-200 responses or exceptions based on error policy."""
+    logger.warning(f"Governance API error for {event_type}: {error_msg}")
+    if on_api_error == "fail_closed":
+        raise GovernanceAPIError(error_msg)
+    return {"success": False, "error": error_msg}
 
-    Args (in input dict):
-        api_url: OpenBox Core API URL
-        api_key: API key for authentication
-        payload: Event payload (without timestamp)
-        timeout: Request timeout in seconds
-        on_api_error: "fail_open" (default) or "fail_closed"
 
-    When on_api_error == "fail_closed" and API fails, raises GovernanceAPIError.
-    This is caught by the workflow interceptor and re-raised as GovernanceHaltError.
+class GovernanceActivities:
+    """Container for Temporal activities that need OpenBox credentials.
 
-    Logging is safe here because activities run outside the workflow sandbox.
+    Credentials live on the instance (never in activity inputs → never in
+    workflow history → not visible to anyone with namespace read access).
+    The worker registers bound methods of a single instance, created at
+    worker-init time by the plugin / create_openbox_worker factory.
     """
-    # Extract input fields
-    api_url = input.get("api_url", "")
-    api_key = input.get("api_key", "")
-    event_payload = input.get("payload", {})
-    timeout = input.get("timeout", 30.0)
-    on_api_error = input.get("on_api_error", "fail_open")
-
-    # Add timestamp here in activity context (non-deterministic code allowed)
-    # Use RFC3339 format: 2024-01-15T10:30:45.123Z
-    payload = {**event_payload, "timestamp": _rfc3339_now()}
-    event_type = event_payload.get("event_type", "unknown")
-
-    try:
-        async with httpx.AsyncClient(timeout=timeout) as client:
-            response = await client.post(
-                f"{api_url}/api/v1/governance/evaluate",
-                json=payload,
-                headers=build_auth_headers(api_key),
-            )
-
-            if response.status_code == 200:
+
+    def __init__(self, api_url: str, api_key: str):
+        self._api_url = api_url.rstrip("/")
+        self._api_key = api_key
+
+    @activity.defn(name="send_governance_event")
+    async def send_governance_event(
+        self, input: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """Send a governance event to OpenBox Core.
+
+        Called from WorkflowInboundInterceptor via workflow.execute_activity()
+        to maintain workflow determinism. The `input` dict carries only the
+        event payload and per-call policy — never credentials.
+        """
+        event_payload = input.get("payload", {})
+        timeout = input.get("timeout", 30.0)
+        on_api_error = input.get("on_api_error", "fail_open")
+
+        # Add timestamp in activity context (non-deterministic code allowed)
+        payload = {**event_payload, "timestamp": _rfc3339_now()}
+        event_type = event_payload.get("event_type", "unknown")
+
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as client:
+                response = await client.post(
+                    f"{self._api_url}/api/v1/governance/evaluate",
+                    json=payload,
+                    headers=build_auth_headers(self._api_key),
+                )
+
+                if response.status_code != 200:
+                    return _handle_api_error(
+                        event_type,
+                        f"HTTP {response.status_code}: {response.text}",
+                        on_api_error,
+                    )
+
                 data = response.json()
-                # Parse verdict (v1.1) or action (v1.0)
-                verdict = Verdict.from_string(data.get("verdict") or data.get("action", "continue"))
+                verdict = Verdict.from_string(
+                    data.get("verdict") or data.get("action", "continue")
+                )
                 reason = data.get("reason")
                 policy_id = data.get("policy_id")
                 risk_score = data.get("risk_score", 0.0)
 
-                # Check if governance wants to stop (BLOCK or HALT)
                 if verdict.should_stop():
-                    logger.info(f"Governance {verdict.value} {event_type}: {reason} (policy: {policy_id})")
-
-                    # For SignalReceived events, return result instead of raising/terminating
-                    # The workflow interceptor will store verdict for activity interceptor to check
-                    if event_type == "SignalReceived":
-                        return {
-                            "success": True,
-                            "verdict": verdict.value,
-                            "action": verdict.value,  # backward compat
-                            "reason": reason,
-                            "policy_id": policy_id,
-                            "risk_score": risk_score,
-                        }
-
-                    # HALT → terminate workflow + raise to stop activity
-                    if verdict == Verdict.HALT:
-                        workflow_id = event_payload.get("workflow_id", "")
-                        # Always raises ApplicationError(type="GovernanceHalt")
-                        await _terminate_workflow_for_halt(
-                            workflow_id, reason or "No reason provided"
-                        )
-                    else:
-                        # BLOCK → fail this activity only, workflow can continue
-                        raise_governance_block(
-                            reason=reason or "No reason provided",
-                            policy_id=policy_id,
-                            risk_score=risk_score,
-                        )
-
-                return {
-                    "success": True,
-                    "verdict": verdict.value,
-                    "action": verdict.value,  # backward compat
-                    "reason": reason,
-                    "policy_id": policy_id,
-                    "risk_score": risk_score,
-                }
-            else:
-                error_msg = f"HTTP {response.status_code}: {response.text}"
-                logger.warning(f"Governance API error for {event_type}: {error_msg}")
-                if on_api_error == "fail_closed":
-                    raise GovernanceAPIError(error_msg)
-                return {"success": False, "error": error_msg}
-
-    except (GovernanceAPIError, ApplicationError):
-        raise  # Re-raise to workflow (ApplicationError is non-retryable)
-    except Exception as e:
-        logger.warning(f"Failed to send {event_type} event: {e}")
-        if on_api_error == "fail_closed":
-            raise GovernanceAPIError(str(e))
-        return {"success": False, "error": str(e)}
+                    result = await _handle_stop_verdict(
+                        verdict,
+                        reason,
+                        policy_id,
+                        risk_score,
+                        event_type,
+                        event_payload,
+                    )
+                    if result:
+                        return result
+
+                return _build_verdict_result(verdict, reason, policy_id, risk_score)
+
+        except (GovernanceAPIError, ApplicationError):
+            raise
+        except Exception as e:
+            logger.warning(f"Failed to send {event_type} event: {e}")
+            if on_api_error == "fail_closed":
+                raise GovernanceAPIError(str(e))
+            return {"success": False, "error": str(e)}
+
+
+def build_governance_activities(
+    api_url: str, api_key: str
+) -> GovernanceActivities:
+    """Factory used by plugin.py and worker.py to build the activities instance."""
+    return GovernanceActivities(api_url=api_url, api_key=api_key)
 
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Backward-compat module-level helper.
+#
+# Not decorated with @activity.defn — worker/plugin register the class-based
+# version above so credentials never flow through activity inputs. This shim
+# exists for direct callers (tests, scripts) who already hold credentials and
+# want to invoke the HTTP logic without constructing the class themselves.
+# ─────────────────────────────────────────────────────────────────────────────
+async def send_governance_event(input: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """Backward-compat wrapper — delegates to GovernanceActivities.
+
+    Tests and direct callers can keep passing api_url/api_key in the input
+    dict. The class-based activity registered with the worker does NOT see
+    these fields (it reads credentials from self), so nothing written to
+    workflow history ever carries the API key.
+    """
+    instance = GovernanceActivities(
+        api_url=input.get("api_url", ""),
+        api_key=input.get("api_key", ""),
+    )
+    forwarded = {k: v for k, v in input.items() if k not in ("api_url", "api_key")}
+    return await instance.send_governance_event(forwarded)