velophex 0.2.0__py3-none-any.whl

velophex/runtime/__init__.py

@@ -0,0 +1,471 @@
+"""What a running automation can ask the platform for.
+
+Two things live here:
+
+* the **ambient run** - :func:`stop_requested`, :func:`stop_reason`, :func:`context` - which
+  the worker installs around the handler, and
+* the **Runtime API** - :func:`client` and the typed helpers below - which reaches the
+  Orchestrator for assets, secrets, credentials, queues, storage buckets, logs and child jobs.
+
+Both need a real run: outside one (a unit test, an import) :func:`context` returns ``None``
+and :func:`client` raises. Nothing here reads the environment for credentials; the execution
+token arrives in the ``start`` context and stays in memory (ADR-P005).
+
+    >>> from velophex import runtime
+    >>>
+    >>> api_key = runtime.secret("ErpApiKey")
+    >>> while not runtime.stop_requested():
+    ...     item = runtime.claim_queue_item("Invoices")
+    ...     if item is None:
+    ...         break
+    >>>
+    >>> for file in runtime.list_files("Invoices", "inbox", pattern="*.pdf"):
+    ...     runtime.download_file("Invoices", file.path, f"C:/work/{file.name}")
+"""
+
+from __future__ import annotations
+
+import sys
+from collections import Counter
+from datetime import datetime
+from os import PathLike
+from pathlib import Path
+from typing import Any
+from uuid import UUID
+
+from velophex.contracts.executor import ExecutionContextInfo, SubResultMessage
+from velophex.errors import VelophexError
+from velophex.runtime._session import RunSession, clear_session, current_session, set_session
+from velophex.runtime.client import (
+    ActionAppNotFoundError,
+    ActionHubDisabledError,
+    ActionHubError,
+    ActionHubRuntimeUnsupportedError,
+    ActionTaskCorrelationConflictError,
+    ActionTaskInputInvalidError,
+    ActionTaskNotFoundError,
+    ActionTaskNotOwnedError,
+    ActionTaskTimeoutError,
+    AgentsNotEnabledError,
+    AiBudgetExhaustedError,
+    AiError,
+    AiPolicyDeniedError,
+    AiProviderUnavailableError,
+    AiRequestInvalidError,
+    RuntimeApiError,
+    RuntimeClient,
+    StorageBucketsUnsupportedError,
+    runtime_base_url,
+)
+from velophex.runtime.models import (
+    ActionAppSchema,
+    ActionTaskCompleter,
+    ActionTaskResult,
+    AddQueueItemRequest,
+    CancellationState,
+    QueueItem,
+    ResolvedSecret,
+    RuntimeActionTask,
+    RuntimeAsset,
+    RuntimeContext,
+    RuntimeCredential,
+    RuntimeJob,
+    RuntimeQueue,
+    StartedJob,
+    StorageFile,
+    StorageFileList,
+)
+
+__all__ = [
+    "ActionAppNotFoundError",
+    "ActionAppSchema",
+    "ActionHubDisabledError",
+    "ActionHubError",
+    "ActionHubRuntimeUnsupportedError",
+    "ActionTaskCompleter",
+    "ActionTaskCorrelationConflictError",
+    "ActionTaskInputInvalidError",
+    "ActionTaskNotFoundError",
+    "ActionTaskNotOwnedError",
+    "ActionTaskResult",
+    "ActionTaskTimeoutError",
+    "AddQueueItemRequest",
+    "AgentsNotEnabledError",
+    "AiBudgetExhaustedError",
+    "AiError",
+    "AiPolicyDeniedError",
+    "AiProviderUnavailableError",
+    "AiRequestInvalidError",
+    "CancellationState",
+    "QueueItem",
+    "ResolvedSecret",
+    "RunSession",
+    "RuntimeActionTask",
+    "RuntimeApiError",
+    "RuntimeAsset",
+    "RuntimeClient",
+    "RuntimeContext",
+    "RuntimeCredential",
+    "RuntimeJob",
+    "RuntimeQueue",
+    "StartedJob",
+    "StorageBucketsUnsupportedError",
+    "StorageFile",
+    "StorageFileList",
+    "add_queue_item",
+    "asset",
+    "claim_queue_item",
+    "clear_session",
+    "client",
+    "complete_queue_item",
+    "context",
+    "create_action_task",
+    "credential",
+    "current_session",
+    "delete_file",
+    "download_file",
+    "fail_queue_item",
+    "get_action_task",
+    "invoke_automation",
+    "list_files",
+    "list_jobs",
+    "queue",
+    "raise_alert",
+    "read_text",
+    "runtime_base_url",
+    "secret",
+    "set_asset",
+    "set_session",
+    "should_stop",
+    "start_job",
+    "stop_job",
+    "stop_reason",
+    "stop_requested",
+    "upload_file",
+    "wait_for_action_task",
+    "write_text",
+]
+
+
+def context() -> ExecutionContextInfo | None:
+    """The ``start`` context of this run, without the execution token, or ``None`` outside a run."""
+    session = current_session()
+    return session.context.redacted() if session is not None else None
+
+
+def stop_requested() -> bool:
+    """True once the parent asked this run to end.
+
+    A long-running automation is expected to poll this between units of work: the platform
+    never interrupts Python code on its own, it asks, waits out the grace period and then
+    kills the process tree.
+    """
+    session = current_session()
+    return session.stop_requested if session is not None else False
+
+
+def should_stop() -> bool:
+    """True once the parent asked this run to finish its current work and end.
+
+    An operator's Stop arrives first as ``request-stop``, which only raises this flag, and only
+    later, if the run has not ended, as ``stop``; this is true after either. Unlike
+    :func:`stop_requested`, a run that ends normally after a ``request-stop`` still succeeds.
+    The Python twin of the workflow Should Stop activity (engine ADR 0037 section 6).
+    """
+    session = current_session()
+    return session.should_stop if session is not None else False
+
+
+def stop_reason() -> str | None:
+    """``User`` or ``Timeout`` once a stop was asked for, else ``None``."""
+    session = current_session()
+    return session.stop_reason if session is not None else None
+
+
+def client() -> RuntimeClient:
+    """The Runtime API client for this attempt."""
+    session = current_session()
+
+    if session is None:
+        raise VelophexError("There is no VeloPhex run in this process; the Runtime API is only available to a handler.")
+
+    return session.client()
+
+
+def invoke_automation(
+    package_id: str,
+    inputs: dict[str, Any] | None = None,
+    *,
+    entry_point: str | None = None,
+    timeout_seconds: int | None = None,
+) -> SubResultMessage:
+    """Run another published automation as a step of this job and return its outcome.
+
+    The Robot runs it on this machine under this job's lease, token and deadline (a hybrid step,
+    ADR-P007): it takes no robot slot of its own, so it cannot wait behind the job that asked
+    for it. The package must be pinned for this job by the Orchestrator. The result carries
+    ``outcome`` (``Succeeded``, ``Failed`` or ``Canceled``), ``outputs`` and the step's ``fault``.
+    """
+    session = current_session()
+
+    if session is None:
+        raise VelophexError("There is no VeloPhex run in this process; steps are only available to a handler.")
+
+    return session.invoke(package_id, inputs, entry_point, timeout_seconds)
+
+
+def asset(name: str) -> RuntimeAsset:
+    """Read an asset of the job's workspace."""
+    return client().asset(name)
+
+
+def set_asset(name: str, **value: Any) -> None:
+    """Set an asset the job's workspace owns, e.g. ``set_asset("LastRun", text="ok")``."""
+    client().set_asset(name, **value)
+
+
+def secret(name: str) -> str:
+    """Resolve a secret asset, or ``"<credential>.password"`` for a credential's password.
+
+    Returns the plain text, because that is what a caller passes on to the system it logs in
+    to. :meth:`RuntimeClient.resolve_secret` returns the :class:`ResolvedSecret` instead, whose
+    ``value`` is a ``SecretStr`` that prints as ``**********``.
+    """
+    return client().resolve_secret(name).get_secret_value()
+
+
+def credential(name: str) -> RuntimeCredential:
+    """The account name of a credential asset; the password comes from :func:`secret`."""
+    return client().credential(name)
+
+
+def queue(name: str) -> RuntimeQueue:
+    """Queue metadata by name."""
+    return client().queue(name)
+
+
+def add_queue_item(
+    queue_name: str,
+    payload: Any | None = None,
+    *,
+    reference: str | None = None,
+    priority: int | None = None,
+    deadline: datetime | None = None,
+    defer_until: datetime | None = None,
+) -> QueueItem:
+    """Add an item to a queue of the job's workspace."""
+    request = AddQueueItemRequest(
+        reference=reference,
+        priority=priority,
+        payload=payload,
+        deadline=deadline,
+        deferUntil=defer_until,
+    )
+
+    return client().add_queue_item(queue_name, request)
+
+
+def claim_queue_item(queue_name: str) -> QueueItem | None:
+    """Claim the next item of a queue, or ``None`` when nothing is due."""
+    return client().claim_queue_item(queue_name)
+
+
+def complete_queue_item(item_id: UUID | str, output: Any | None = None) -> QueueItem:
+    """Mark a claimed item successful."""
+    return client().complete_queue_item(item_id, output)
+
+
+def fail_queue_item(
+    item_id: UUID | str,
+    *,
+    kind: str,
+    reason: str | None = None,
+    output: Any | None = None,
+) -> QueueItem:
+    """Mark a claimed item failed: ``Business`` is final, ``Application`` is retried."""
+    return client().fail_queue_item(item_id, kind=kind, reason=reason, output=output)
+
+
+def start_job(
+    *,
+    automation_id: UUID | str | None = None,
+    automation_name: str | None = None,
+    inputs: Any | None = None,
+    priority: int | None = None,
+) -> StartedJob:
+    """Start a child automation in this job's workspace."""
+    return client().start_job(
+        automation_id=automation_id,
+        automation_name=automation_name,
+        inputs=inputs,
+        priority=priority,
+    )
+
+
+def list_jobs(
+    *,
+    automation_name: str | None = None,
+    statuses: list[str] | None = None,
+    top: int = 50,
+) -> list[RuntimeJob]:
+    """The newest jobs of this job's workspace (at most 100)."""
+    return client().list_jobs(automation_name=automation_name, statuses=statuses, top=top)
+
+
+def stop_job(job_id: UUID | str, *, kill: bool = False) -> None:
+    """Ask a job of this workspace to stop, or with ``kill`` end it at once."""
+    client().stop_job(job_id, kill=kill)
+
+
+def raise_alert(message: str, *, severity: str = "Info") -> None:
+    """Raise an alert (``Info``, ``Warning`` or ``Error``) tied to this job."""
+    client().raise_alert(message, severity=severity)
+
+
+#: Calls per call site in this process, so a loop raises one task per iteration while a retried
+#: attempt, which runs the same code again from the start, replays the same keys.
+_call_sites: Counter[str] = Counter()
+
+
+def create_action_task(
+    app_key: str,
+    version: int,
+    input: dict[str, Any] | None = None,
+    *,
+    correlation_key: str | None = None,
+    title: str | None = None,
+    assignee_user_id: UUID | str | None = None,
+    assignee_group: str | None = None,
+    due_at: datetime | None = None,
+    priority: str | None = None,
+) -> UUID:
+    """Raise an Action Hub task from a published app version and return its id.
+
+    >>> task_id = runtime.create_action_task("approval", 1, {"title": "Laptop", "amount": 1200})
+
+    ``correlation_key`` defaults to the call site and how many times it ran in this process, so a
+    retried attempt gets the same task back instead of raising a second one (see
+    ``docs/action-hub.md``, "Correlation keys").
+    """
+    if correlation_key is None:
+        caller = sys._getframe(1)
+        site = f"{caller.f_code.co_filename}:{caller.f_lineno}"
+        _call_sites[site] += 1
+        correlation_key = f"py:{site.rsplit('/', 1)[-1].rsplit(chr(92), 1)[-1]}#{_call_sites[site]}"
+
+    return client().create_action_task(
+        app_key,
+        version,
+        input,
+        correlation_key=correlation_key,
+        title=title,
+        assignee_user_id=assignee_user_id,
+        assignee_group=assignee_group,
+        due_at=due_at,
+        priority=priority,
+    )
+
+
+def get_action_task(task_id: UUID | str) -> RuntimeActionTask:
+    """Read an action task this job created: status, and outcome and output once completed."""
+    return client().get_action_task(task_id)
+
+
+def wait_for_action_task(
+    task_id: UUID | str,
+    *,
+    timeout: float = 900.0,
+    raise_on_timeout: bool = False,
+) -> ActionTaskResult:
+    """Wait in the job for the task's decision; ``timedOut`` (task left open) after ``timeout`` seconds.
+
+    The default is 15 minutes, and the wait never runs past the job's deadline or a stop request.
+    This always waits in the job and holds the Robot: a Python job cannot be checkpointed, so it
+    cannot suspend the way the XAML Wait for Action Task does past 60 minutes. For waits of hours
+    or days give the app a continuation automation.
+    """
+    session = current_session()
+    deadline = session.context.deadline if session is not None else None
+
+    return client().wait_for_action_task(
+        task_id,
+        timeout=timeout,
+        raise_on_timeout=raise_on_timeout,
+        deadline=deadline,
+        stop_requested=stop_requested,
+    )
+
+
+# ---------------------------------------------------------------------------------------------
+# Storage buckets: the Python twins of the Upload File, Download File, List Files, Delete File,
+# Read Text and Write Text activities (velophex.orchestrator.storage.*). A bucket is named; it is
+# the job's workspace's own or one shared into it, and "default" always exists. Paths use "/".
+# ---------------------------------------------------------------------------------------------
+
+
+def upload_file(
+    bucket: str,
+    local_path: str | PathLike[str],
+    path: str | None = None,
+    *,
+    content_type: str | None = None,
+) -> StorageFile:
+    """Upload a local file to ``path`` in ``bucket`` (its own name at the root when ``path`` is ``None``).
+
+    An existing path gets a new version in an internal bucket; the bucket's size limit (at most
+    100 MiB) and quotas apply.
+    """
+    source = Path(local_path)
+
+    with source.open("rb") as content:
+        return client().upload_file(bucket, path or source.name, content, content_type=content_type)
+
+
+def download_file(bucket: str, path: str, local_path: str | PathLike[str]) -> Path:
+    """Download ``path`` from ``bucket`` to ``local_path`` (folders are created); returns the local path.
+
+    A failed download leaves no partial file behind.
+    """
+    target = Path(local_path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    partial = target.with_name(target.name + ".partial")
+
+    try:
+        with partial.open("wb") as destination:
+            client().download_file(bucket, path, destination)
+
+        partial.replace(target)
+    finally:
+        partial.unlink(missing_ok=True)
+
+    return target
+
+
+def list_files(
+    bucket: str,
+    prefix: str | None = None,
+    *,
+    pattern: str | None = None,
+    recursive: bool = False,
+) -> list[StorageFile]:
+    """Every file under ``prefix`` (the root when ``None``), across all pages.
+
+    ``pattern`` is ``*``/``?`` wildcards on the file name, several separated by ``;``
+    (``"*.pdf;*.xlsx"``). ``recursive`` includes every folder below ``prefix``.
+    """
+    return list(client().iter_files(bucket, prefix, pattern=pattern, recursive=recursive))
+
+
+def delete_file(bucket: str, path: str) -> None:
+    """Delete ``path`` from ``bucket``; :class:`RuntimeApiError` ``storage_file_not_found`` when absent."""
+    client().delete_file(bucket, path)
+
+
+def read_text(bucket: str, path: str, *, encoding: str = "utf-8") -> str:
+    """The text of ``path`` in ``bucket``."""
+    return client().read_file(bucket, path).decode(encoding)
+
+
+def write_text(bucket: str, path: str, text: str, *, encoding: str = "utf-8") -> StorageFile:
+    """Store ``text`` at ``path`` in ``bucket`` as a ``text/plain`` file in ``encoding``."""
+    return client().upload_file(bucket, path, text.encode(encoding), content_type=f"text/plain; charset={encoding}")

velophex/runtime/_session.py

@@ -0,0 +1,192 @@
+"""The ambient run an automation can ask about: stop requests, context and the API client.
+
+The worker installs exactly one :class:`RunSession` for the life of the process and tears it
+down afterwards, so :func:`velophex.runtime.stop_requested` and friends work without the
+handler threading anything through its own call stack. A module-level object rather than a
+:class:`contextvars.ContextVar` is deliberate: one process runs one automation (ADR-P005), and
+a worker thread the handler starts must see the same stop flag as the handler itself.
+"""
+
+from __future__ import annotations
+
+import threading
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from velophex.contracts.executor import ExecutionContextInfo, SubInvokeMessage, SubResultMessage
+from velophex.entrypoints import EntryPointDefinition
+from velophex.errors import VelophexError
+from velophex.runtime.client import RuntimeClient
+
+__all__ = ["RunSession", "clear_session", "current_session", "set_session"]
+
+
+@dataclass
+class RunSession:
+    """One automation run, as the handler may observe it."""
+
+    context: ExecutionContextInfo
+    entry_point: EntryPointDefinition | None
+    package_root: str
+    _stop: threading.Event
+    _stop_reason: str | None = None
+    _client: RuntimeClient | None = None
+    _should_stop: bool = False
+    _send_sub_invoke: Callable[[SubInvokeMessage], None] | None = None
+    _pending: dict[str, list[Any]] = field(default_factory=dict)
+    _pending_lock: threading.Lock = field(default_factory=threading.Lock)
+
+    @classmethod
+    def create(
+        cls,
+        context: ExecutionContextInfo,
+        entry_point: EntryPointDefinition | None,
+        package_root: str,
+    ) -> RunSession:
+        """Start a session for one ``start`` message."""
+        return cls(context=context, entry_point=entry_point, package_root=package_root, _stop=threading.Event())
+
+    @property
+    def stop_requested(self) -> bool:
+        """True once the parent asked the run to end."""
+        return self._stop.is_set()
+
+    @property
+    def stop_reason(self) -> str | None:
+        """``User`` or ``Timeout`` once a stop was asked for."""
+        return self._stop_reason
+
+    def request_stop(self, reason: str) -> None:
+        """Record a stop request. Called by the worker when a ``stop`` frame arrives."""
+        self._stop_reason = reason
+        self._stop.set()
+
+    @property
+    def should_stop(self) -> bool:
+        """True once the parent asked the run to finish its work and end, or to end now."""
+        return self._should_stop or self._stop.is_set()
+
+    def request_soft_stop(self) -> None:
+        """Record a ``request-stop``: the automation should end on its own.
+
+        Nothing is canceled, and a run that then returns normally still succeeds (engine ADR
+        0037 section 6).
+        """
+        self._should_stop = True
+
+    def wait_for_stop(self, timeout: float | None = None) -> bool:
+        """Block until a stop is requested or *timeout* seconds elapse."""
+        return self._stop.wait(timeout)
+
+    def enable_sub_invoke(self, send: Callable[[SubInvokeMessage], None]) -> None:
+        """Let the run ask the parent for steps; the worker calls it when the parent serves them."""
+        self._send_sub_invoke = send
+
+    def invoke(
+        self,
+        package_id: str,
+        inputs: Any | None,
+        entry_point_id: str | None,
+        timeout_seconds: int | None,
+    ) -> SubResultMessage:
+        """Run a published automation as a step of this job and block until its ``sub-result``.
+
+        The parent (the Robot) runs it on this machine, under this job's lease, token and
+        deadline, without a slot of its own. It always answers, also when the job is stopped
+        (``Canceled``), so the wait is not bounded here.
+        """
+        if self._send_sub_invoke is None:
+            raise VelophexError(
+                "This run cannot invoke another automation: the parent does not serve sub-invoke "
+                "(a local velophex run, or a Robot that predates it)."
+            )
+
+        request_id = uuid.uuid4().hex
+        slot: list[Any] = [threading.Event(), None]
+
+        with self._pending_lock:
+            self._pending[request_id] = slot
+
+        self._send_sub_invoke(SubInvokeMessage(request_id, package_id, entry_point_id, inputs, timeout_seconds))
+        slot[0].wait()
+
+        with self._pending_lock:
+            self._pending.pop(request_id, None)
+
+        if isinstance(slot[1], BaseException):
+            raise slot[1]
+
+        return slot[1]
+
+    def deliver(self, result: SubResultMessage) -> bool:
+        """Hand a ``sub-result`` to the call waiting for it; ``False`` for an id nobody is waiting for."""
+        with self._pending_lock:
+            slot = self._pending.get(result.request_id)
+
+            if slot is None or slot[0].is_set():
+                return False
+
+            slot[1] = result
+            slot[0].set()
+            return True
+
+    def fail_pending(self, reason: str) -> None:
+        """End every waiting step call with an error: the parent is gone or broke the protocol."""
+        with self._pending_lock:
+            for slot in self._pending.values():
+                if not slot[0].is_set():
+                    slot[1] = VelophexError(reason)
+                    slot[0].set()
+
+    def client(self) -> RuntimeClient:
+        """The Runtime API client for this attempt, created on first use.
+
+        Raises :class:`VelophexError` when the run has no Orchestrator behind it, which is
+        the case for ``velophex run`` and for Studio's local Run.
+        """
+        if self._client is None:
+            if not self.context.orchestrator_url or not self.context.runtime_token:
+                raise VelophexError(
+                    "This run has no Orchestrator: start context carries no orchestratorUrl or runtimeToken. "
+                    "Assets, queues and child jobs are only available for jobs dispatched by the Orchestrator."
+                )
+
+            self._client = RuntimeClient(
+                self.context.orchestrator_url,
+                self.context.runtime_token,
+                trace_parent=self.context.trace_parent,
+            )
+
+        return self._client
+
+    def close(self) -> None:
+        """Release the Runtime API connection pool."""
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+
+_current: RunSession | None = None
+
+
+def set_session(session: RunSession) -> None:
+    """Install the ambient session. The worker calls this once per ``start``."""
+    global _current
+    _current = session
+
+
+def clear_session() -> None:
+    """Remove the ambient session and close its client."""
+    global _current
+
+    if _current is not None:
+        _current.close()
+
+    _current = None
+
+
+def current_session() -> RunSession | None:
+    """The ambient session, or ``None`` outside a run."""
+    return _current