render 1.0.1__py3-none-any.whl

render/workflows/app.py

@@ -0,0 +1,263 @@
+"""Workflows application for defining durable tasks."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Any, Concatenate, ParamSpec, TypeVar, overload
+
+from render.workflows.runner import register, run
+from render.workflows.task import (
+    BoundTaskDecorator,
+    Options,
+    Retry,
+    TaskDefinition,
+    TaskRegistry,
+    create_task_decorator,
+)
+
+if TYPE_CHECKING:
+    from render.workflows.context import TaskContext
+
+# P is the task's own inputs, i.e. everything after the leading TaskContext.
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class Workflows:
+    """
+    Task definition app for Render Durable Workflows.
+
+    This is the primary entry point for defining tasks that run on Render.
+    For calling tasks via REST API, use the Render class instead.
+
+    Every task takes a TaskContext as its first parameter, followed by its
+    inputs. The context is how a task reaches other tasks: ``ctx.run``
+    runs one on its own compute and waits for its result.
+
+    Example:
+        app = Workflows()
+
+        @app.task
+        def my_task(ctx: TaskContext, x: int) -> int:
+            return x * 2
+
+        @app.task
+        async def double_twice(ctx: TaskContext, x: int) -> int:
+            # .run runs the task on its own compute
+            once = await ctx.run(my_task, x)
+            return await ctx.run(my_task, once)
+
+    With configuration:
+        app = Workflows(
+            default_retry=Retry(max_retries=3, wait_duration_ms=1000),
+            default_timeout=300,
+        )
+
+        @app.task
+        def my_task(ctx: TaskContext, x: int) -> int:
+            return x * 2
+
+    Combining multiple modules:
+        from tasks_a import app as app_a
+        from tasks_b import app as app_b
+
+        combined = Workflows.from_workflows(app_a, app_b)
+    """
+
+    _registry: TaskRegistry
+    _default_retry: Retry | None
+    _default_timeout: int | None
+    _default_plan: str | None
+
+    def __init__(
+        self,
+        *,
+        default_retry: Retry | None = None,
+        default_timeout: int | None = None,
+        default_plan: str | None = None,
+    ) -> None:
+        """
+        Initialize a Workflows application.
+
+        Args:
+            default_retry: Default retry configuration for all tasks.
+            default_timeout: Default timeout in seconds for all tasks.
+            default_plan: Default resource plan for all tasks.
+        """
+        self._registry = TaskRegistry()
+        self._default_retry = default_retry
+        self._default_timeout = default_timeout
+        self._default_plan = default_plan
+
+    def __repr__(self) -> str:
+        task_count = len(self._registry.get_task_names())
+        return f"Workflows(tasks={task_count})"
+
+    # The async overload comes first: a coroutine function also matches the
+    # sync signature with R bound to the coroutine itself.
+    @overload
+    def task(
+        self, func: Callable[Concatenate[TaskContext, P], Awaitable[R]], /
+    ) -> TaskDefinition[P, R]: ...
+
+    @overload
+    def task(
+        self, func: Callable[Concatenate[TaskContext, P], R], /
+    ) -> TaskDefinition[P, R]: ...
+
+    @overload
+    def task(
+        self,
+        *,
+        name: str | None = ...,
+        retry: Retry | None = ...,
+        timeout_seconds: int | None = ...,
+        plan: str | None = ...,
+    ) -> BoundTaskDecorator: ...
+
+    # The overloads above carry the precise types. The implementation is
+    # deliberately loose so it stays compatible with both of them.
+    def task(
+        self,
+        func: Callable[..., Any] | None = None,
+        *,
+        name: str | None = None,
+        retry: Retry | None = None,
+        timeout_seconds: int | None = None,
+        plan: str | None = None,
+    ) -> Any:
+        """
+        Decorator to register a function as a task.
+
+        The decorated function takes a TaskContext as its first parameter,
+        followed by its inputs.
+
+        Args:
+            func: The function to decorate (when used without parentheses).
+            name: Optional custom name for the task (defaults to function name).
+            retry: Retry configuration (overrides default_retry).
+            timeout_seconds: Timeout in seconds (overrides default_timeout).
+            plan: Resource plan (overrides default_plan).
+
+        Returns:
+            The decorated function as a TaskDefinition.
+
+        Example:
+            @app.task
+            def simple_task(ctx: TaskContext, x: int) -> int:
+                return x * 2
+
+            @app.task(timeout_seconds=60, plan="starter")
+            def quick_task(ctx: TaskContext, x: int) -> int:
+                return x + 1
+        """
+        # Build options from defaults and overrides
+        effective_retry = retry if retry is not None else self._default_retry
+        effective_timeout = (
+            timeout_seconds if timeout_seconds is not None else self._default_timeout
+        )
+        effective_plan = plan if plan is not None else self._default_plan
+
+        options = Options(
+            retry=effective_retry,
+            timeout_seconds=effective_timeout,
+            plan=effective_plan,
+        )
+
+        # Create the task decorator bound to this app's registry
+        task_decorator = create_task_decorator(self._registry)
+
+        def decorator(f: Callable[..., Any]) -> TaskDefinition:
+            return task_decorator(f, name=name, options=options)
+
+        if func is None:
+            # Called with arguments: @app.task(name="...", timeout_seconds=30)
+            return decorator
+        # Called without arguments: @app.task
+        return decorator(func)
+
+    def start(self) -> None:
+        """
+        Start the workflow worker.
+
+        Reads RENDER_SDK_MODE and RENDER_SDK_SOCKET_PATH environment variables
+        to determine whether to run tasks or register them.
+
+        Typically invoked via the render-workflows CLI:
+            render-workflows myapp:app
+
+        Raises:
+            ValueError: If required environment variables are not set.
+        """
+        import os
+
+        mode = os.environ.get("RENDER_SDK_MODE")
+        socket_path = os.environ.get("RENDER_SDK_SOCKET_PATH")
+
+        if not mode:
+            raise ValueError("RENDER_SDK_MODE environment variable is required")
+
+        if not socket_path:
+            raise ValueError("RENDER_SDK_SOCKET_PATH environment variable is required")
+
+        # Copy tasks to global registry for the runner to use
+        from render.workflows.task import _global_registry
+
+        for task_name in self._registry.get_task_names():
+            task_info = self._registry.get_task(task_name)
+            if task_info and task_name not in _global_registry._tasks:
+                _global_registry._tasks[task_name] = task_info
+
+        if mode == "run":
+            run(socket_path)
+        elif mode == "register":
+            register(socket_path)
+        else:
+            raise ValueError(f"Unknown mode: {mode}")
+
+    @classmethod
+    def from_workflows(
+        cls,
+        *apps: Workflows,
+        default_retry: Retry | None = None,
+        default_timeout: int | None = None,
+        default_plan: str | None = None,
+    ) -> Workflows:
+        """
+        Combine multiple Workflows apps into one.
+
+        This is useful for organizing tasks across multiple modules.
+
+        Args:
+            *apps: Workflows instances to combine.
+            default_retry: Default retry for new tasks on combined app.
+            default_timeout: Default timeout for new tasks on combined app.
+            default_plan: Default plan for new tasks on combined app.
+
+        Returns:
+            A new Workflows instance with all tasks from the input apps.
+
+        Example:
+            from tasks_a import app as app_a
+            from tasks_b import app as app_b
+
+            combined = Workflows.from_workflows(app_a, app_b)
+        """
+        combined = cls(
+            default_retry=default_retry,
+            default_timeout=default_timeout,
+            default_plan=default_plan,
+        )
+
+        # Copy tasks from all apps
+        for app in apps:
+            for task_name in app._registry.get_task_names():
+                task_info = app._registry.get_task(task_name)
+                if task_info:
+                    if task_name in combined._registry._tasks:
+                        raise ValueError(
+                            f"Task '{task_name}' is defined in multiple apps"
+                        )
+                    combined._registry._tasks[task_name] = task_info
+
+        return combined

render/workflows/cli.py

@@ -0,0 +1,62 @@
+"""CLI entrypoint for running Render Workflows.
+
+Usage:
+    render-workflows myapp:app
+    render-workflows myapp.tasks:app
+
+Provides explicit control over when and how the worker starts.
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+
+
+def main() -> None:
+    """Main CLI entrypoint."""
+    # Ensure the current working directory is on sys.path so that
+    # `render-workflows <module>:<app>` can find modules in the cwd.
+    if "" not in sys.path:
+        sys.path.insert(0, "")
+
+    if len(sys.argv) < 2:
+        print("Usage: render-workflows <module:app>", file=sys.stderr)
+        print("Example: render-workflows myapp:app", file=sys.stderr)
+        sys.exit(1)
+
+    app_path = sys.argv[1]
+
+    if ":" not in app_path:
+        print(f"Error: Invalid app path '{app_path}'", file=sys.stderr)
+        print("Expected format: <module>:<app_variable>", file=sys.stderr)
+        print("Example: render-workflows myapp:app", file=sys.stderr)
+        sys.exit(1)
+
+    module_path, app_name = app_path.rsplit(":", 1)
+
+    try:
+        module = importlib.import_module(module_path)
+    except ImportError as e:
+        print(f"Error: Could not import module '{module_path}': {e}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        app = getattr(module, app_name)
+    except AttributeError:
+        print(
+            f"Error: Module '{module_path}' has no attribute '{app_name}'",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if not hasattr(app, "start"):
+        print(f"Error: '{app_name}' does not have a start() method", file=sys.stderr)
+        print("Expected a Workflows instance", file=sys.stderr)
+        sys.exit(1)
+
+    app.start()
+
+
+if __name__ == "__main__":
+    main()

render/workflows/client.py

@@ -0,0 +1,354 @@
+"""Unix domain socket client for communicating with the SDK server.
+
+Uses a hand-rolled HTTP/UDS transport (``_uds_http``) and hand-rolled
+data models (``_callback_models``) so this module — which is on the
+worker hot path — does not pull in ``httpx`` or ``attrs`` at import
+time.
+
+Error translation from raw transport exceptions to
+``render.client.errors`` types lives in the :func:`_translate_errors`
+decorator, applied per public method together with
+:func:`_retry_transient_errors`. That keeps ``_uds_http.py`` unaware of
+domain error vocabulary and operation labels.
+"""
+
+import asyncio
+import base64
+import functools
+import http.client
+import json
+import logging
+import time
+import uuid
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, ParamSpec, TypeVar
+
+from render.client.errors import (
+    ClientError,
+    RateLimitError,
+    RenderError,
+    ServerError,
+    TaskRunError,
+)
+from render.client.errors import TimeoutError as SdkTimeoutError
+from render.version import get_user_agent
+from render.workflows._callback_models import CallbackRequest as ApiCallbackRequest
+from render.workflows._callback_models import (
+    InputResponse,
+    RunSubtaskRequest,
+    RunSubtaskResponse,
+    SubtaskResultRequest,
+    SubtaskResultResponse,
+    TaskComplete,
+    TaskError,
+    Tasks,
+    Unset,
+)
+from render.workflows._uds_http import HttpStatusError, request_json
+
+logger = logging.getLogger(__name__)
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class Status(Enum):
+    RUNNING = "running"
+    ERROR = "error"
+    SUCCESS = "success"
+
+
+@dataclass
+class TaskResultResponse:
+    """Response when requesting task results."""
+
+    status: Status
+    result: Any | None = None
+    error: str | None = None
+
+
+@dataclass
+class CallbackRequest:
+    status: Status
+    result: Any | None = None
+    error: str | None = None
+
+
+POLLING_INTERVAL = 1.0
+POLLING_TIMEOUT = 24 * 60 * 60  # 24 hours
+QUERY_TIMEOUT = 15  # 15 seconds
+
+# Total retry window is ~5 minutes (303.75 seconds)
+_UDS_MAX_RETRIES = 25
+_UDS_INITIAL_DELAY_S = 0.25
+_UDS_BACKOFF_FACTOR = 2.0
+_UDS_MAX_DELAY_S = 16.0
+
+
+def _retry_transient_errors(
+    func: Callable[P, Awaitable[R]],
+) -> Callable[P, Awaitable[R]]:
+    """Retry async functions on transient UDS errors.
+
+    Retries on ``ServerError`` (5xx, connection errors), our
+    ``TimeoutError``, and ``RateLimitError`` (429). Does not retry on
+    ``ClientError`` (4xx) or other exceptions. Stacked OUTSIDE
+    :func:`_translate_errors` so it sees translated typed errors, not raw
+    transport exceptions.
+    """
+
+    @functools.wraps(func)
+    async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        for attempt in range(_UDS_MAX_RETRIES):
+            try:
+                return await func(*args, **kwargs)
+            except (ServerError, SdkTimeoutError, RateLimitError) as e:
+                if attempt >= _UDS_MAX_RETRIES - 1:
+                    raise
+                delay = min(
+                    _UDS_INITIAL_DELAY_S * (_UDS_BACKOFF_FACTOR**attempt),
+                    _UDS_MAX_DELAY_S,
+                )
+                logger.warning(
+                    "Request to Render failed (%d/%d), retry in %.1fs: %s",
+                    attempt + 1,
+                    _UDS_MAX_RETRIES,
+                    delay,
+                    e,
+                )
+                await asyncio.sleep(delay)
+        raise AssertionError("unreachable")  # pragma: no cover
+
+    return wrapper
+
+
+def _extract_status_message(body: bytes) -> str | None:
+    """Best-effort extraction of an error message from an HTTP error body.
+
+    Tries JSON ``{"message": ...}`` / ``{"error": ...}`` first, then falls
+    back to the raw body as UTF-8. Returns ``None`` if nothing usable is
+    found.
+    """
+    if not body:
+        return None
+    try:
+        payload = json.loads(body)
+        if isinstance(payload, dict):
+            raw = payload.get("message") or payload.get("error")
+            if isinstance(raw, str):
+                return raw
+    except (ValueError, UnicodeDecodeError):
+        pass
+    try:
+        return body.decode("utf-8", errors="replace").strip() or None
+    except Exception:  # pragma: no cover - defensive
+        return None
+
+
+def _translate_errors(
+    operation: str,
+) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[R]]]:
+    """Translate raw transport exceptions into render.client.errors types.
+
+    The transport in ``_uds_http`` raises stdlib exceptions plus
+    :class:`HttpStatusError`. This decorator turns those into the
+    appropriate typed error with the operation label baked into the
+    message, so callers see a consistent error vocabulary regardless of
+    which transport-level failure occurred.
+    """
+
+    def decorator(func: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
+        @functools.wraps(func)
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            try:
+                return await func(*args, **kwargs)
+            # `socket.timeout` is an alias for the built-in ``TimeoutError``;
+            # our domain timeout is imported as ``SdkTimeoutError`` so the
+            # built-in name stays free for catching.
+            except TimeoutError as e:
+                raise SdkTimeoutError(f"{operation} timed out: {e}") from e
+            except (ConnectionError, FileNotFoundError) as e:
+                raise ServerError(f"{operation} failed to connect: {e}") from e
+            except http.client.HTTPException as e:
+                raise ServerError(f"{operation} got invalid HTTP response: {e}") from e
+            except HttpStatusError as e:
+                message = _extract_status_message(e.body)
+                full = f"{operation} failed with status {e.status}"
+                if message:
+                    full = f"{full}: {message}"
+                if e.status == 429:
+                    raise RateLimitError(full) from e
+                if e.status < 500:
+                    raise ClientError(full) from e
+                raise ServerError(full) from e
+            except json.JSONDecodeError as e:
+                raise RenderError(f"{operation} failed: non-JSON response: {e}") from e
+            except OSError as e:
+                raise ServerError(f"{operation} network error: {e}") from e
+
+        return wrapper
+
+    return decorator
+
+
+class UDSClient:
+    """Client for communicating with the SDK server over Unix Domain Socket."""
+
+    def __init__(self, socket_path: str):
+        self.socket_path = socket_path
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None,
+    ) -> Any:
+        """Bundle the per-call constants (user agent, timeout, socket path).
+
+        This carries no error translation — that lives on the public
+        methods via :func:`_translate_errors`. Each public method is
+        responsible for asserting the response shape it expects.
+        """
+        return await request_json(
+            socket_path=self.socket_path,
+            method=method,
+            path=path,
+            body=body,
+            user_agent=get_user_agent(),
+            timeout=QUERY_TIMEOUT,
+        )
+
+    @_retry_transient_errors
+    @_translate_errors("get input")
+    async def get_input(self) -> InputResponse:
+        """Get the task name and input for a task run."""
+        payload = await self._request("GET", "/input", None)
+        if not isinstance(payload, dict):
+            raise RenderError(f"get input failed: unexpected response: {payload!r}")
+        return InputResponse.from_dict(payload)
+
+    @_retry_transient_errors
+    @_translate_errors("post callback")
+    async def post_callback(self, callback_request: CallbackRequest) -> None:
+        """Send a callback to the server."""
+        if callback_request.status == Status.SUCCESS:
+            # Wire format expects results to be wrapped in an array.
+            result_array = (
+                [callback_request.result]
+                if not isinstance(callback_request.result, list)
+                else callback_request.result
+            )
+            result_json = json.dumps(result_array).encode()
+            data = ApiCallbackRequest(
+                complete=TaskComplete(output=base64.b64encode(result_json).decode())
+            )
+        elif (
+            callback_request.status == Status.ERROR
+            and callback_request.error is not None
+        ):
+            data = ApiCallbackRequest(error=TaskError(details=callback_request.error))
+        else:
+            data = ApiCallbackRequest()
+
+        await self._request("POST", "/callback", data.to_dict())
+
+    async def run_subtask(
+        self, task_name: str, input_data: list[Any] | dict[str, Any] | None = None
+    ) -> Any:
+        """
+        Run a subtask and wait for its completion.
+
+        Args:
+            task_name: Name of the task to run
+            input_data: Input data to pass to the task. Can be either:
+                - A list for positional arguments: [arg1, arg2, arg3]
+                - A dict for named parameters: {"param1": value1, "param2": value2}
+
+        Returns:
+            The result of the subtask execution
+        """
+        # Encode input data as base64 JSON
+        input_json = json.dumps(input_data if input_data is not None else []).encode()
+        # Build the request outside _start_subtask, which retries internally, so
+        # every retry resends the same idempotency_key and created_at.
+        subtask_request = RunSubtaskRequest(
+            task_name=task_name,
+            input_=base64.b64encode(input_json).decode(),
+            idempotency_key=str(uuid.uuid4()),
+            created_at=datetime.now(timezone.utc).isoformat(),
+        )
+
+        response = await self._start_subtask(subtask_request)
+        task_run_id = response.task_run_id
+
+        start_time = time.time()
+        while time.time() - start_time < POLLING_TIMEOUT:
+            result = await self.get_task_result(task_run_id)
+
+            if result.status == Status.SUCCESS:
+                actual_result = result.result
+                if isinstance(actual_result, list) and len(actual_result) == 1:
+                    return actual_result[0]
+                return actual_result
+            elif result.status == Status.ERROR:
+                raise TaskRunError(f"Subtask failed: {result.error}")
+            elif result.status == Status.RUNNING:
+                await asyncio.sleep(POLLING_INTERVAL)
+            else:
+                raise RenderError(f"Unknown subtask status: {result.status}")
+
+    @_retry_transient_errors
+    @_translate_errors("run subtask")
+    async def _start_subtask(
+        self, subtask_request: RunSubtaskRequest
+    ) -> RunSubtaskResponse:
+        payload = await self._request("POST", "/run-subtask", subtask_request.to_dict())
+        if not isinstance(payload, dict):
+            raise RenderError(f"run subtask failed: unexpected response: {payload!r}")
+        return RunSubtaskResponse.from_dict(payload)
+
+    @_retry_transient_errors
+    @_translate_errors("register tasks")
+    async def register_tasks(self, tasks: Tasks) -> None:
+        """Register tasks with the server."""
+        await self._request("POST", "/register-tasks", tasks.to_dict())
+
+    @_retry_transient_errors
+    @_translate_errors("get task result")
+    async def get_task_result(self, task_run_id: str) -> TaskResultResponse:
+        """Get the result of a task run."""
+        subtask_result_request = SubtaskResultRequest(task_run_id=task_run_id)
+
+        payload = await self._request(
+            "POST", "/get-subtask-result", subtask_result_request.to_dict()
+        )
+        if not isinstance(payload, dict):
+            raise RenderError(
+                f"get task result failed: unexpected response: {payload!r}"
+            )
+        response = SubtaskResultResponse.from_dict(payload)
+
+        if response.still_running:
+            return TaskResultResponse(status=Status.RUNNING)
+
+        if not isinstance(response.error, Unset) and response.error is not None:
+            return TaskResultResponse(
+                status=Status.ERROR,
+                error=response.error.details,
+            )
+
+        if not isinstance(response.complete, Unset) and response.complete is not None:
+            result: Any | None = None
+            if response.complete.output:
+                try:
+                    result = json.loads(
+                        base64.b64decode(response.complete.output).decode()
+                    )
+                except (json.JSONDecodeError, ValueError) as e:
+                    raise RenderError(f"Failed to decode task result: {e}") from e
+            return TaskResultResponse(status=Status.SUCCESS, result=result)
+
+        raise RenderError("Unknown task status")