crosswind-workers 0.1.0__py3-none-any.whl

workers/context.py

@@ -0,0 +1,230 @@
+"""The context an entrypoint receives as `ctx`.
+
+As in the stock SDK, names these classes don't define pass through raw: the
+JS value comes back unconverted. Python wrappers passed as arguments are
+unwrapped to their JS objects first.
+"""
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from datetime import datetime
+from functools import cached_property
+from typing import Any
+
+import js
+from pyodide.ffi import create_once_callable, create_proxy
+
+from ._js import js_name
+from .bindings import Binding, _js_options
+from .rpc import python_from_rpc, python_to_rpc
+
+__all__ = [
+    "DurableObjectAbort",
+    "DurableObjectContext",
+    "DurableObjectStorage",
+    "ExecutionContext",
+    "js_promise",
+]
+
+
+class DurableObjectAbort(BaseException):
+    """Raised by `ctx.abort()`. A BaseException, so `except Exception` lets it
+    through, and the Durable Object is reset."""
+
+
+class _RawContext(Binding):
+    @property
+    def _ctx(self) -> Any:
+        # The stock SDK's private name for the JS context, which its tests and
+        # the agents port read.
+        return self.js_object
+
+    def _pass_through(self, name: str, value: Any) -> Any:
+        if not callable(value):
+            return value
+        return lambda *args, **kwargs: value(
+            *map(_unwrap, args), **{k: _unwrap(v) for k, v in kwargs.items()}
+        )
+
+    def wait_until(self, awaitable: Awaitable[Any]) -> None:
+        """Keep the invocation alive until `awaitable`, a coroutine, task or
+        JS promise, finishes."""
+        self.js_object.waitUntil(js_promise(awaitable))
+
+
+def js_promise(awaitable: Any) -> Any:
+    """A JS promise that settles when `awaitable` does.
+
+    Handing JS a coroutine loses it once the call returns, unless workerd's
+    patchWaitUntil applies, and it applies only to an ExecutionContext. So JS
+    gets a real promise that follows a task through a persistent proxy, which
+    is destroyed once the promise settles.
+    """
+    if js_name(awaitable) == "Promise":
+        return awaitable
+    proxy = create_proxy(asyncio.ensure_future(awaitable))
+    return js.Promise.resolve(proxy).finally_(create_once_callable(proxy.destroy))
+
+
+def _unwrap(value: Any) -> Any:
+    return getattr(value, "js_object", value)
+
+
+class ExecutionContext(_RawContext):
+    """The `ctx` of a WorkerEntrypoint."""
+
+    def pass_through_on_exception(self) -> None:
+        self.js_object.passThroughOnException()
+
+
+class DurableObjectStorage(Binding):
+    """A Durable Object's storage. Unlisted names, such as `sql`, pass through
+    with values converted, as in the stock SDK."""
+
+    async def get(
+        self,
+        keys: Any,
+        options: Any = None,
+        /,
+        *,
+        allow_concurrency: bool | None = None,
+        no_cache: bool | None = None,
+        **extra: Any,
+    ) -> Any:
+        """One value for a key, or a dict for a list of keys."""
+        js_options = _js_options(
+            options, extra, allow_concurrency=allow_concurrency, no_cache=no_cache
+        )
+        return python_from_rpc(
+            await self.js_object.get(python_to_rpc(keys), js_options)
+        )
+
+    async def put(
+        self,
+        key_or_entries: Any,
+        *args: Any,
+        allow_concurrency: bool | None = None,
+        allow_unconfirmed: bool | None = None,
+        no_cache: bool | None = None,
+        **extra: Any,
+    ) -> None:
+        """`put(key, value[, options])` or `put(entries[, options])`."""
+        named = {
+            "allow_concurrency": allow_concurrency,
+            "allow_unconfirmed": allow_unconfirmed,
+            "no_cache": no_cache,
+        }
+
+        if isinstance(key_or_entries, str):
+            if not 1 <= len(args) <= 2:
+                raise TypeError("put(key, value[, options]) needs a value")
+            value, options = args[0], args[1] if len(args) == 2 else None
+            js_value = python_to_rpc(value)
+            js_options = _js_options(options, extra, **named)
+            await self.js_object.put(key_or_entries, js_value, js_options)
+        else:
+            if len(args) > 1:
+                raise TypeError("put(entries[, options]) takes no value")
+            js_options = _js_options(args[0] if args else None, extra, **named)
+            await self.js_object.put(python_to_rpc(key_or_entries), js_options)
+
+    async def delete(
+        self,
+        keys: Any,
+        options: Any = None,
+        /,
+        *,
+        allow_unconfirmed: bool | None = None,
+        no_cache: bool | None = None,
+        **extra: Any,
+    ) -> Any:
+        """Whether a key existed, or how many of a list of keys did."""
+        js_options = _js_options(
+            options, extra, allow_unconfirmed=allow_unconfirmed, no_cache=no_cache
+        )
+        return await self.js_object.delete(python_to_rpc(keys), js_options)
+
+    async def delete_all(self, options: Any = None, /, **extra: Any) -> None:
+        await self.js_object.deleteAll(_js_options(options, extra))
+
+    async def list(
+        self,
+        options: Any = None,
+        /,
+        *,
+        start: str | None = None,
+        start_after: str | None = None,
+        end: str | None = None,
+        prefix: str | None = None,
+        reverse: bool | None = None,
+        limit: int | None = None,
+        **extra: Any,
+    ) -> dict[str, Any]:
+        js_options = _js_options(
+            options,
+            extra,
+            start=start,
+            start_after=start_after,
+            end=end,
+            prefix=prefix,
+            reverse=reverse,
+            limit=limit,
+        )
+        return python_from_rpc(await self.js_object.list(js_options))
+
+    async def get_alarm(self, options: Any = None, /, **extra: Any) -> int | None:
+        """The scheduled alarm time in milliseconds since the epoch."""
+        return python_from_rpc(
+            await self.js_object.getAlarm(_js_options(options, extra))
+        )
+
+    async def set_alarm(
+        self, scheduled_time: datetime | int, options: Any = None, /, **extra: Any
+    ) -> None:
+        """Schedule `alarm` at a datetime or at milliseconds since the epoch."""
+        if isinstance(scheduled_time, datetime):
+            scheduled_time = int(scheduled_time.timestamp() * 1000)
+        js_options = _js_options(options, extra)
+        await self.js_object.setAlarm(scheduled_time, js_options)
+
+    async def delete_alarm(self, options: Any = None, /, **extra: Any) -> None:
+        await self.js_object.deleteAlarm(_js_options(options, extra))
+
+
+class DurableObjectContext(_RawContext):
+    """The `ctx` of a Durable Object: the JS DurableObjectState."""
+
+    @cached_property
+    def storage(self) -> DurableObjectStorage:
+        return DurableObjectStorage(self.js_object.storage)
+
+    @property
+    def id(self) -> Any:
+        return self.js_object.id
+
+    async def block_concurrency_while(
+        self, callback: Callable[[], Awaitable[Any]]
+    ) -> Any:
+        return python_from_rpc(await self.js_object.blockConcurrencyWhile(callback))
+
+    def accept_web_socket(self, ws: Any, tags: list[str] | None = None) -> None:
+        if tags is None:
+            self.js_object.acceptWebSocket(_unwrap(ws))
+        else:
+            self.js_object.acceptWebSocket(_unwrap(ws), python_to_rpc(tags))
+
+    def get_web_sockets(self, tag: str | None = None) -> list[Binding]:
+        sockets = self.js_object.getWebSockets(*([] if tag is None else [tag]))
+        return [Binding(socket) for socket in sockets]
+
+    def abort(self, reason: str | None = None) -> None:
+        """Reset the Durable Object, and stop this call.
+
+        The JS abort ends execution at once, so it runs in a microtask, after
+        Python has unwound. DurableObjectAbort stops the caller's code first.
+        """
+        ctx = self.js_object
+        args = () if reason is None else (reason,)
+        js.queueMicrotask(create_once_callable(lambda: ctx.abort(*args)))
+
+        raise DurableObjectAbort(reason or "Durable Object abort requested")

