workers-runtime-sdk 1.5.4__tar.gz → 1.6.1__tar.gz

{workers_runtime_sdk-1.5.4 → workers_runtime_sdk-1.6.1}/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 <!-- version list -->
 
+## v1.6.1 (2026-07-09)
+
+### Bug Fixes
+
+- Improve lifespan handling in asgi.py ([#148](https://github.com/cloudflare/workers-py/pull/148),
+  [`7c9adfc`](https://github.com/cloudflare/workers-py/commit/7c9adfce6c3997f1547901755e97c685ef6e6be3))
+
+
+## v1.6.0 (2026-07-08)
+
+### Features
+
+- Add wsgi.py analogous to asgi.py ([#145](https://github.com/cloudflare/workers-py/pull/145),
+  [`247f9ff`](https://github.com/cloudflare/workers-py/commit/247f9ff5387eb2d286c65c1199f3ff51938578fa))
+
+
 ## v1.5.4 (2026-07-08)
 
 ### Bug Fixes

{workers_runtime_sdk-1.5.4 → workers_runtime_sdk-1.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workers-runtime-sdk
-Version: 1.5.4
+Version: 1.6.1
 Summary: Python SDK for Cloudflare Workers
 Project-URL: Homepage, https://github.com/cloudflare/workers-py
 Project-URL: Bug Tracker, https://github.com/cloudflare/workers-py/issues

{workers_runtime_sdk-1.5.4 → workers_runtime_sdk-1.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "workers-runtime-sdk"
-version = "1.5.4"
+version = "1.6.1"
 description = "Python SDK for Cloudflare Workers"
 readme = "README.md"
 requires-python = ">=3.11"

{workers_runtime_sdk-1.5.4 → workers_runtime_sdk-1.6.1}/src/asgi.py

@@ -1,8 +1,7 @@
 import logging
-from asyncio import Event, Future, Queue, create_task, ensure_future, sleep
+from asyncio import Event, Future, Queue, create_task, ensure_future
 from collections.abc import Awaitable
 from contextlib import contextmanager
-from inspect import isawaitable
 from typing import Any
 
 import js
@@ -10,6 +9,7 @@ import js
 from workers import Context, Request
 
 ASGI = {"spec_version": "2.0", "version": "3.0"}
+NULL_BODY_STATUSES = frozenset({101, 103, 204, 205, 304})
 logger = logging.getLogger("asgi")
 background_tasks = set()
 
@@ -76,42 +76,86 @@ def request_to_scope(req, env, ws=False):
 
 
 async def start_application(app):
-    shutdown_future = Future()
+    # Drives one ASGI lifespan startup/shutdown cycle before/after serving the
+    # request. The lifespan protocol is optional, so we must tolerate apps that
+    # don't implement it and fall back to serving requests without lifespan.
+    # https://asgi.readthedocs.io/en/latest/specs/lifespan.html
+    receive_queue = Queue()
+    await receive_queue.put({"type": "lifespan.startup"})
+
+    # `startup` resolves True on `lifespan.startup.complete`, False when the app
+    # has no lifespan support, and raises on `lifespan.startup.failed`.
+    # `shutdown_complete` mirrors the shutdown phase.
+    startup = Future()
+    shutdown_complete = Future()
 
     async def shutdown():
-        shutdown_future.set_result(None)
-        await sleep(0)
+        # Nothing to shut down if the app never completed a lifespan startup.
+        if startup.done() and not startup.result():
+            return
+        await receive_queue.put({"type": "lifespan.shutdown"})
+        await shutdown_complete
 
-    it = iter([{"type": "lifespan.startup"}, Future()])
+    async def no_lifespan_shutdown():
+        return
 
     async def receive():
-        res = next(it)
-        if isawaitable(res):
-            await res
-        return res
-
-    ready = Future()
+        return await receive_queue.get()
 
     async def send(got):
         if got["type"] == "lifespan.startup.complete":
-            ready.set_result(None)
+            if not startup.done():
+                startup.set_result(True)
+            return
+        if got["type"] == "lifespan.startup.failed":
+            message = got.get("message", "ASGI lifespan startup failed")
+            if not startup.done():
+                startup.set_exception(RuntimeError(message))
             return
         if got["type"] == "lifespan.shutdown.complete":
+            if not shutdown_complete.done():
+                shutdown_complete.set_result(None)
+            return
+        if got["type"] == "lifespan.shutdown.failed":
+            message = got.get("message", "ASGI lifespan shutdown failed")
+            if not shutdown_complete.done():
+                shutdown_complete.set_exception(RuntimeError(message))
             return
         raise RuntimeError(f"Unexpected lifespan event {got['type']}")
 
-    run_in_background(
-        app(
-            {
-                "asgi": ASGI,
-                "state": {},
-                "type": "lifespan",
-            },
-            receive,
-            send,
-        )
-    )
-    await ready
+    async def run_lifespan():
+        try:
+            await app(
+                {
+                    "asgi": ASGI,
+                    "state": {},
+                    "type": "lifespan",
+                },
+                receive,
+                send,
+            )
+            # App returned without acking: a missing startup ack means it has no
+            # lifespan handler, so mark startup unsupported rather than hanging.
+            if not startup.done():
+                startup.set_result(False)
+            elif not shutdown_complete.done():
+                shutdown_complete.set_result(None)
+        except Exception as exc:
+            # Spec: an exception raised before startup is acked signals that the
+            # app doesn't support lifespan; swallow it and serve requests anyway.
+            if not startup.done():
+                startup.set_result(False)
+                return
+            # After a successful startup, a shutdown-phase error can't affect the
+            # already-served request, so log it and let shutdown complete.
+            logger.exception("Exception in ASGI lifespan application", exc_info=exc)
+            if not shutdown_complete.done():
+                shutdown_complete.set_result(None)
+
+    run_in_background(run_lifespan())
+    supported = await startup
+    if not supported:
+        return no_lifespan_shutdown
     return shutdown
 
 
@@ -163,10 +207,10 @@ async def process_request(
         if got["type"] == "http.response.start":
             status = got["status"]
             # Like above, we need to convert byte-pairs into string explicitly.
-            headers = [(k.decode(), v.decode()) for k, v in got["headers"]]
+            headers = [(k.decode(), v.decode()) for k, v in got.get("headers", [])]
 
         elif got["type"] == "http.response.body":
-            body = got["body"]
+            body = got.get("body", b"")
             more_body = got.get("more_body", False)
 
             if writer is not None:
@@ -189,6 +233,14 @@ async def process_request(
                 result.set_result(resp)
                 with acquire_js_buffer(body) as jsbytes:
                     await writer.write(jsbytes.slice())
+            elif status in NULL_BODY_STATUSES:
+                # 101/103/204/205/304 must not carry a body per the Fetch spec.
+                # https://fetch.spec.whatwg.org/#null-body-status
+                resp = Response.new(
+                    None, headers=Object.fromEntries(headers), status=status
+                )
+                result.set_result(resp)
+                finished_response.set()
             else:
                 # Complete body in a single chunk
                 px = create_proxy(body)

workers_runtime_sdk-1.6.1/src/workers/wsgi.py

@@ -0,0 +1,372 @@
+import io
+import logging
+import sys
+from collections.abc import Callable, Iterator
+from typing import Any
+from urllib.parse import unquote, urlsplit
+
+import js
+
+from workers import Context, Request
+
+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:  # noqa: BLE001 - best-effort cleanup
+            pass
+
+
+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"")
+    # `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]:
+    # `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
+
+    req_headers = req.headers.items() if isinstance(req, Request) else req.headers
+
+    url = urlsplit(req.url)
+    scheme = url.scheme
+    if not scheme:
+        raise ValueError(f"Request URL is not absolute: {req.url!r}")
+
+    # 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
+
+    server_port = str(url.port) if url.port else ("443" if scheme == "https" else "80")
+
+    method = req.method
+    # `workers.Request.method` is an `http.HTTPMethod` (a str subclass); coerce
+    # to a plain string so frameworks comparing against literals behave.
+    method = str(method.value) if hasattr(method, "value") else str(method)
+
+    environ: dict[str, Any] = {
+        "REQUEST_METHOD": method,
+        "SCRIPT_NAME": "",
+        "PATH_INFO": path_info,
+        "QUERY_STRING": query_string,
+        # 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,
+        "SERVER_PROTOCOL": "HTTP/1.1",
+        "wsgi.version": (1, 0),
+        "wsgi.url_scheme": 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,
+    }
+
+    for key, value in req_headers:
+        name = key.upper().replace("-", "_")
+        if name in ("CONTENT_TYPE", "CONTENT_LENGTH"):
+            environ[name] = value
+        else:
+            http_name = "HTTP_" + name
+            if http_name in environ:
+                # Repeated headers are folded into a single comma-separated value.
+                environ[http_name] += "," + value
+            else:
+                environ[http_name] = value
+
+    # 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 _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 Headers as JsHeaders
+    from js import ReadableStream, Response
+    from pyodide.ffi import create_proxy
+
+    # WSGI status is e.g. "200 OK"; split into code + reason phrase.
+    code_str, _, reason = status.partition(" ")
+    options: dict[str, Any] = {"status": int(code_str)}
+    if reason:
+        options["statusText"] = reason
+
+    js_headers = JsHeaders.new()
+    for key, value in headers:
+        # `append` (not `set`) preserves repeated headers such as Set-Cookie.
+        js_headers.append(key, value)
+    options["headers"] = js_headers
+
+    proxies: list[Any] = []
+    done = False
+
+    def cleanup() -> None:
+        nonlocal done
+        if done:
+            return
+        done = True
+        try:
+            on_close()
+        finally:
+            for proxy in proxies:
+                proxy.destroy()
+
+    @create_proxy
+    def pull(controller: Any) -> None:
+        try:
+            chunk = next(chunks, _END)
+        except Exception as exc:  # noqa: BLE001 - forward app errors to the stream
+            logger.exception("Exception while streaming WSGI response body")
+            cleanup()
+            controller.error(str(exc))
+            return
+        if chunk is _END:
+            controller.close()
+            cleanup()
+            return
+        controller.enqueue(_to_js_uint8array(chunk))
+
+    @create_proxy
+    def cancel(_reason: Any = None) -> None:
+        cleanup()
+
+    proxies = [pull, cancel]
+    return Response.new(ReadableStream.new(pull=pull, cancel=cancel), **options)
+
+
+def process_request(
+    app: Any,
+    req: "Request | js.Request",
+    env: Any,
+    body: "bytes | io.IOBase",
+) -> js.Response:
+    environ = build_environ(req, env, body)
+
+    response_state: dict[str, Any] = {"status": None, "headers": None}
+    # 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.
+    write_chunks: list[bytes] = []
+
+    def write(chunk: bytes) -> None:
+        if response_state["status"] is None:
+            raise AssertionError("write() called before start_response()")
+        if chunk:
+            write_chunks.append(chunk)
+
+    def start_response(status, response_headers, exc_info=None):
+        if exc_info is not None:
+            try:
+                if response_state["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 response_state["status"] is not None:
+            raise AssertionError("start_response() called more than once")
+
+        response_state["status"] = status
+        response_state["headers"] = response_headers
+        return write
+
+    result = app(environ, start_response)
+    result_iter = iter(result)
+
+    def close_all() -> None:
+        _close_iterable(result)
+        try:
+            environ["wsgi.input"].close()
+        except Exception:  # noqa: BLE001 - best-effort cleanup
+            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 = _END
+        for chunk in result_iter:
+            if chunk:
+                first_chunk = chunk
+                break
+    except Exception:
+        close_all()
+        raise
+
+    if response_state["status"] is None:
+        close_all()
+        raise RuntimeError("The WSGI application did not call start_response()")
+
+    def body_chunks() -> "Iterator[bytes]":
+        yield from write_chunks
+        if first_chunk is not _END:
+            yield first_chunk
+        for chunk in result_iter:
+            if chunk:
+                yield chunk
+
+    return _make_streaming_response(
+        response_state["status"], response_state["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 | 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

{workers_runtime_sdk-1.5.4 → workers_runtime_sdk-1.6.1}/uv.lock

@@ -229,7 +229,7 @@ wheels = [
 
 [[package]]
 name = "workers-runtime-sdk"
-version = "1.5.4"
+version = "1.6.1"
 source = { editable = "." }
 
 [package.dev-dependencies]