velophex 0.2.0__py3-none-any.whl

velophex/runtime/models.py

@@ -0,0 +1,326 @@
+"""Responses and requests of the Orchestrator Runtime API (``/api/v1/runtime/*``).
+
+Mirrors ``VeloPhex.Platform.Contracts.Runtime.RuntimeApiContracts`` and ``StorageContracts`` and
+the queue and asset contracts in ``VeloPhex.Orchestrator.Contracts``. Unknown members are kept, so a newer server
+never breaks an older automation.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Final
+from uuid import UUID
+
+from pydantic import ConfigDict, Field, SecretStr
+
+from velophex.contracts._model import ContractModel
+
+__all__ = [
+    "STORAGE_BUCKETS_CAPABILITY",
+    "STORAGE_ERROR_CODES",
+    "ActionAppSchema",
+    "ActionTaskCompleter",
+    "ActionTaskResult",
+    "AddQueueItemRequest",
+    "CancellationState",
+    "QueueItem",
+    "ResolvedSecret",
+    "RuntimeActionTask",
+    "RuntimeAsset",
+    "RuntimeContext",
+    "RuntimeCredential",
+    "RuntimeQueue",
+    "StartedJob",
+    "StorageFile",
+    "StorageFileList",
+    "StorageLink",
+    "StorageLinkRequest",
+]
+
+
+class RuntimeContext(ContractModel):
+    """What the Orchestrator knows about the attempt this process is running."""
+
+    job_id: UUID = Field(alias="jobId")
+    attempt_id: UUID = Field(alias="attemptId")
+    attempt_number: int = Field(alias="attemptNumber")
+    tenant_id: UUID = Field(alias="tenantId")
+    workspace_id: UUID = Field(alias="workspaceId")
+    automation_id: UUID = Field(alias="automationId")
+    automation_name: str = Field(alias="automationName")
+    entry_point_id: str = Field(alias="entryPointId")
+    inputs: Any | None = None
+    execution_deadline: datetime = Field(alias="executionDeadline")
+
+
+class CancellationState(ContractModel):
+    """Whether a stop was requested for this attempt, and why."""
+
+    cancel_requested: bool = Field(alias="cancelRequested")
+    reason: str | None = None
+
+
+#: Settings for a model that carries a decrypted secret.
+#:
+#: * ``hide_input_in_errors``: a :class:`pydantic.ValidationError` otherwise prints the whole
+#:   input document - every sibling member, the secret included - in its message, and that
+#:   message is exactly what ends up in a log or a fault.
+#: * ``extra="ignore"``: unlike other contract models, an unknown member is *dropped*. A newer
+#:   server may add a confidential member this SDK does not know to wrap, and a plain ``str``
+#:   in the extras would print in every ``repr``.
+_SECRET_BEARING = ConfigDict(hide_input_in_errors=True, extra="ignore")
+
+
+class RuntimeAsset(ContractModel):
+    """An asset of the job's workspace, with the secret or password already decrypted.
+
+    ``secret`` and ``password`` are :class:`pydantic.SecretStr`: ``repr``, ``str`` and
+    ``model_dump`` show ``**********``. Read the plain text deliberately, with
+    ``asset.secret.get_secret_value()`` or :meth:`value`.
+    """
+
+    model_config = _SECRET_BEARING
+
+    name: str
+    type: str
+    text: str | None = None
+    integer: int | None = None
+    boolean: bool | None = None
+    secret: SecretStr | None = None
+    user_name: str | None = Field(default=None, alias="userName")
+    password: SecretStr | None = None
+
+    def value(self) -> Any:
+        """The one member the asset's type carries, as plain text for a secret or credential.
+
+        This is the explicit way to read a confidential value; keep the result out of logs.
+        """
+        return {
+            "Text": self.text,
+            "Integer": self.integer,
+            "Boolean": self.boolean,
+            "Secret": _reveal(self.secret),
+            "Credential": _reveal(self.password),
+        }.get(self.type)
+
+
+class ResolvedSecret(ContractModel):
+    """One confidential value: a secret asset, or a credential's password.
+
+    ``value`` is a :class:`pydantic.SecretStr`, so the model can be printed, logged or put in
+    an exception without the secret; :meth:`get_secret_value` returns the plain text.
+    """
+
+    model_config = _SECRET_BEARING
+
+    name: str
+    value: SecretStr
+    user_name: str | None = Field(default=None, alias="userName")
+
+    def get_secret_value(self) -> str:
+        """The plain text of the secret. Keep it out of logs, outputs and exceptions."""
+        return self.value.get_secret_value()
+
+
+def _reveal(value: SecretStr | None) -> str | None:
+    return value.get_secret_value() if value is not None else None
+
+
+class RuntimeCredential(ContractModel):
+    """A credential asset without its password."""
+
+    name: str
+    user_name: str = Field(alias="userName")
+    has_password: bool = Field(alias="hasPassword")
+
+
+class RuntimeQueue(ContractModel):
+    """Queue metadata by name, inside the job's workspace."""
+
+    id: UUID
+    number: int
+    name: str
+    description: str | None = None
+    max_retries: int = Field(alias="maxRetries")
+    enforce_unique_reference: bool = Field(alias="enforceUniqueReference")
+    is_active: bool = Field(alias="isActive")
+    sla_minutes: int | None = Field(default=None, alias="slaMinutes")
+    risk_sla_minutes: int | None = Field(default=None, alias="riskSlaMinutes")
+
+
+class AddQueueItemRequest(ContractModel):
+    """A new queue item."""
+
+    reference: str | None = None
+    priority: int | None = None
+    payload: Any | None = None
+    deadline: datetime | None = None
+    defer_until: datetime | None = Field(default=None, alias="deferUntil")
+
+
+class QueueItem(ContractModel):
+    """A queue item as the Orchestrator reports it.
+
+    Only the members an automation acts on are typed; everything else survives in the model's
+    extras, because the queue projection grows more often than the SDK ships.
+    """
+
+    id: UUID
+    number: int
+    queue_id: UUID = Field(alias="queueId")
+    reference: str | None = None
+    status: str
+    priority: int
+    payload: Any | None = None
+    output: Any | None = None
+    error_kind: str | None = Field(default=None, alias="errorKind")
+    error_reason: str | None = Field(default=None, alias="errorReason")
+    retry_count: int = Field(alias="retryCount")
+    deadline: datetime | None = None
+    defer_until: datetime | None = Field(default=None, alias="deferUntil")
+    progress: str | None = None
+    lease_expires_at: datetime | None = Field(default=None, alias="leaseExpiresAt")
+
+
+class StartedJob(ContractModel):
+    """A child job started from a running automation."""
+
+    job_id: UUID = Field(alias="jobId")
+    job_number: int = Field(alias="jobNumber")
+    automation_id: UUID = Field(alias="automationId")
+    automation_name: str = Field(alias="automationName")
+    status: str
+    chain_depth: int = Field(alias="chainDepth")
+
+
+class RuntimeJob(ContractModel):
+    """A job of the running automation's workspace (``GET /runtime/jobs``)."""
+
+    job_id: UUID = Field(alias="jobId")
+    job_number: int = Field(alias="jobNumber")
+    automation_id: UUID | None = Field(default=None, alias="automationId")
+    automation_name: str = Field(alias="automationName")
+    status: str
+    priority: int
+    created_at: datetime = Field(alias="createdAt")
+    started_at: datetime | None = Field(default=None, alias="startedAt")
+    finished_at: datetime | None = Field(default=None, alias="finishedAt")
+    parent_job_id: UUID | None = Field(default=None, alias="parentJobId")
+    fault_message: str | None = Field(default=None, alias="faultMessage")
+
+
+class ActionTaskCompleter(ContractModel):
+    """Who completed an action task."""
+
+    user_id: UUID = Field(alias="userId")
+    name: str | None = None
+
+
+class RuntimeActionTask(ContractModel):
+    """An action task as this job reads it (``ActionTaskState``).
+
+    ``status`` is ``unassigned``, ``in_progress``, ``completed`` or ``canceled``; ``outcome`` is
+    the action the completer chose and ``output`` their answer, both ``None`` until completed.
+    """
+
+    task_id: UUID = Field(alias="taskId")
+    app_key: str = Field(alias="appKey")
+    version: int
+    title: str
+    status: str
+    outcome: str | None = None
+    output: Any | None = None
+    completed_by: ActionTaskCompleter | None = Field(default=None, alias="completedBy")
+    completed_at: datetime | None = Field(default=None, alias="completedAt")
+    late: bool = False
+    automation_gone: bool = Field(default=False, alias="automationGone")
+    cancel_reason: str | None = Field(default=None, alias="cancelReason")
+    created_at: datetime | None = Field(default=None, alias="createdAt")
+    due_at: datetime | None = Field(default=None, alias="dueAt")
+
+
+class ActionTaskResult(ContractModel):
+    """What waiting for an action task ends with (``ActionTaskWaitResult``).
+
+    ``status`` is ``completed``, ``canceled`` or ``timedOut``; on ``timedOut`` the task stays open.
+    ``output`` may be ``None`` for an action that does not require a valid form.
+    """
+
+    task_id: UUID = Field(alias="taskId")
+    status: str
+    outcome: str | None = None
+    output: Any | None = None
+    completed_by: ActionTaskCompleter | None = Field(default=None, alias="completedBy")
+    completed_at: datetime | None = Field(default=None, alias="completedAt")
+    late: bool = False
+
+
+class ActionAppSchema(ContractModel):
+    """The input and output JSON Schema of a published action app version."""
+
+    app_key: str = Field(alias="appKey")
+    version: int
+    name: str
+    input_schema: dict[str, Any] = Field(alias="inputSchema")
+    output_schema: dict[str, Any] = Field(alias="outputSchema")
+    actions: list[dict[str, Any]] = Field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------------------------
+# Storage buckets (contracts 0.8.35, schemas/runtime-storage.schema.json)
+# ---------------------------------------------------------------------------------------------
+
+#: The runtime capability of the storage routes (``RuntimeCapabilities.StorageBuckets``).
+STORAGE_BUCKETS_CAPABILITY: Final = "storage-buckets/1"
+
+#: The problem ``code`` values of the storage routes (``StorageErrorCodes``), in contract order.
+STORAGE_ERROR_CODES: Final = (
+    "storage_bucket_not_found",
+    "storage_file_not_found",
+    "storage_bucket_read_only",
+    "storage_file_too_large",
+    "storage_quota_exceeded",
+    "storage_connection_failed",
+)
+
+
+class StorageFile(ContractModel):
+    """One file of a storage bucket (``RuntimeStorageFile``).
+
+    ``path`` is ``/``-separated with no leading slash; ``sha256`` and ``version`` are set where the
+    bucket knows them (internal buckets keep versions).
+    """
+
+    path: str
+    name: str
+    size_bytes: int = Field(alias="sizeBytes")
+    content_type: str = Field(alias="contentType")
+    last_modified: datetime = Field(alias="lastModified")
+    sha256: str | None = None
+    version: int | None = None
+
+
+class StorageFileList(ContractModel):
+    """A page of a bucket listing (``RuntimeStorageFileList``); ``folders`` on the first page only."""
+
+    files: list[StorageFile] = Field(default_factory=list)
+    folders: list[str] = Field(default_factory=list)
+    next_cursor: str | None = Field(default=None, alias="nextCursor")
+
+
+class StorageLinkRequest(ContractModel):
+    """Asks for a short-lived URL for one file (``CreateRuntimeStorageLinkRequest``)."""
+
+    path: str
+    verb: str
+    expires_in_seconds: int | None = Field(default=None, alias="expiresInSeconds")
+    content_type: str | None = Field(default=None, alias="contentType")
+
+
+class StorageLink(ContractModel):
+    """A short-lived URL for one file (``RuntimeStorageLinkResponse``); send ``headers`` with it."""
+
+    url: str
+    verb: str
+    expires_at: datetime = Field(alias="expiresAt")
+    headers: dict[str, str] = Field(default_factory=dict)