workers/entrypoints.py

@@ -0,0 +1,183 @@
+import functools
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, TypeVar
+
+import _pyodide_entrypoint_helper
+from pyodide.code import relaxed_call
+
+from ._js import js_name
+from .bindings import Binding, _convert, _EnvWrapper
+from .context import DurableObjectAbort, DurableObjectContext, ExecutionContext
+from .request import Request
+from .workflows import wrap_run
+
+__all__ = [
+    "DurableObject",
+    "DurableObjectAbort",
+    "DurableObjectContext",
+    "WorkerEntrypoint",
+    "WorkflowEntrypoint",
+    "handler",
+]
+
+EnvT = TypeVar("EnvT")
+
+if TYPE_CHECKING:
+
+    class _Typed[Env]:
+        env: Env
+
+else:
+
+    class _Typed:
+        # Generic only to type checkers. A class that is generic at runtime
+        # can't follow Generic[S] in a base list (Python reports an
+        # inconsistent MRO), so subscripting here just returns the class and
+        # Generic mixes in before or after an entrypoint.
+        def __class_getitem__(cls, item: Any) -> type:
+            return cls
+
+
+class _Entrypoint:
+    # The class that wraps ctx, or None to leave it raw.
+    _context_class: Callable[[Any], Any] | None = None
+    # Handlers workerd calls with raw JS arguments, which get converted.
+    _raw_handlers: tuple[str, ...] = ()
+    # Handlers workerd calls as on_<name> on dates before 2025-08-14, from
+    # makeEntrypointProxyHandler in workerd's python-entrypoint-helper.ts.
+    _legacy_names: tuple[str, ...] = ()
+
+    ctx: Any
+    env: Any
+
+    def __init__(self, ctx: Any, env: Any) -> None:
+        self.ctx, self.env = _wrap_ctx_and_env(type(self), ctx, env)
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if "__init__" in cls.__dict__:
+            init = _init_with_wrapped_args(cls.__dict__["__init__"])
+            setattr(cls, "__init__", init)  # noqa: B010 (ty rejects the plain assignment)
+
+        # A handler the user names on_<name> for old dates converts too.
+        for name in (*cls._raw_handlers, *(f"on_{n}" for n in cls._raw_handlers)):
+            handler = getattr(cls, name, None)
+            if handler is not None and handler not in _CONVERTING | _ALIASES:
+                setattr(cls, name, _converting(handler))
+
+        # The alias looks the handler up on each call, so it follows subclass
+        # overrides and is set once. An on_<name> the user defines wins.
+        for name in cls._legacy_names:
+            if hasattr(cls, name) and not hasattr(cls, f"on_{name}"):
+                setattr(cls, f"on_{name}", _alias(name))
+
+
+def _wrap_ctx_and_env(cls: type[_Entrypoint], ctx: Any, env: Any) -> tuple[Any, Any]:
+    if not isinstance(ctx, Binding):
+        # Lets ctx.waitUntil take a coroutine, as in the stock SDK. A ctx this
+        # wrapped already went through here; workerd ignores a repeat patch.
+        _pyodide_entrypoint_helper.patchWaitUntil(ctx)
+        if cls._context_class is not None:
+            ctx = cls._context_class(ctx)
+
+    return ctx, _EnvWrapper(env)
+
+
+def _init_with_wrapped_args(init: Callable[..., None]) -> Callable[..., None]:
+    # The stock SDK wraps ctx and env before the user's __init__ sees them.
+    @functools.wraps(init)
+    def wrapped(self: Any, ctx: Any, env: Any, *args: Any, **kwargs: Any) -> None:
+        init(self, *_wrap_ctx_and_env(type(self), ctx, env), *args, **kwargs)
+
+    return wrapped
+
+
+# Handlers already converting their arguments, and on_<name> aliases, so a
+# subclass doesn't rewrap them.
+_CONVERTING: set[Callable[..., Any]] = set()
+_ALIASES: set[Callable[..., Any]] = set()
+
+
+def _handler_arg(value: Any) -> Any:
+    # A binary WebSocket message stays an ArrayBuffer, as in the stock SDK.
+    return value if js_name(value) == "ArrayBuffer" else _convert(value)
+
+
+def _converting(handler: Callable[..., Any]) -> Callable[..., Any]:
+    # wraps() keeps the handler's signature visible to workerd's relaxed_call.
+    @functools.wraps(handler)
+    def wrapped(self: Any, *args: Any, **kwargs: Any) -> Any:
+        return handler(
+            self,
+            *map(_handler_arg, args),
+            **{k: _handler_arg(v) for k, v in kwargs.items()},
+        )
+
+    _CONVERTING.add(wrapped)
+    return wrapped
+
+
+def _alias(name: str) -> Callable[..., Any]:
+    def alias(self: Any, *args: Any, **kwargs: Any) -> Any:
+        # workerd passes on_fetch (request, env, ctx). Relaxing drops what the
+        # handler's signature doesn't take, as workerd does for a plain fetch.
+        return relaxed_call(getattr(self, name), *args, **kwargs)
+
+    _ALIASES.add(alias)
+    return alias
+
+
+class WorkerEntrypoint(_Typed[EnvT], _Entrypoint):
+    _context_class = ExecutionContext
+    _raw_handlers = ("connect", "queue")
+    _legacy_names = ("fetch", "connect")
+
+    ctx: ExecutionContext
+
+
+class DurableObject(_Typed[EnvT], _Entrypoint):
+    _context_class = DurableObjectContext
+    _raw_handlers = (
+        "connect",
+        "alarm",
+        "webSocketMessage",
+        "webSocketClose",
+        "webSocketError",
+    )
+    _legacy_names = (
+        "fetch",
+        "connect",
+        "alarm",
+        "webSocketMessage",
+        "webSocketClose",
+        "webSocketError",
+    )
+
+    ctx: DurableObjectContext
+
+
+class WorkflowEntrypoint(_Typed[EnvT], _Entrypoint):
+    # The stock SDK leaves a Workflow's ctx raw.
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        # Only a run this class defines, so an inherited one isn't rewrapped.
+        if "run" in cls.__dict__:
+            setattr(cls, "run", wrap_run(cls.__dict__["run"]))  # noqa: B010
+
+
+def handler(func: Callable[..., Any]) -> Callable[..., Any]:
+    """For a module-level handler such as `on_fetch`, which workerd calls only
+    on dates before 2025-08-14: converts a JS Request argument to a Request
+    and wraps the env, as in the stock SDK."""
+
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        if args and js_name(args[0]) == "Request":
+            args = (Request(args[0]), *args[1:])
+        if len(args) > 1:
+            args = (args[0], _EnvWrapper(args[1]), *args[2:])
+
+        return func(*args, **kwargs)
+
+    return wrapper

