workers-runtime-sdk 0.1.0__tar.gz

workers_runtime_sdk-0.1.0/.gitattributes

@@ -0,0 +1 @@
+uv.lock binary

workers_runtime_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run tests
+        run: uv run pytest

workers_runtime_sdk-0.1.0/.gitignore

@@ -0,0 +1 @@
+__pycache__

workers_runtime_sdk-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+default_language_version:
+  python: "3.13"
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: "v5.0.0"
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: check-yaml
+      - id: debug-statements
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+      - id: trailing-whitespace
+      - id: requirements-txt-fixer
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.9.1"
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: "v0.10.0.1"
+    hooks:
+      - id: shellcheck
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: "v2.3.0"
+    hooks:
+      - id: codespell
+ci:
+  autoupdate_schedule: "quarterly"

workers_runtime_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: workers-runtime-sdk
+Version: 0.1.0
+Summary: Python runtime SDK for Cloudflare Workers
+Requires-Python: >=3.12

workers_runtime_sdk-0.1.0/commitlint.yml

@@ -0,0 +1,15 @@
+name: Lint Commit Messages
+on:
+  pull_request:
+    branches: [ main ]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  commitlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: wagoid/commitlint-github-action@v6

workers_runtime_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "workers-runtime-sdk"
+version = "0.1.0"
+description = "Python runtime SDK for Cloudflare Workers"
+requires-python = ">=3.12"
+
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+include = ["src/*"]
+
+[dependency-groups]
+dev = [
+    "build",
+    "pre-commit>=4.3.0",
+    "pytest>=8.4.2",
+]

workers_runtime_sdk-0.1.0/release.yml

@@ -0,0 +1,139 @@
+# Based on https://python-semantic-release.readthedocs.io/en/latest/configuration/automatic-releases/github-actions.html#examples
+
+name: Continuous Delivery
+
+on:
+  push:
+    branches:
+      - main
+
+# default: least privileged permissions across all jobs
+permissions:
+  contents: read
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: ${{ github.workflow }}-release-${{ github.ref_name }}
+      cancel-in-progress: false
+
+    outputs:
+      released: ${{ steps.release.outputs.released }}
+
+    permissions:
+      contents: write
+
+    steps:
+      # Note: We checkout the repository at the branch that triggered the workflow
+      # with the entire history to ensure to match PSR's release branch detection
+      # and history evaluation.
+      # However, we forcefully reset the branch to the workflow sha because it is
+      # possible that the branch was updated while the workflow was running. This
+      # prevents accidentally releasing un-evaluated changes.
+      - name: Setup | Checkout Repository on Release Branch
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.DEVPROD_PAT }}
+          ref: main
+          fetch-depth: 0
+
+      - name: Setup | Force release branch to be at workflow sha
+        run: |
+          git reset --hard ${{ github.sha }}
+
+      - name: Evaluate | Verify upstream has NOT changed
+        # Last chance to abort before causing an error as another PR/push was applied to
+        # the upstream branch while this workflow was running. This is important
+        # because we are committing a version change (--commit). You may omit this step
+        # if you have 'commit: false' in your configuration.
+        #
+        # You may consider moving this to a repo script and call it from this step instead
+        # of writing it in-line.
+        shell: bash
+        run: |
+          set +o pipefail
+
+          UPSTREAM_BRANCH_NAME="$(git status -sb | head -n 1 | cut -d' ' -f2 | grep -E '\.{3}' | cut -d'.' -f4)"
+          printf '%s\n' "Upstream branch name: $UPSTREAM_BRANCH_NAME"
+
+          set -o pipefail
+
+          if [ -z "$UPSTREAM_BRANCH_NAME" ]; then
+              printf >&2 '%s\n' "::error::Unable to determine upstream branch name!"
+              exit 1
+          fi
+
+          git fetch "${UPSTREAM_BRANCH_NAME%%/*}"
+
+          if ! UPSTREAM_SHA="$(git rev-parse "$UPSTREAM_BRANCH_NAME")"; then
+              printf >&2 '%s\n' "::error::Unable to determine upstream branch sha!"
+              exit 1
+          fi
+
+          HEAD_SHA="$(git rev-parse HEAD)"
+
+          if [ "$HEAD_SHA" != "$UPSTREAM_SHA" ]; then
+              printf >&2 '%s\n' "[HEAD SHA] $HEAD_SHA != $UPSTREAM_SHA [UPSTREAM SHA]"
+              printf >&2 '%s\n' "::error::Upstream has changed, aborting release..."
+              exit 1
+          fi
+
+          printf '%s\n' "Verified upstream branch has not changed, continuing with release..."
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Action | Semantic Version Release
+        id: release
+        uses: python-semantic-release/python-semantic-release@v10.2.0
+        with:
+          github_token: ${{ secrets.DEVPROD_PAT }}
+          git_committer_name: "Workers DevProd"
+          git_committer_email: "workers-devprod@cloudflare.com"
+
+      - name: Publish | Upload to GitHub Release Assets
+        uses: python-semantic-release/publish-action@v10.2.0
+        if: steps.release.outputs.released == 'true'
+        with:
+          github_token: ${{ secrets.DEVPROD_PAT }}
+          tag: ${{ steps.release.outputs.tag }}
+
+      - name: Upload | Distribution Artifacts
+        uses: actions/upload-artifact@v4
+        if: steps.release.outputs.released == 'true'
+        with:
+          name: distribution-artifacts
+          path: dist
+          if-no-files-found: error
+
+  deploy:
+    # 1. Separate out the deploy step from the publish step to run each step at
+    #    the least amount of token privilege
+    # 2. Also, deployments can fail, and its better to have a separate job if you need to retry
+    #    and it won't require reversing the release.
+    runs-on: ubuntu-latest
+    needs: release
+    if: ${{ needs.release.outputs.released == 'true' }}
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Setup | Download Build Artifacts
+        uses: actions/download-artifact@v4
+        id: artifact-download
+        with:
+          name: distribution-artifacts
+          path: dist
+
+      # see https://docs.pypi.org/trusted-publishers/
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          print-hash: true
+          verbose: true

