crosswind-workers 0.1.0__py3-none-any.whl

workers/workflows.py

@@ -0,0 +1,265 @@
+"""Workflow steps in pure Python.
+
+The stock SDK ships one JavaScript helper, which renames a Python
+`NonRetryableError` so the Workflows engine stops retrying the step. A Python
+`raise` can't do that, because Pyodide wraps it in a fresh `PythonError`. Here
+the step callback instead returns a thenable that rejects with a JS `Error` of
+that name, and the engine adopts the rejection.
+"""
+
+import functools
+import inspect
+from asyncio import Task, create_task, gather
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+import js
+from pyodide.ffi import JsException, create_once_callable, to_js
+
+from ._js import compat_flag
+from .bindings import Binding
+from .rpc import python_from_rpc, python_to_rpc
+
+__all__ = ["NonRetryableError", "WorkflowStep"]
+
+NON_RETRYABLE = "NonRetryableError"
+
+type Step = Callable[[], Coroutine[Any, Any, Any]]
+
+
+class NonRetryableError(Exception):
+    """Raised inside a step, stops the Workflows engine from retrying it."""
+
+
+class WorkflowStep(Binding):
+    """The `step` a Workflow's `run` receives. Other names pass through."""
+
+    def __init__(self, js_object: Any) -> None:
+        if js_object is self:
+            return
+        super().__init__(js_object)
+        self._results: dict[Step, Any] = {}
+        self._in_flight: dict[Step, Task[Any]] = {}
+        # Each step by its step name and by its function's name.
+        self._steps: dict[str, Step] = {}
+
+    def do(
+        self,
+        name: str | None = None,
+        depends: list[Step] | None = None,
+        concurrent: bool = False,
+        config: dict[str, Any] | None = None,
+    ) -> Callable[[Callable[..., Any]], Step]:
+        """Decorate a function as a step and return an async callable that runs it.
+
+        With `python_workflows_implicit_dependencies`, a parameter named after
+        an earlier step receives its result. Without it, `depends` lists them.
+        A parameter named `ctx` receives the step context either way.
+        """
+        implicit = compat_flag("python_workflows_implicit_dependencies")
+        if implicit and depends is not None:
+            raise TypeError(
+                "depends is not accepted with python_workflows_implicit_dependencies;"
+                " name parameters after the steps they depend on"
+            )
+
+        def decorator(func: Callable[..., Any]) -> Step:
+            func_name: str = getattr(func, "__name__", name or "")
+            step_name = func_name if name is None else name
+            parameters = list(inspect.signature(func).parameters)
+            dependencies = self._dependencies(parameters, depends, implicit)
+
+            async def step() -> Any:
+                if concurrent:
+                    results = await gather(*map(self._resolve, dependencies))
+                else:
+                    results = [await self._resolve(d) for d in dependencies]
+                return await self._run(
+                    step, step_name, config, func, parameters, results
+                )
+
+            # By function name too, so a step named "ctx-step" can be a dependency.
+            self._steps[step_name] = self._steps[func_name] = step
+            return step
+
+        return decorator
+
+    async def sleep(self, *args: Any, **kwargs: Any) -> Any:
+        return await self.js_object.sleep(*args, **kwargs)
+
+    async def sleep_until(self, name: str, timestamp: Any) -> Any:
+        if not isinstance(timestamp, str):
+            timestamp = python_to_rpc(timestamp)
+        return await self.js_object.sleepUntil(name, timestamp)
+
+    async def wait_for_event(
+        self, name: str, event_type: str, /, timeout: str = "24 hours"
+    ) -> Any:
+        options = _js_object({"type": event_type, "timeout": timeout})
+        return python_from_rpc(await self.js_object.waitForEvent(name, options))
+
+    def _dependencies(
+        self, parameters: list[str], depends: list[Step] | None, implicit: bool
+    ) -> list[Step]:
+        """The steps whose results fill the parameters other than ctx."""
+        others = [p for p in parameters if p != "ctx"]
+        if not implicit:
+            return self._listed_dependencies(others, depends)
+
+        for parameter in others:
+            if parameter not in self._steps:
+                raise TypeError(f"Received unexpected parameter {parameter}")
+
+        return [self._steps[p] for p in others]
+
+    def _listed_dependencies(
+        self, others: list[str], depends: list[Step] | None
+    ) -> list[Step]:
+        """The steps `depends` lists, checked against the parameters they fill."""
+        if depends is None and others:
+            raise TypeError(
+                f"Step has {len(others)} non-ctx parameter(s) but no 'depends' "
+                "list provided"
+            )
+        depends = list(depends or [])
+
+        if len(depends) != len(others):
+            raise TypeError(
+                f"Step declares {len(others)} non-ctx parameter(s) but 'depends' "
+                f"has {len(depends)} item(s)"
+            )
+
+        for parameter, dependency in zip(others, depends, strict=True):
+            if dependency not in self._steps.values():
+                raise TypeError(
+                    f"'depends' entry for parameter {parameter!r} is not a "
+                    "function decorated with step.do"
+                )
+
+        return depends
+
+    async def _resolve(self, dependency: Step) -> Any:
+        if dependency in self._results:
+            return self._results[dependency]
+
+        # Registered before awaiting, so a concurrent branch reuses this run.
+        if dependency not in self._in_flight:
+            self._in_flight[dependency] = create_task(dependency())
+        return await self._in_flight[dependency]
+
+    async def _run(
+        self,
+        key: Step,
+        name: str,
+        config: dict[str, Any] | None,
+        func: Callable[..., Any],
+        parameters: list[str],
+        results: list[Any],
+    ) -> Any:
+        async def callback(ctx: Any = None) -> Any:
+            given = iter(results)
+            args = [
+                python_from_rpc(ctx) if p == "ctx" else next(given) for p in parameters
+            ]
+
+            try:
+                result = func(*args)
+                if inspect.isawaitable(result):
+                    result = await result
+            except NonRetryableError as error:
+                return _rejecting_thenable(error)
+
+            # The result crosses RPC back to the Workflows engine.
+            return python_to_rpc(result)
+
+        async def call() -> Any:
+            args = [name] if config is None else [name, _js_object(config)]
+
+            try:
+                return python_from_rpc(await self.js_object.do(*args, callback))
+            except JsException as error:
+                python_error = _python_error(error)
+                if python_error is error:
+                    raise
+                raise python_error from error
+
+        task = create_task(call())
+        self._in_flight[key] = task
+        try:
+            self._results[key] = result = await task
+        finally:
+            self._in_flight.pop(key, None)
+
+        return result
+
+
+def wrap_run(run: Callable[..., Any]) -> Callable[..., Any]:
+    """Convert the event and step workerd passes `run` as raw JS values."""
+
+    @functools.wraps(run)
+    async def wrapped(
+        self: Any, event: Any = None, step: Any = None, /, *args: Any, **kwargs: Any
+    ) -> Any:
+        if event is not None:
+            event = python_from_rpc(event)
+        if step is not None:
+            step = WorkflowStep(step)
+
+        result = run(self, event, step, *args, **kwargs)
+        if inspect.isawaitable(result):
+            result = await result
+
+        return None if result is None else python_to_rpc(result)
+
+    return wrapped
+
+
+def _js_object(value: dict[str, Any]) -> Any:
+    return to_js(value, dict_converter=js.Object.fromEntries)
+
+
+def _rejecting_thenable(error: NonRetryableError) -> Any:
+    js_error = js.Error.new(str(error))
+    js_error.name = NON_RETRYABLE
+    # A thenable, so no rejected promise exists before the engine adopts it.
+    return _js_object(
+        {"then": create_once_callable(lambda _resolve, reject: reject(js_error))}
+    )
+
+
+# The Python exception for a traceback's last line, by the line's prefix.
+_TRACEBACK_ERRORS: dict[str, type[Exception]] = {
+    "TypeError": TypeError,
+    "ValueError": ValueError,
+    "workers.workflows.NonRetryableError": NonRetryableError,
+}
+
+# The Python exception for a JS error, by the error's name.
+_JS_ERRORS: dict[str | None, type[Exception]] = {
+    "RangeError": ValueError,
+    "TypeError": TypeError,
+}
+
+
+def _python_error(error: JsException) -> Exception:
+    """The Python exception for a step error the engine rethrew."""
+    message = error.message or ""
+
+    # The name survives the engine, or is folded into the message.
+    if error.name == NON_RETRYABLE:
+        return NonRetryableError(message)
+    if message == NON_RETRYABLE or message.startswith(f"{NON_RETRYABLE}: "):
+        return NonRetryableError(message[len(NON_RETRYABLE) + 2 :])
+
+    # A Python exception that escaped a step comes back as a PythonError whose
+    # message is the traceback, ending with the exception's own line.
+    lines = message.rstrip().split("\n")
+    if len(lines) > 1 and (
+        error.name == "PythonError" or message.startswith("PythonError")
+    ):
+        for prefix, error_type in _TRACEBACK_ERRORS.items():
+            if lines[-1].startswith(prefix):
+                return error_type(lines[-1])
+
+    error_type = _JS_ERRORS.get(error.name)
+    return error if error_type is None else error_type(message)