workers/fetch.py

@@ -0,0 +1,51 @@
+from http import HTTPMethod
+from typing import TYPE_CHECKING, Any, Unpack
+
+import js
+from pyodide import __version__ as pyodide_version
+from pyodide.ffi import JsException, to_js
+from pyodide.http import pyfetch
+
+from ._js import js_body
+from .request import Request
+from .response import Response
+
+if TYPE_CHECKING:
+    from .types import FetchKwargs
+
+__all__ = ["fetch"]
+
+
+async def _pyfetch_0_26(request: Any, **kwargs: Any) -> Response:
+    # Pyodide 0.26.0a2's pyfetch lacks `fetcher`. Copied from Pyodide d3f99e1d.
+    custom_fetch = kwargs.pop("fetcher", None) or js.fetch
+
+    try:
+        return Response(
+            await custom_fetch(
+                request, to_js(kwargs, dict_converter=js.Object.fromEntries)
+            )
+        )
+    except JsException as error:
+        raise OSError(error.message) from None
+
+
+async def fetch(
+    resource: "str | Request | js.Request", **options: "Unpack[FetchKwargs]"
+) -> Response:
+    if isinstance(resource, Request):
+        resource = resource.js_object
+    kwargs: dict[str, Any] = dict(options)
+    if isinstance(kwargs.get("method"), HTTPMethod):
+        kwargs["method"] = kwargs["method"].value
+
+    # The body conversion Request() does: FormData and Blob as their JS
+    # objects, and bytes lent as a buffer while the request is sent.
+    body = kwargs.pop("body", None)
+    send = _pyfetch_0_26 if pyodide_version == "0.26.0a2" else pyfetch
+    with js_body(body) as converted:
+        if body is not None:
+            kwargs["body"] = converted
+        response = await send(resource, **kwargs)
+
+    return Response(response.js_response)