workers_runtime_sdk-0.1.0/src/asgi.py

@@ -0,0 +1,306 @@
+from asyncio import Event, Future, Queue, create_task, ensure_future, sleep
+from collections.abc import Awaitable
+from contextlib import contextmanager
+from inspect import isawaitable
+from typing import Any
+
+import js
+from workers import Context, Request
+
+ASGI = {"spec_version": "2.0", "version": "3.0"}
+
+
+background_tasks = set()
+
+
+def run_in_background(coro: Awaitable[Any]) -> None:
+    fut = ensure_future(coro)
+    background_tasks.add(fut)
+    fut.add_done_callback(background_tasks.discard)
+
+
+@contextmanager
+def acquire_js_buffer(pybuffer):
+    from pyodide.ffi import create_proxy
+
+    px = create_proxy(pybuffer)
+    buf = px.getBuffer()
+    px.destroy()
+    try:
+        yield buf.data
+    finally:
+        buf.release()
+
+
+def request_to_scope(req, env, ws=False):
+    from js import URL
+
+    # @app.get("/example")
+    # async def example(request: Request):
+    #     request.headers.get("content-type")
+    # - this will error if header is not "bytes" as in ASGI spec.
+
+    # Support both JS and Python http.client.HTTPMessage headers.
+    req_headers = req.headers.items() if isinstance(req, Request) else req.headers
+
+    headers = [(k.lower().encode(), v.encode()) for k, v in req_headers]
+    url = URL.new(req.url)
+    assert url.protocol[-1] == ":"
+    scheme = url.protocol[:-1]
+    path = url.pathname
+    assert "?".startswith(url.search[0:1])
+    query_string = url.search[1:].encode()
+    if ws:
+        ty = "websocket"
+    else:
+        ty = "http"
+    return {
+        "asgi": ASGI,
+        "headers": headers,
+        "http_version": "1.1",
+        "method": req.method,
+        "scheme": scheme,
+        "path": path,
+        "query_string": query_string,
+        "type": ty,
+        "env": env,
+    }
+
+
+async def start_application(app):
+    shutdown_future = Future()
+
+    async def shutdown():
+        shutdown_future.set_result(None)
+        await sleep(0)
+
+    it = iter([{"type": "lifespan.startup"}, Future()])
+
+    async def receive():
+        res = next(it)
+        if isawaitable(res):
+            await res
+        return res
+
+    ready = Future()
+
+    async def send(got):
+        if got["type"] == "lifespan.startup.complete":
+            ready.set_result(None)
+            return
+        if got["type"] == "lifespan.shutdown.complete":
+            return
+        raise RuntimeError(f"Unexpected lifespan event {got['type']}")
+
+    run_in_background(
+        app(
+            {
+                "asgi": ASGI,
+                "state": {},
+                "type": "lifespan",
+            },
+            receive,
+            send,
+        )
+    )
+    await ready
+    return shutdown
+
+
+async def process_request(
+    app: Any, req: "Request | js.Request", env: Any, ctx: Context
+) -> js.Response:
+    from js import Object, Response, TransformStream
+
+    from pyodide.ffi import create_proxy
+
+    status = None
+    headers = None
+    result = Future()
+    is_sse = False
+    finished_response = Event()
+
+    receive_queue = Queue()
+    if req.body:
+        async for data in req.body:
+            await receive_queue.put(
+                {
+                    "body": data.to_bytes(),
+                    "more_body": True,
+                    "type": "http.request",
+                }
+            )
+    await receive_queue.put({"body": b"", "more_body": False, "type": "http.request"})
+
+    async def receive():
+        message = None
+        if not receive_queue.empty():
+            message = await receive_queue.get()
+        else:
+            await finished_response.wait()
+            message = {"type": "http.disconnect"}
+        return message
+
+    # Create a transform stream for handling streaming responses
+    transform_stream = TransformStream.new()
+    readable = transform_stream.readable
+    writable = transform_stream.writable
+    writer = writable.getWriter()
+
+    async def send(got):
+        nonlocal status
+        nonlocal headers
+        nonlocal is_sse
+
+        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"]]
+            # Check if this is a server-sent events response
+            for k, v in headers:
+                if k.lower() == "content-type" and v.lower().startswith(
+                    "text/event-stream"
+                ):
+                    is_sse = True
+                    break
+            if is_sse:
+                # For SSE, create and return the response immediately after http.response.start
+                resp = Response.new(
+                    readable, headers=Object.fromEntries(headers), status=status
+                )
+                result.set_result(resp)
+
+        elif got["type"] == "http.response.body":
+            body = got["body"]
+            more_body = got.get("more_body", False)
+
+            # Convert body to JS buffer
+            px = create_proxy(body)
+            buf = px.getBuffer()
+            px.destroy()
+
+            if is_sse:
+                # For SSE, write chunk to the stream
+                await writer.write(buf.data)
+                # If this is the last chunk, close the writer
+                if not more_body:
+                    await writer.close()
+                    finished_response.set()
+            else:
+                resp = Response.new(
+                    buf.data, headers=Object.fromEntries(headers), status=status
+                )
+                result.set_result(resp)
+                await writer.close()
+                finished_response.set()
+
+    # Run the application in the background to handle SSE
+    async def run_app():
+        try:
+            await app(request_to_scope(req, env), receive, send)
+
+            # If we get here and no response has been set yet, the app didn't generate a response
+            if not result.done():
+                raise RuntimeError("The application did not generate a response")  # noqa: TRY301
+        except Exception as e:
+            # Handle any errors in the application
+            if not result.done():
+                result.set_exception(e)
+                await writer.close()  # Close the writer
+                finished_response.set()
+
+    # Create task to run the application in the background
+    app_task = create_task(run_app())
+
+    # Wait for the result (the response)
+    response = await result
+
+    # For non-SSE responses, we need to wait for the application to complete
+    if not is_sse:
+        await app_task
+    else:  # noqa: PLR5501
+        if ctx is not None:
+            ctx.waitUntil(create_proxy(app_task))
+        else:
+            raise RuntimeError(
+                "Server-Side-Events require ctx to be passed to asgi.fetch"
+            )
+    return response
+
+
+async def process_websocket(app: Any, req: "Request | js.Request") -> js.Response:
+    from js import Response, WebSocketPair
+
+    client, server = WebSocketPair.new().object_values()
+    server.accept()
+    queue = Queue()
+
+    def onopen(evt):
+        msg = {"type": "websocket.connect"}
+        queue.put_nowait(msg)
+
+    # onopen doesn't seem to get called. WS lifecycle events are a bit messed up
+    # here.
+    onopen(1)
+
+    def onclose(evt):
+        msg = {"type": "websocket.close", "code": evt.code, "reason": evt.reason}
+        queue.put_nowait(msg)
+
+    def onmessage(evt):
+        msg = {"type": "websocket.receive", "text": evt.data}
+        queue.put_nowait(msg)
+
+    server.onopen = onopen
+    server.onopen = onclose
+    server.onmessage = onmessage
+
+    async def ws_send(got):
+        if got["type"] == "websocket.send":
+            b = got.get("bytes", None)
+            s = got.get("text", None)
+            if b:
+                with acquire_js_buffer(b) as jsbytes:
+                    # Unlike the `Response` constructor,  server.send seems to
+                    # eagerly copy the source buffer
+                    server.send(jsbytes)
+            if s:
+                server.send(s)
+
+        else:
+            print(" == Not implemented", got["type"])
+
+    async def ws_receive():
+        received = await queue.get()
+        return received
+
+    env = {}
+    run_in_background(app(request_to_scope(req, env, ws=True), ws_receive, ws_send))
+
+    return Response.new(None, status=101, webSocket=client)
+
+
+async def fetch(
+    app: Any, req: "Request | js.Request", env: Any, ctx: Context | None = None
+) -> js.Response:
+    shutdown = await start_application(app)
+    result = await process_request(app, req, env, ctx)
+    await shutdown()
+    return result
+
+
+async def websocket(app: Any, req: "Request | js.Request") -> js.Response:
+    return await process_websocket(app, req)
+
+
+def __getattr__(name):
+    if name == "env":
+        from fastapi import Depends, Request
+
+        @Depends
+        async def env(request: Request):
+            return request.scope["env"]
+
+        return env
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

workers_runtime_sdk-0.1.0/src/workers/__init__.py

@@ -0,0 +1,51 @@
+from ._workers import (
+    Blob,
+    BlobEnding,
+    BlobValue,
+    Body,
+    Context,
+    DurableObject,
+    FetchKwargs,
+    FetchResponse,
+    File,
+    FormData,
+    FormDataValue,
+    Headers,
+    JSBody,
+    Request,
+    RequestInitCfProperties,
+    Response,
+    WorkerEntrypoint,
+    WorkflowEntrypoint,
+    fetch,
+    handler,
+    import_from_javascript,
+    python_from_rpc,
+    python_to_rpc,
+)
+
+__all__ = [
+    "Blob",
+    "BlobEnding",
+    "BlobValue",
+    "Body",
+    "Context",
+    "DurableObject",
+    "FetchKwargs",
+    "FetchResponse",
+    "File",
+    "FormData",
+    "FormDataValue",
+    "Headers",
+    "JSBody",
+    "Request",
+    "RequestInitCfProperties",
+    "Response",
+    "WorkerEntrypoint",
+    "WorkflowEntrypoint",
+    "fetch",
+    "handler",
+    "import_from_javascript",
+    "python_from_rpc",
+    "python_to_rpc",
+]