workers-runtime-sdk 1.9.4__tar.gz → 1.9.6__tar.gz

{workers_runtime_sdk-1.9.4 → workers_runtime_sdk-1.9.6}/AGENTS.md

@@ -16,6 +16,7 @@ This package provides utilities for:
 - `_pyodide_entrypoint_helper` and `_cloudflare_compat_flags` are internal values that are imported from `workerd`.
   - `workerd` (https://github.com/cloudflare/workerd) is the runtime that Cloudflare Workers use to run Python code.
 - When using a feature from `workerd`, always check if we can implement it in this package instead to avoid tight coupling with the runtime.
+- Code shared by the ASGI (`workers/asgi.py`) and WSGI (`workers/wsgi.py`) adapters lives in the `workers/gateway/` directory.
 
 ## Testing
 

{workers_runtime_sdk-1.9.4 → workers_runtime_sdk-1.9.6}/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 <!-- version list -->
 
+## v1.9.6 (2026-11-04)
+
+### Bug Fixes
+
+- **runtime-sdk**: Fix contextvars not being properly shared in WSGI streaming response
+  ([#288](https://github.com/cloudflare/workers-py/pull/288),
+  [`7cc6cbd`](https://github.com/cloudflare/workers-py/commit/7cc6cbd9253cc581dbb53e9254aa063b643f1183))
+
+
+## v1.9.5 (2026-10-20)
+
+### Bug Fixes
+
+- **runtime-sdk**: Add options argument to asgi and wsgi
+  ([#289](https://github.com/cloudflare/workers-py/pull/289),
+  [`eec1e54`](https://github.com/cloudflare/workers-py/commit/eec1e54fa0348e6c90161d7f1f022344e4e6e867))
+
+
 ## v1.9.4 (2026-10-16)
 
 ### Bug Fixes

{workers_runtime_sdk-1.9.4 → workers_runtime_sdk-1.9.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: workers-runtime-sdk
-Version: 1.9.4
+Version: 1.9.6
 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.9.4 → workers_runtime_sdk-1.9.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "workers-runtime-sdk"
-version = "1.9.4"
+version = "1.9.6"
 description = "Python SDK for Cloudflare Workers"
 readme = "README.md"
 license = "MIT"

{workers_runtime_sdk-1.9.4 → workers_runtime_sdk-1.9.6}/src/workers/asgi.py

@@ -2,12 +2,14 @@ import logging
 from asyncio import Event, Future, Queue, create_task, ensure_future
 from collections.abc import Awaitable
 from contextlib import contextmanager
+from dataclasses import dataclass
 from typing import Any
 from urllib.parse import unquote
 
 import js
 
 from workers import Context, Request, WorkerEntrypoint
+from workers.gateway import BaseOptions
 from workers.utils import _to_js_headers
 
 ASGI = {"spec_version": "2.0", "version": "3.0"}
@@ -16,6 +18,14 @@ logger = logging.getLogger("asgi")
 background_tasks = set()
 
 
+@dataclass(frozen=True, kw_only=True)
+class Options(BaseOptions):
+    """Options for the ASGI adapter"""
+
+
+DEFAULT_OPTIONS = Options()
+
+
 def run_in_background(coro: Awaitable[Any]) -> Future:
     fut = ensure_future(coro)
     background_tasks.add(fut)
@@ -195,10 +205,12 @@ async def process_request(  # noqa: PLR0913
     # TODO(later): remove this parameter after unvendoring Python SDK from workerd
     ctx: Context | None,
     state: dict[str, Any] | None = None,
+    options: Options = DEFAULT_OPTIONS,
 ) -> tuple[js.Response, Future[None]]:
     from js import Response, TransformStream
     from pyodide.ffi import create_proxy
 
+    response_init = options.response_init()
     status = None
     headers = None
     result = Future()
@@ -262,7 +274,10 @@ async def process_request(  # noqa: PLR0913
                 readable = transform_stream.readable
                 writer = transform_stream.writable.getWriter()
                 resp = Response.new(
-                    readable, headers=_to_js_headers(headers), status=status
+                    readable,
+                    headers=_to_js_headers(headers),
+                    status=status,
+                    **response_init,
                 )
                 result.set_result(resp)
                 with acquire_js_buffer(body) as jsbytes:
@@ -271,7 +286,10 @@ async def process_request(  # noqa: PLR0913
                 # 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=_to_js_headers(headers), status=status
+                    None,
+                    headers=_to_js_headers(headers),
+                    status=status,
+                    **response_init,
                 )
                 result.set_result(resp)
                 finished_response.set()
@@ -281,7 +299,10 @@ async def process_request(  # noqa: PLR0913
                 buf = px.getBuffer()
                 px.destroy()
                 resp = Response.new(
-                    buf.data, headers=_to_js_headers(headers), status=status
+                    buf.data,
+                    headers=_to_js_headers(headers),
+                    status=status,
+                    **response_init,
                 )
                 result.set_result(resp)
                 finished_response.set()
@@ -436,12 +457,19 @@ async def process_websocket(
 
 
 async def fetch(
-    app: Any, req: "Request | js.Request", env: Any, ctx: Context | None = None
+    app: Any,
+    req: "Request | js.Request",
+    env: Any,
+    ctx: Context | None = None,
+    *,
+    options: Options | None = None,
 ) -> js.Response:
     logger.debug("ASGI request: %s %s", req.method, req.url)
     shutdown, state = await start_application(app)
     try:
-        result, request_task = await process_request(app, req, env, ctx, state=state)
+        result, request_task = await process_request(
+            app, req, env, ctx, state=state, options=options or DEFAULT_OPTIONS
+        )
     except Exception:
         logger.exception("ASGI request failed")
         await shutdown()
@@ -469,14 +497,14 @@ async def websocket(
     return await process_websocket(app, req, env)
 
 
-def entrypoint(app: Any) -> type[WorkerEntrypoint]:
+def entrypoint(app: Any, *, options: Options | None = None) -> type[WorkerEntrypoint]:
     """Create the default Worker entrypoint for an ASGI application."""
 
     class Default(WorkerEntrypoint):
         async def fetch(self, request):
             if (request.headers.get("upgrade") or "").lower() == "websocket":
                 return await websocket(app, request, self.env)
-            return await fetch(app, request, self.env, self.ctx)
+            return await fetch(app, request, self.env, self.ctx, options=options)
 
     return Default
 

workers_runtime_sdk-1.9.6/src/workers/gateway/__init__.py

@@ -0,0 +1,5 @@
+"""Shared building blocks for the ASGI and WSGI adapters."""
+
+from .options import BaseOptions, EncodeBody
+
+__all__ = ["BaseOptions", "EncodeBody"]

workers_runtime_sdk-1.9.6/src/workers/gateway/options.py

@@ -0,0 +1,30 @@
+from dataclasses import dataclass
+from typing import Any, Literal, get_args
+
+EncodeBody = Literal["automatic", "manual"]
+
+
+@dataclass(frozen=True, kw_only=True)
+class BaseOptions:
+    """Options shared by the ASGI and WSGI adapters.
+
+    Downstream adapters should inherit from this class to define their own options.
+    """
+
+    # Whether to encode the body according to the ``Content-Encoding`` header
+    # See https://developers.cloudflare.com/workers/runtime-apis/response/#the-encodebody-option
+    encode_body: EncodeBody = "automatic"
+
+    def __post_init__(self) -> None:
+        if self.encode_body not in get_args(EncodeBody):
+            raise ValueError(
+                f"encode_body must be one of {get_args(EncodeBody)}, "
+                f"got {self.encode_body!r}"
+            )
+
+    def response_init(self) -> dict[str, Any]:
+        """Extra keyword arguments for ``Response.new``."""
+        init: dict[str, Any] = {}
+        if self.encode_body != "automatic":
+            init["encodeBody"] = self.encode_body
+        return init

{workers_runtime_sdk-1.9.4 → workers_runtime_sdk-1.9.6}/src/workers/wsgi.py

@@ -1,18 +1,29 @@
+import contextvars
 import io
 import logging
 import sys
 from collections.abc import Callable, Iterator
+from dataclasses import dataclass
 from typing import Any
 from urllib.parse import unquote, urlsplit
 
 import js
 
 from workers import Context, Request, WorkerEntrypoint
+from workers.gateway import BaseOptions
 
 logger = logging.getLogger("wsgi")
 NULL_BODY_STATUSES = frozenset({101, 103, 204, 205, 304})
 
 
+@dataclass(frozen=True, kw_only=True)
+class Options(BaseOptions):
+    """Options for the WSGI adapter, see ``BaseOptions`` for shared fields."""
+
+
+DEFAULT_OPTIONS = Options()
+
+
 def _wsgi_native_string(value: str) -> str:
     """Convert a (possibly non-ASCII) Python ``str`` into a WSGI "native string".
 
@@ -212,11 +223,20 @@ def _close_iterable(iterable: Any) -> None:
 _END = object()
 
 
+def _iter_in_context(
+    context: contextvars.Context, iterator: "Iterator[Any]"
+) -> "Iterator[Any]":
+    """Make sure every chunk is produced in the given context."""
+    while (chunk := context.run(next, iterator, _END)) is not _END:
+        yield chunk
+
+
 def _make_streaming_response(
     status: str,
     headers: "list[tuple[str, str]]",
     chunks: "Iterator[bytes]",
     on_close: "Callable[[], None]",
+    response_init: dict[str, Any],
 ) -> js.Response:
     """Build a ``js.Response`` whose body is pulled lazily from *chunks*.
 
@@ -232,7 +252,7 @@ def _make_streaming_response(
     # WSGI status is e.g. "200 OK"; split into code + reason phrase.
     code_str, _, reason = status.partition(" ")
     code = int(code_str)
-    options: dict[str, Any] = {"status": code}
+    options: dict[str, Any] = {"status": code, **response_init}
     if reason:
         options["statusText"] = reason
 
@@ -291,6 +311,7 @@ def process_request(
     req: "Request | js.Request",
     env: Any,
     body: "bytes | io.IOBase",
+    options: Options = DEFAULT_OPTIONS,
 ) -> js.Response:
     environ = build_environ(req, env, body)
 
@@ -321,15 +342,21 @@ def process_request(
         response_state["headers"] = response_headers
         return write
 
-    result = app(environ, start_response)
-    result_iter = iter(result)
+    # Make sure a single context is used per response.
+    # Otherwise, stack switching could cause context variables set by the app
+    # to be lost when the iterable is consumed.
+    context = contextvars.copy_context()
+    result = context.run(app, environ, start_response)
+    result_iter = _iter_in_context(context, context.run(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")
+            context.run(_close_iterable, result)
+        finally:
+            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
@@ -357,7 +384,11 @@ def process_request(
                 yield chunk
 
     return _make_streaming_response(
-        response_state["status"], response_state["headers"], body_chunks(), close_all
+        response_state["status"],
+        response_state["headers"],
+        body_chunks(),
+        close_all,
+        options.response_init(),
     )
 
 
@@ -367,6 +398,8 @@ async def fetch(
     env: Any,
     # Accepted for parity with asgi.fetch; WSGI has no use for it.
     ctx: Context | None = None,
+    *,
+    options: Options | 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);
@@ -375,17 +408,17 @@ async def fetch(
     if body is None:
         body = await _read_body(req)
     try:
-        return process_request(app, req, env, body)
+        return process_request(app, req, env, body, options or DEFAULT_OPTIONS)
     except Exception:
         logger.exception("WSGI request failed")
         raise
 
 
-def entrypoint(app: Any) -> type[WorkerEntrypoint]:
+def entrypoint(app: Any, *, options: Options | None = None) -> 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 await fetch(app, request, self.env, options=options)
 
     return Default

{workers_runtime_sdk-1.9.4 → workers_runtime_sdk-1.9.6}/tests/web-frameworks-test/flask-tests/pyproject.toml

@@ -2,7 +2,13 @@
 name = "flask-tests"
 version = "0.1.0"
 requires-python = ">=3.12"
-dependencies = ["flask", "pytest", "testlib", "workers-runtime-sdk"]
+dependencies = [
+    "flask",
+    "pytest",
+    "pytest-asyncio<1.2.0",
+    "testlib",
+    "workers-runtime-sdk",
+]
 
 [tool.uv.sources]
 testlib = { path = "../packages/testlib" }

workers_runtime_sdk-1.9.6/tests/web-frameworks-test/flask-tests/src/test_stream_with_context.py

@@ -0,0 +1,70 @@
+import asyncio
+
+import js
+import pytest
+from flask import (
+    Flask,
+    Response,
+    has_request_context,
+    request,
+    stream_with_context,
+)
+
+from workers import wsgi
+
+app = Flask(__name__)
+# Request values whose stream_with_context generator has run its cleanup.
+closed: list[str] = []
+
+
+@app.get("/stream")
+def stream():
+    @stream_with_context
+    def body():
+        value = request.args["value"]
+        try:
+            yield "flask:"
+            yield request.args["value"]
+        finally:
+            closed.append(value)
+
+    return Response(body(), content_type="text/plain")
+
+
+async def fetch(value):
+    req = js.Request.new(f"http://example.com/stream?value={value}")
+    return await wsgi.fetch(app, req, {})
+
+
+@pytest.fixture(autouse=True)
+def clear_closed():
+    closed.clear()
+
+
+@pytest.mark.asyncio
+async def test_stream_with_context():
+    response = await fetch("stream-body")
+    assert response.status == 200
+    # The request context pushed while priming the body must stay in the
+    # response's own context instead of leaking into the caller's.
+    assert not has_request_context()
+    assert await response.text() == "flask:stream-body"
+    assert closed == ["stream-body"]
+
+
+@pytest.mark.asyncio
+async def test_concurrent_stream_with_context():
+    responses = await asyncio.gather(fetch("first"), fetch("second"))
+    bodies = await asyncio.gather(*(response.text() for response in responses))
+    assert bodies == ["flask:first", "flask:second"]
+    assert sorted(closed) == ["first", "second"]
+
+
+@pytest.mark.asyncio
+async def test_cancelled_stream_with_context():
+    response = await fetch("cancel")
+    reader = response.body.getReader()
+    first = await reader.read()
+    assert first.value.to_bytes() == b"flask:"
+    await reader.cancel()
+    assert closed == ["cancel"]

workers_runtime_sdk-1.9.6/tests/workerd-test/asgi/asgi.wd-test

@@ -0,0 +1,36 @@
+using Workerd = import "/workerd/workerd.capnp";
+
+const unitTests :Workerd.Config = (
+  services = [
+    ( name = "python-asgi",
+      worker = (
+        modules = [
+          (name = "worker.py", pythonModule = embed "worker.py"),
+          %PYTHON_MODULES
+        ],
+        bindings = [
+          ( name = "SELF", service = "python-asgi" ),
+          # SELF.fetch does not serialize the response over HTTP, so it cannot
+          # observe the runtime encoding the body. ASGI_HTTP goes through the
+          # loopback HTTP socket below instead.
+          ( name = "ASGI_HTTP", service = "asgi-http" ),
+        ],
+        compatibilityDate = "%COMPAT_DATE",
+        compatibilityFlags = ["python_workers"],
+      )
+    ),
+    ( name = "asgi-http",
+      external = (
+        address = "loopback:asgi-http",
+        http = (),
+      )
+    ),
+  ],
+  sockets = [
+    ( name = "asgi-http",
+      address = "loopback:asgi-http",
+      http = (),
+      service = "python-asgi",
+    ),
+  ],
+);

{workers_runtime_sdk-1.9.4 → workers_runtime_sdk-1.9.6}/tests/workerd-test/asgi/tests/test_asgi.py

@@ -1,11 +1,17 @@
 import asyncio
+import gzip
 import json
 import logging
 
 import js
 import pytest
 from pyodide.ffi import to_js
-from worker import STREAMING_CHUNK_SIZE, STREAMING_NUM_CHUNKS, example_hdr
+from worker import (
+    ENCODED_RESPONSE_PAYLOAD,
+    STREAMING_CHUNK_SIZE,
+    STREAMING_NUM_CHUNKS,
+    example_hdr,
+)
 
 import asgi
 from workers import Request, env
@@ -474,3 +480,35 @@ async def test_lifespan_preack_crash_is_logged_and_treated_as_unsupported():
         )
     finally:
         _remove_handler(handler)
+
+
+def test_options_validate_encode_body():
+    assert asgi.Options().response_init() == {}
+    assert asgi.Options(encode_body="manual").response_init() == {
+        "encodeBody": "manual"
+    }
+    with pytest.raises(ValueError, match="encode_body"):
+        asgi.Options(encode_body="gzip")
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("mode", ["buffered", "streaming"])
+@pytest.mark.parametrize("encoding", ["gzip", "identity"])
+@pytest.mark.parametrize("encode_body", ["automatic", "manual"])
+async def test_encode_body_option(encode_body, encoding, mode):
+    # SELF.fetch does not serialize the response over HTTP, so it cannot
+    # observe the runtime encoding the body; ASGI_HTTP goes over a socket.
+    response = await env.ASGI_HTTP.fetch(
+        f"http://example.com/encoded/{encoding}/{mode}/{encode_body}",
+        headers={"accept-encoding": "gzip"},
+    )
+    assert response.status == 200
+    assert response.headers["content-encoding"] == encoding
+
+    # fetch() decodes the declared Content-Encoding once, like a browser.
+    body = await response.bytes()
+    if encoding == "gzip" and encode_body == "automatic":
+        # The runtime gzips the app's already-gzipped bytes a second time.
+        assert gzip.decompress(body) == ENCODED_RESPONSE_PAYLOAD
+    else:
+        assert body == ENCODED_RESPONSE_PAYLOAD

{workers_runtime_sdk-1.9.4 → workers_runtime_sdk-1.9.6}/tests/workerd-test/asgi/worker.py

@@ -1,9 +1,11 @@
+import gzip
 import os
 
 from testlib.entrypoint import run_pytest
 
 import asgi
 from workers import WorkerEntrypoint
+from workers.asgi import Options
 
 # ---------------------------------------------------------------------------
 # ASGI apps
@@ -238,6 +240,54 @@ class MultiCookieApp:
         await send({"type": "http.response.body", "body": b"ok"})
 
 
+ENCODED_RESPONSE_PAYLOAD = b'{"message":"already encoded by the app"}' * 64
+
+
+class EncodedResponseApp:
+    """Sends a body the app has already encoded to match Content-Encoding."""
+
+    def __init__(self, encoding, streaming):
+        self.encoding = encoding
+        self.streaming = streaming
+        self.body = (
+            gzip.compress(ENCODED_RESPONSE_PAYLOAD, mtime=0)
+            if encoding == "gzip"
+            else ENCODED_RESPONSE_PAYLOAD
+        )
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] == "lifespan":
+            message = await receive()
+            if message["type"] == "lifespan.startup":
+                await send({"type": "lifespan.startup.complete"})
+            return
+        await receive()
+        await send(
+            {
+                "type": "http.response.start",
+                "status": 200,
+                "headers": [
+                    (b"content-type", b"application/json"),
+                    (b"content-encoding", self.encoding.encode()),
+                ],
+            }
+        )
+        if not self.streaming:
+            await send({"type": "http.response.body", "body": self.body})
+            return
+        # Split one gzip member across chunks (inside its header and before
+        # its footer) and finish with an empty terminal chunk.
+        chunks = (self.body[:7], self.body[7:-8], self.body[-8:], b"")
+        for i, chunk in enumerate(chunks):
+            await send(
+                {
+                    "type": "http.response.body",
+                    "body": chunk,
+                    "more_body": i < len(chunks) - 1,
+                }
+            )
+
+
 app = HeaderEchoApp()
 sse_app = SSEApp()
 streaming_app = StreamingApp()
@@ -267,6 +317,16 @@ class Default(WorkerEntrypoint):
             )
         elif path == "/multi-cookie":
             return await asgi.fetch(multi_cookie_app, request, self.env, self.ctx)
+        elif path.startswith("/encoded/"):
+            # /encoded/<gzip|identity>/<buffered|streaming>/<automatic|manual>
+            _, _, encoding, mode, encode_body = path.split("/")
+            return await asgi.fetch(
+                EncodedResponseApp(encoding, streaming=mode == "streaming"),
+                request,
+                self.env,
+                self.ctx,
+                options=Options(encode_body=encode_body),
+            )
 
         return await asgi.fetch(app, request, self.env, self.ctx)
 

{workers_runtime_sdk-1.9.4 → workers_runtime_sdk-1.9.6}/tests/workerd-test/asgi-ws-disconnect/tests/test_ws_disconnect.py

@@ -99,10 +99,16 @@ async def _ws_session(path):
     # Without this the payload arrives as a Blob, which cannot be read
     # synchronously in the message callback.
     ws.binaryType = "arraybuffer"
+    # The app runs on this test's event loop, which pytest-asyncio closes when
+    # the test ends, cancelling an app still awaiting the disconnect. Its
+    # server socket then never closes, and workerd keeps the request open
+    # waiting for it, so wait for the server's close before returning.
+    closed = _listen(ws, "close")
     try:
         yield ws
     finally:
         ws.close()
+        await asyncio.wait_for(closed, TIMEOUT_S)
 
 
 @pytest.mark.asyncio

{workers_runtime_sdk-1.9.4 → workers_runtime_sdk-1.9.6}/tests/workerd-test/sdk/tests/test_sdk.py

@@ -498,8 +498,7 @@ async def test_response_unit_tests():
     response_json = Response.json([1, 2, 3])
     assert await response_json.text() == "[1, 2, 3]"
     assert (
-        repr(response_json)
-        == "Response(status=200, status_text='OK', content_type='application/json')"
+        repr(response_json) == "Response(status=200, content_type='application/json')"
     )
 
     response_json = Response.from_json([1, 2, 3])