workers/formdata.py

@@ -0,0 +1,92 @@
+from collections.abc import Generator, MutableMapping
+from typing import Any
+
+import js
+
+from ._js import js_name
+from .blob import Blob, File
+
+__all__ = ["FormData", "FormDataValue"]
+
+type FormDataValue = str | js.Blob | Blob
+
+
+class FormData(MutableMapping[str, Any]):
+    """Key/value pairs for forms, following multidict and the JS FormData API."""
+
+    def __init__(self, form_data: "js.FormData | dict[str, Any] | None" = None) -> None:
+        if not form_data:
+            self._js_form_data = js.FormData.new()
+        elif isinstance(form_data, dict):
+            self._js_form_data = js.FormData.new()
+            for key, value in form_data.items():
+                self._js_form_data.append(key, _to_js(value))
+        elif js_name(form_data) == "FormData":
+            self._js_form_data = form_data
+        else:
+            raise TypeError(
+                "Expected form_data to be a dict or an instance of FormData"
+            )
+
+    def __getitem__(self, key: str) -> Any:
+        # The stock SDK returns JS null for a missing key.
+        if not self._js_form_data.has(key):
+            raise KeyError(key)
+        return _to_python(self._js_form_data.get(key))
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        if isinstance(value, list):
+            raise TypeError("Expected single item in arguments to FormData.__setitem__")
+        self._js_form_data.set(key, _to_js(value))
+
+    def __delitem__(self, key: str) -> None:
+        self.delete(key)
+
+    def __contains__(self, key: object) -> bool:
+        return self._js_form_data.has(key)
+
+    def __iter__(self) -> Generator[str]:
+        yield from self.keys()
+
+    def __len__(self) -> int:
+        # The stock SDK calls len() on a generator here and raises TypeError.
+        return sum(1 for _ in self.keys())
+
+    def append(self, key: str, value: Any, filename: str | None = None) -> None:
+        self._js_form_data.append(key, _to_js(value), filename)
+
+    def delete(self, key: str) -> None:
+        self._js_form_data.delete(key)
+
+    # keys, values and items return generators, as in the stock SDK, where
+    # Mapping promises views.
+    def keys(self) -> Generator[str]:  # ty: ignore[invalid-method-override]
+        yield from self._js_form_data.keys()
+
+    def values(self) -> Generator[Any]:  # ty: ignore[invalid-method-override]
+        for value in self._js_form_data.values():
+            yield _to_python(value)
+
+    def items(self) -> Generator[tuple[str, Any]]:  # ty: ignore[invalid-method-override]
+        for key, value in self._js_form_data.entries():
+            yield key, _to_python(value)
+
+    def get_all(self, key: str) -> list[Any]:
+        return [_to_python(value) for value in self._js_form_data.getAll(key)]
+
+    @property
+    def js_object(self) -> "js.FormData":
+        return self._js_form_data
+
+
+def _to_js(value: Any) -> Any:
+    return value.js_object if isinstance(value, Blob) else value
+
+
+# The Python wrapper for each JS value FormData can hold besides a string.
+_WRAPPERS: dict[str | None, type[Blob]] = {"File": File, "Blob": Blob}
+
+
+def _to_python(value: Any) -> Any:
+    wrapper = _WRAPPERS.get(js_name(value))
+    return value if wrapper is None else wrapper(value)