workers/wsgi.py

@@ -0,0 +1,426 @@
+"""Serve a WSGI application, such as Flask, from a Worker.
+
+Ported from the stock SDK at cb2db3c. `wsgi.input` streams the request body
+through `run_sync`, which Python 3.12 Workers lack, so there the body is read
+up front instead.
+"""
+
+import io
+import logging
+import sys
+from collections.abc import Callable, Iterable, Iterator
+from typing import Any
+from urllib.parse import SplitResult, unquote, urlsplit
+
+import js
+import pyodide.ffi
+
+from ._adapter import NULL_BODY_STATUSES, body_encoding, request_headers
+from .context import ExecutionContext
+from .entrypoints import WorkerEntrypoint
+from .request import Request
+from .types import Context
+
+logger = logging.getLogger("wsgi")
+
+
+def _wsgi_native_string(value: str) -> str:
+    """Convert a (possibly non-ASCII) Python ``str`` into a WSGI "native string".
+
+    PEP 3333 requires that strings handed to a WSGI application use the
+    bytes-in-unicode convention: the string contains characters whose code
+    points correspond to the raw bytes (i.e. it is decoded with ``latin-1``).
+    Frameworks such as Werkzeug/Flask undo this by re-encoding with ``latin-1``
+    and decoding with ``utf-8``.
+    """
+    return value.encode("utf-8").decode("latin-1")
+
+
+class _ReadableStreamInput(io.RawIOBase):
+    """A blocking, file-like ``wsgi.input`` backed by an async ``ReadableStream``.
+
+    WSGI apps read the request body synchronously, but the Workers body is an
+    async ``ReadableStream``. We bridge the two lazily using Pyodide's
+    ``run_sync`` (JSPI stack switching): each ``readinto`` pulls only as much
+    from the stream as the application asks for, so the body is never fully
+    buffered up-front.
+
+    This only works while a JSPI suspender is on the stack, which is the case
+    here because the WSGI app runs synchronously inside the async ``fetch``
+    handler.
+    """
+
+    def __init__(self, js_body: "js.ReadableStream") -> None:
+        self._reader = js_body.getReader()
+        self._buf = bytearray()
+        self._eof = False
+
+    def readable(self) -> bool:
+        return True
+
+    def _fill(self) -> None:
+        from pyodide.ffi import run_sync
+
+        while not self._buf and not self._eof:
+            result = run_sync(self._reader.read())
+            if result.done:
+                self._eof = True
+            elif result.value is not None:
+                self._buf.extend(result.value.to_bytes())
+
+    def readinto(self, b) -> int:
+        self._fill()
+        if not self._buf:
+            return 0
+
+        n = min(len(b), len(self._buf))
+        b[:n] = self._buf[:n]
+        del self._buf[:n]
+        return n
+
+    def close(self) -> None:
+        if not self.closed:
+            self._release_reader()
+        super().close()
+
+    def __del__(self):
+        self.close()
+
+    def _release_reader(self) -> None:
+        """Discard the request body and release the underlying reader.
+
+        If the body was fully consumed we just release the lock. Otherwise we
+        ``cancel()`` the reader to drop the remainder; ``cancel()`` returns a JS
+        promise that the runtime settles on its own, so we don't await it.
+        """
+        from pyodide.ffi import run_sync
+
+        try:
+            if self._eof:
+                self._reader.releaseLock()
+            else:
+                run_sync(self._reader.cancel())
+        except Exception:
+            logger.debug("Releasing the request body failed", exc_info=True)
+
+
+def _make_wsgi_input(req: "Request | js.Request") -> "io.BufferedIOBase | None":
+    """Build a lazy, stream-backed ``wsgi.input`` if the runtime supports it.
+
+    Returns ``None`` when lazy streaming is unavailable, signalling the caller
+    to fall back to pre-buffering the body.
+    """
+    if not req.body:
+        return io.BytesIO(b"")
+    if not hasattr(pyodide.ffi, "run_sync"):
+        return None
+
+    # `req.body` is a JS ReadableStream for both workers.Request and js.Request.
+    return io.BufferedReader(_ReadableStreamInput(req.body))
+
+
+async def _read_body(req: "Request | js.Request") -> bytes:
+    """Read the entire request body into memory (fallback when streaming is off)."""
+    if not req.body:
+        return b""
+
+    chunks = [data.to_bytes() async for data in req.body]
+    return b"".join(chunks)
+
+
+def build_environ(
+    req: "Request | js.Request",
+    env: dict[str, Any],
+    body: "bytes | io.IOBase",
+) -> dict[str, Any]:
+    url = urlsplit(req.url)
+    if not url.scheme:
+        raise ValueError(f"Request URL is not absolute: {req.url!r}")
+
+    # `body` may be raw bytes or a file-like `wsgi.input` stream
+    if isinstance(body, (bytes, bytearray)):
+        wsgi_input: Any = io.BytesIO(body)
+        content_length_fallback: int | None = len(body)
+    else:
+        wsgi_input = body
+        content_length_fallback = None
+
+    environ: dict[str, Any] = {
+        "REQUEST_METHOD": _method_name(req.method),
+        "SCRIPT_NAME": "",
+        # PATH_INFO is the URL-decoded path expressed as a WSGI native string.
+        "PATH_INFO": _wsgi_native_string(unquote(url.path or "/")),
+        # QUERY_STRING stays percent-encoded per the spec.
+        "QUERY_STRING": url.query,
+        # A request URL is always absolute here, so hostname is populated; keep a
+        # fallback since WSGI requires SERVER_NAME to be non-empty.
+        "SERVER_NAME": url.hostname,
+        "SERVER_PORT": _server_port(url),
+        "SERVER_PROTOCOL": "HTTP/1.1",
+        "wsgi.version": (1, 0),
+        "wsgi.url_scheme": url.scheme,
+        "wsgi.input": wsgi_input,
+        "wsgi.errors": sys.stderr,
+        "wsgi.multithread": False,
+        "wsgi.multiprocess": False,
+        "wsgi.run_once": False,
+        # Cloudflare-specific extension so handlers can reach bindings, mirroring
+        # the `scope["env"]` convention used by asgi.py.
+        "workers.env": env,
+    }
+    environ.update(_header_variables(request_headers(req)))
+
+    # Only synthesize CONTENT_LENGTH when the body was pre-buffered; when
+    # streaming lazily we don't know the length without consuming it.
+    if "CONTENT_LENGTH" not in environ and content_length_fallback:
+        environ["CONTENT_LENGTH"] = str(content_length_fallback)
+
+    return environ
+
+
+def _method_name(method: Any) -> str:
+    # `workers.Request.method` is an `http.HTTPMethod` (a str subclass); coerce
+    # to a plain string so frameworks comparing against literals behave.
+    return str(method.value) if hasattr(method, "value") else str(method)
+
+
+def _server_port(url: SplitResult) -> str:
+    if url.port:
+        return str(url.port)
+    return "443" if url.scheme == "https" else "80"
+
+
+def _header_variables(headers: Iterable[tuple[str, str]]) -> dict[str, str]:
+    """The environ variables for request headers, per the CGI convention."""
+    variables: dict[str, str] = {}
+    for key, value in headers:
+        name = key.upper().replace("-", "_")
+        if name in ("CONTENT_TYPE", "CONTENT_LENGTH"):
+            variables[name] = value
+        elif (http_name := "HTTP_" + name) in variables:
+            # Repeated headers are folded into a single comma-separated value.
+            variables[http_name] += "," + value
+        else:
+            variables[http_name] = value
+
+    return variables
+
+
+def _to_js_uint8array(chunk: bytes) -> "js.Uint8Array":
+    """Copy Python ``bytes`` into a standalone, JS-owned ``Uint8Array``.
+
+    A copy (rather than a view over the WASM heap) is required because
+    ``ReadableStreamDefaultController.enqueue`` keeps the chunk by reference in
+    the stream's internal queue until the consumer reads it later, by which
+    point ``chunk`` has been released. ``to_js`` copies buffer data out of the
+    heap into a fresh ``ArrayBuffer`` (pyodide's ``python2js_buffer``), so its
+    result stays valid.
+    """
+    from pyodide.ffi import to_js
+
+    return to_js(chunk)
+
+
+def _close_iterable(iterable: Any) -> None:
+    # PEP 3333: if the iterable has a close() method, the server must call it.
+    close = getattr(iterable, "close", None)
+    if close is not None:
+        close()
+
+
+# Sentinel marking exhaustion of the response body iterator.
+_END = object()
+
+
+def _make_streaming_response(
+    status: str,
+    headers: "list[tuple[str, str]]",
+    chunks: "Iterator[bytes]",
+    on_close: "Callable[[], None]",
+) -> js.Response:
+    """Build a ``js.Response`` whose body is pulled lazily from *chunks*.
+
+    Uses a ``ReadableStream`` with a synchronous, pull-based source so response
+    bytes are produced on demand as the client reads, instead of buffering the
+    whole body in memory. ``on_close`` runs exactly once when the stream is
+    exhausted, errored, or cancelled.
+    """
+    from js import ReadableStream, Response
+
+    init = _response_init(status, headers)
+    if init["status"] in NULL_BODY_STATUSES:
+        on_close()
+        return Response.new(None, **init)
+
+    source = _PullSource(chunks, on_close)
+    stream = ReadableStream.new(pull=source.pull, cancel=source.cancel)
+
+    return Response.new(stream, **init)
+
+
+def _response_init(status: str, headers: "list[tuple[str, str]]") -> dict[str, Any]:
+    from js import Headers as JsHeaders
+
+    # WSGI status is e.g. "200 OK"; split into code + reason phrase.
+    code, _, reason = status.partition(" ")
+    init: dict[str, Any] = {"status": int(code), **body_encoding(headers)}
+    if reason:
+        init["statusText"] = reason
+
+    init["headers"] = JsHeaders.new()
+    for key, value in headers:
+        # `append` (not `set`) preserves repeated headers such as Set-Cookie.
+        init["headers"].append(key, value)
+
+    return init
+
+
+class _PullSource:
+    """The pull-based source of a response ``ReadableStream``."""
+
+    def __init__(self, chunks: "Iterator[bytes]", on_close: "Callable[[], None]"):
+        from pyodide.ffi import create_proxy
+
+        self._chunks = chunks
+        self._on_close = on_close
+        self._done = False
+        # Make proxies async so that it is possible to stack switch inside them.
+        self.pull = create_proxy(self._pull)
+        self.cancel = create_proxy(self._cancel)
+
+    async def _pull(self, controller: Any) -> None:
+        try:
+            chunk: Any = next(self._chunks, _END)
+        except Exception as exc:
+            logger.exception("Exception while streaming WSGI response body")
+            self._cleanup()
+            controller.error(str(exc))
+            return
+
+        if chunk is _END:
+            controller.close()
+            self._cleanup()
+            return
+
+        controller.enqueue(_to_js_uint8array(chunk))
+
+    async def _cancel(self, _reason: Any = None) -> None:
+        self._cleanup()
+
+    def _cleanup(self) -> None:
+        if self._done:
+            return
+
+        self._done = True
+        try:
+            self._on_close()
+        finally:
+            self.pull.destroy()
+            self.cancel.destroy()
+
+
+class _StartResponse:
+    """The ``start_response`` callable, and the status and headers it records."""
+
+    def __init__(self) -> None:
+        self.status: str | None = None
+        self.headers: list[tuple[str, str]] = []
+        # Output from the (rarely used) legacy `write()` callable. Modern
+        # frameworks (Flask, Werkzeug, Django) return an iterable instead; when
+        # they do use write(), that output is emitted before the iterable's
+        # chunks.
+        self.written: list[bytes] = []
+
+    def __call__(self, status, response_headers, exc_info=None):
+        if exc_info is not None:
+            try:
+                if self.status is not None:
+                    # Headers were already sent; re-raise the original error.
+                    raise exc_info[1].with_traceback(exc_info[2])
+            finally:
+                exc_info = None
+        elif self.status is not None:
+            raise AssertionError("start_response() called more than once")
+
+        self.status = status
+        self.headers = response_headers
+        return self.write
+
+    def write(self, chunk: bytes) -> None:
+        if self.status is None:
+            raise AssertionError("write() called before start_response()")
+        if chunk:
+            self.written.append(chunk)
+
+
+def process_request(
+    app: Any,
+    req: "Request | js.Request",
+    env: Any,
+    body: "bytes | io.IOBase",
+) -> js.Response:
+    environ = build_environ(req, env, body)
+    start_response = _StartResponse()
+    result = app(environ, start_response)
+    result_iter = filter(None, iter(result))
+
+    def close_all() -> None:
+        _close_iterable(result)
+        try:
+            environ["wsgi.input"].close()
+        except Exception:
+            logger.exception("Failed to close wsgi.input")
+
+    # WSGI apps must call start_response before yielding the first body chunk,
+    # but some defer it until the first non-empty chunk is produced. Pull that
+    # chunk now so status/headers are known before we construct the Response.
+    try:
+        first_chunk: Any = next(result_iter, _END)
+    except Exception:
+        close_all()
+        raise
+
+    if start_response.status is None:
+        close_all()
+        raise RuntimeError("The WSGI application did not call start_response()")
+
+    def body_chunks() -> "Iterator[bytes]":
+        yield from start_response.written
+        if first_chunk is not _END:
+            yield first_chunk
+        yield from result_iter
+
+    return _make_streaming_response(
+        start_response.status, start_response.headers, body_chunks(), close_all
+    )
+
+
+async def fetch(
+    app: Any,
+    req: "Request | js.Request",
+    env: Any,
+    # Accepted for parity with asgi.fetch; WSGI has no use for it.
+    ctx: "Context | ExecutionContext | None" = None,
+) -> js.Response:
+    logger.debug("WSGI request: %s %s", req.method, req.url)
+    # Prefer lazily streaming the body through `wsgi.input` (no full buffering);
+    # fall back to pre-buffering when `run_sync`/JSPI isn't available.
+    body: bytes | io.IOBase | None = _make_wsgi_input(req)
+    if body is None:
+        body = await _read_body(req)
+
+    try:
+        return process_request(app, req, env, body)
+    except Exception:
+        logger.exception("WSGI request failed")
+        raise
+
+
+def entrypoint(app: Any) -> type[WorkerEntrypoint]:
+    """Create the default Worker entrypoint for a WSGI application."""
+
+    class Default(WorkerEntrypoint):
+        async def fetch(self, request):
+            return await fetch(app, request, self.env)
+
+    return Default