workers/request.py

@@ -0,0 +1,138 @@
+import json
+from http import HTTPMethod
+from typing import TYPE_CHECKING, Any, Unpack
+
+import js
+
+from ._body import BodyMixin
+from ._js import js_body, js_name, none_if_null, to_js_headers
+
+if TYPE_CHECKING:
+    from .types import FetchKwargs
+
+__all__ = ["Request"]
+
+
+class Request(BodyMixin):
+    def __init__(
+        self, input: "Request | str | js.Request", **options: "Unpack[FetchKwargs]"
+    ) -> None:
+        if js_name(input) == "Request":
+            if options:
+                raise ValueError(
+                    "Expected no options when constructing Request from a js.Request"
+                )
+            self._js_request: Any = input
+            return
+
+        js_options: dict[str, Any] = dict(options)
+        if isinstance(js_options.get("method"), HTTPMethod):
+            js_options["method"] = js_options["method"].value
+        if "headers" in js_options:
+            js_options["headers"] = to_js_headers(js_options["headers"])
+
+        body = js_options.pop("body", None)
+        with js_body(body) as converted:
+            if body is not None:
+                js_options["body"] = converted
+            self._js_request = js.Request.new(
+                input.js_object if isinstance(input, Request) else input,
+                **js_options,
+            )
+
+    def __repr__(self) -> str:
+        return (
+            f"Request(method={self._js_request.method!r}, url={self._js_request.url!r})"
+        )
+
+    @property
+    def js_object(self) -> "js.Request":
+        return self._js_request
+
+    @property
+    def body(self) -> "js.ReadableStream":
+        return self.js_object.body
+
+    @property
+    def body_used(self) -> bool:
+        return self.js_object.bodyUsed
+
+    @property
+    def cf(self) -> Any:
+        """Cloudflare's properties of an incoming request, or None if absent."""
+        return none_if_null(self.js_object.cf)
+
+    @property
+    def cache(self) -> str:
+        return self.js_object.cache
+
+    @property
+    def credentials(self) -> str:
+        return self.js_object.credentials
+
+    @property
+    def destination(self) -> str:
+        return self.js_object.destination
+
+    @property
+    def integrity(self) -> str:
+        return self.js_object.integrity
+
+    @property
+    def is_history_navigation(self) -> bool:
+        return self.js_object.isHistoryNavigation
+
+    @property
+    def keepalive(self) -> bool:
+        return self.js_object.keepalive
+
+    @property
+    def method(self) -> HTTPMethod | str:
+        # HTTPMethod for a standard method. The stock SDK raises KeyError on
+        # any other; this returns the method string instead.
+        method = self.js_object.method
+        return HTTPMethod[method] if method in HTTPMethod.__members__ else method
+
+    @property
+    def mode(self) -> str:
+        return self.js_object.mode
+
+    @property
+    def redirect(self) -> str:
+        return self.js_object.redirect
+
+    @property
+    def referrer(self) -> str:
+        return self.js_object.referrer
+
+    @property
+    def referrer_policy(self) -> str:
+        return self.js_object.referrerPolicy
+
+    @property
+    def url(self) -> str:
+        return self.js_object.url
+
+    def _raise_if_failed(self) -> None:
+        if self.body_used:
+            raise OSError("Body already used")
+
+    async def buffer(self) -> "js.ArrayBuffer":
+        self._raise_if_failed()
+        return await self.js_object.arrayBuffer()
+
+    async def bytes(self) -> bytes:
+        self._raise_if_failed()
+        return (await self.buffer()).to_bytes()
+
+    def clone(self) -> "Request":
+        self._raise_if_failed()
+        return Request(self.js_object.clone())
+
+    async def json(self, **kwargs: Any) -> Any:
+        self._raise_if_failed()
+        return json.loads(await self.text(), **kwargs)
+
+    async def text(self) -> str:
+        self._raise_if_failed()
+        return await self.js_object.text()