vercel-queue 0.7.0__py3-none-any.whl

vercel/queue/__init__.py

@@ -0,0 +1,8 @@
+"""Vercel Queue client APIs."""
+# ruff: noqa: F403
+
+from ._internal import api_async as _api_async, api_common as _api_common
+from ._internal.api_async import *
+from ._internal.api_common import *
+
+__all__ = _api_async.__all__ + _api_common.__all__

vercel/queue/__main__.py

@@ -0,0 +1,10 @@
+"""Command-line entry point for ``python -m vercel.queue``."""
+
+from __future__ import annotations
+
+import sys
+
+from ._internal.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

vercel/queue/_internal/__init__.py

@@ -0,0 +1 @@
+"""Internal implementation for vercel.queue."""

vercel/queue/_internal/api_async.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+from typing import Any, TypeVar, overload
+
+from collections.abc import AsyncIterator, Mapping
+
+from .client import Delivery, LeaseRenewal, QueueClient
+from .config import (
+    CURRENT_DEPLOYMENT,
+    DeploymentOption,
+)
+from .http import (
+    AsyncHttpMessage,
+    AsyncPushDeliveryBody,
+)
+from .names import SanitizedName
+from .subscribers import QueueSubscriber
+from .types import (
+    Duration,
+    MessageID,
+    RawHeaders,
+    StrContainer,
+    Topic,
+)
+
+T = TypeVar("T")
+
+
+async def send(
+    topic: str | SanitizedName | Topic[T],
+    payload: T,
+    *,
+    idempotency_key: str | None = None,
+    retention: Duration | None = None,
+    delay: Duration | None = None,
+    deployment: DeploymentOption = CURRENT_DEPLOYMENT,
+    headers: Mapping[str, str] | None = None,
+) -> MessageID | None:
+    """Send a message with the default asynchronous client.
+
+    Args:
+        topic: Topic object or topic name.
+        payload: Payload accepted by the topic or inferred transport.
+        idempotency_key: Optional service-side deduplication key.
+        retention: Optional message retention duration.
+        delay: Optional delay before the message becomes visible.
+        deployment: Per-send deployment partition selection.
+        headers: Custom non-protected headers to include.
+
+    Returns:
+        Created message ID, or ``None`` if ingestion was deferred.
+
+    Raises:
+        QueueError: If the service rejects the request.
+
+    """
+    client = QueueClient()
+    return await client.send(
+        topic,
+        payload,
+        idempotency_key=idempotency_key,
+        retention=retention,
+        delay=delay,
+        deployment=deployment,
+        headers=headers,
+    )
+
+
+@overload
+async def accept_and_handle(
+    raw_body: AsyncPushDeliveryBody,
+    headers: RawHeaders,
+    *,
+    lease_duration: Duration | None = None,
+) -> None: ...
+
+
+@overload
+async def accept_and_handle(
+    raw_body: AsyncHttpMessage,
+    headers: None = None,
+    *,
+    lease_duration: Duration | None = None,
+) -> None: ...
+
+
+async def accept_and_handle(
+    raw_body: AsyncPushDeliveryBody | AsyncHttpMessage,
+    headers: RawHeaders | None = None,
+    *,
+    lease_duration: Duration | None = None,
+) -> None:
+    """Accept a push callback and dispatch async subscribers.
+
+    Args:
+        raw_body: Callback body bytes, byte iterable, or response object.
+        headers: Callback request headers, unless ``raw_body`` is a response.
+        lease_duration: Processing timeout used while handlers run.
+
+    Raises:
+        UnhandledMessageError: If no subscription matches the topic.
+        QueueError: If fetching, acknowledging, or retry scheduling fails.
+
+    """
+    client = QueueClient()
+    await client._accept_and_handle(  # noqa: SLF001
+        raw_body,
+        headers,
+        lease_duration=lease_duration,
+    )
+
+
+@overload
+def poll(
+    topic: Topic[T],
+    consumer_group: str | SanitizedName,
+    *,
+    limit: int = 1,
+    lease_duration: Duration | None = None,
+) -> AsyncIterator[Delivery[T]]: ...
+
+
+@overload
+def poll(
+    topic: str,
+    consumer_group: str | SanitizedName,
+    *,
+    limit: int = 1,
+    lease_duration: Duration | None = None,
+) -> AsyncIterator[Delivery[Any]]: ...
+
+
+@overload
+def poll(
+    topic: SanitizedName,
+    consumer_group: str | SanitizedName,
+    *,
+    limit: int = 1,
+    lease_duration: Duration | None = None,
+) -> AsyncIterator[Delivery[Any]]: ...
+
+
+def poll(
+    topic: str | SanitizedName | Topic[T],
+    consumer_group: str | SanitizedName,
+    *,
+    limit: int = 1,
+    lease_duration: Duration | None = None,
+) -> AsyncIterator[Delivery[T]]:
+    """Poll available deliveries with the default asynchronous client.
+
+    Args:
+        topic: Topic object or topic name to receive from.
+        consumer_group: Consumer group to receive as.
+        limit: Maximum messages to claim, from 1 through 10.
+        lease_duration: Optional processing timeout for received messages.
+
+    Returns:
+        Async iterator of deliveries. Enter each delivery to process its message.
+
+    Raises:
+        InvalidLimitError: If ``limit`` is outside the service range.
+        QueueError: If the service rejects the request.
+
+    """
+
+    async def _iterate() -> AsyncIterator[Delivery[T]]:
+        client = QueueClient()
+        async for delivery in client.poll(
+            topic,
+            consumer_group,
+            limit=limit,
+            lease_duration=lease_duration,
+        ):
+            yield delivery
+
+    return _iterate()
+
+
+async def poll_and_handle(
+    subscriber: QueueSubscriber[..., Any],
+    *,
+    topics: StrContainer | None = None,
+    interval: Duration = 1.0,
+    limit: int | None = None,
+    lease_duration: Duration | None = None,
+) -> None:
+    """Continuously poll messages with the default async client.
+
+    Args:
+        subscriber: Callback previously registered with ``@subscribe``.
+        topics: Concrete topic names to poll. Required for wildcard or prefix
+            subscription patterns; exact subscriptions infer their topic.
+        interval: Idle backoff when all configured topics are empty.
+        limit: Per-request maximum from 1 through 10. ``None`` drains until
+            empty before idling.
+        lease_duration: Optional processing timeout for received messages.
+
+    """
+    client = QueueClient()
+    await client.poll_and_handle(
+        subscriber,
+        topics=topics,
+        interval=interval,
+        limit=limit,
+        lease_duration=lease_duration,
+    )
+
+
+# Only add public symbols to __all__; internal helpers must stay unexported.
+__all__: tuple[str, ...] = (
+    "Delivery",
+    "LeaseRenewal",
+    "QueueClient",
+    "accept_and_handle",
+    "poll",
+    "poll_and_handle",
+    "send",
+)

vercel/queue/_internal/api_common.py

@@ -0,0 +1,104 @@
+"""Common public Vercel Queue API exports."""
+# ruff: noqa: F403, F405
+
+from .. import version as _version
+from . import (
+    asgi as _asgi,
+    config as _config,
+    names as _names,
+    transports as _transports,
+    types as _types,
+)
+from .errors import *
+from .subscribers import QueueSubscriber, Subscription, get_subscriptions, subscribe
+
+ALL_DEPLOYMENTS = _config.ALL_DEPLOYMENTS
+CURRENT_DEPLOYMENT = _config.CURRENT_DEPLOYMENT
+AllDeployments = _config.AllDeployments
+ByteBufferTransport = _transports.ByteBufferTransport
+ByteStreamTransport = _transports.ByteStreamTransport
+CurrentDeployment = _config.CurrentDeployment
+DeploymentID = _config.DeploymentID
+DeploymentOption = _config.DeploymentOption
+Duration = _types.Duration
+Handoff = _types.Handoff
+Message = _types.Message
+MessageID = _types.MessageID
+MessageMetadata = _types.MessageMetadata
+QueueClientAsgiApp = _asgi.QueueClientAsgiApp
+QueueDirective = _types.QueueDirective
+RawJsonTransport = _transports.RawJsonTransport
+ReceiptHandle = _types.ReceiptHandle
+RetryAfter = _types.RetryAfter
+SanitizedName = _names.SanitizedName
+StrContainer = _types.StrContainer
+TextBufferTransport = _transports.TextBufferTransport
+TextStreamTransport = _transports.TextStreamTransport
+Topic = _types.Topic
+TypedJsonTransport = _transports.TypedJsonTransport
+__version__ = _version.__version__
+asgi_app = _asgi.asgi_app
+sanitize_name = _names.sanitize_name
+
+# Only add public symbols to __all__; internal helpers must stay unexported.
+__all__ = (
+    "ALL_DEPLOYMENTS",
+    "CURRENT_DEPLOYMENT",
+    "AllDeployments",
+    "BadRequestError",
+    "ByteBufferTransport",
+    "ByteStreamTransport",
+    "CommunicationError",
+    "ConsumerDiscoveryError",
+    "ConsumerRegistryNotConfiguredError",
+    "CurrentDeployment",
+    "DeploymentID",
+    "DeploymentOption",
+    "DeploymentResolutionError",
+    "DuplicateIdempotencyKeyError",
+    "DuplicateSubscriptionError",
+    "Duration",
+    "ForbiddenError",
+    "Handoff",
+    "InternalServerError",
+    "InvalidLimitError",
+    "Message",
+    "MessageAlreadyProcessedError",
+    "MessageCorruptedError",
+    "MessageID",
+    "MessageLeaseExpiredError",
+    "MessageLockedError",
+    "MessageMetadata",
+    "MessageNotFoundError",
+    "MessageNotInFlightError",
+    "MessageUnavailableError",
+    "PayloadValidationError",
+    "ProtocolError",
+    "QueueClientAsgiApp",
+    "QueueDirective",
+    "QueueError",
+    "QueueSubscriber",
+    "RawJsonTransport",
+    "ReceiptHandle",
+    "ReceiptHandleMismatchError",
+    "RetryAfter",
+    "RetryableError",
+    "SanitizedName",
+    "ServiceError",
+    "StrContainer",
+    "Subscription",
+    "SubscriptionError",
+    "TextBufferTransport",
+    "TextStreamTransport",
+    "ThrottledError",
+    "TokenResolutionError",
+    "Topic",
+    "TypedJsonTransport",
+    "UnauthorizedError",
+    "UnhandledMessageError",
+    "__version__",
+    "asgi_app",
+    "get_subscriptions",
+    "sanitize_name",
+    "subscribe",
+)

vercel/queue/_internal/api_sync.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+from typing import Any, TypeVar, overload
+
+from collections.abc import Iterator, Mapping
+
+from .client import Delivery
+from .client_sync import LeaseRenewal, QueueClient
+from .config import CURRENT_DEPLOYMENT, DeploymentOption
+from .http import HttpResponse, PushDeliveryBody
+from .names import SanitizedName
+from .types import (
+    Duration,
+    MessageID,
+    RawHeaders,
+    Topic,
+)
+
+T = TypeVar("T")
+
+
+def send(
+    topic: str | SanitizedName | Topic[T],
+    payload: T,
+    *,
+    idempotency_key: str | None = None,
+    retention: Duration | None = None,
+    delay: Duration | None = None,
+    deployment: DeploymentOption = CURRENT_DEPLOYMENT,
+    headers: Mapping[str, str] | None = None,
+) -> MessageID | None:
+    """Send a message with the default synchronous client."""
+    client = QueueClient()
+    return client.send(
+        topic,
+        payload,
+        idempotency_key=idempotency_key,
+        retention=retention,
+        delay=delay,
+        deployment=deployment,
+        headers=headers,
+    )
+
+
+@overload
+def accept_and_handle(
+    raw_body: PushDeliveryBody,
+    headers: RawHeaders,
+    *,
+    lease_duration: Duration | None = None,
+) -> None: ...
+
+
+@overload
+def accept_and_handle(
+    raw_body: HttpResponse,
+    headers: None = None,
+    *,
+    lease_duration: Duration | None = None,
+) -> None: ...
+
+
+def accept_and_handle(
+    raw_body: PushDeliveryBody | HttpResponse,
+    headers: RawHeaders | None = None,
+    *,
+    lease_duration: Duration | None = None,
+) -> None:
+    """Accept a push callback and dispatch sync subscribers."""
+    client = QueueClient()
+    client._accept_and_handle(  # noqa: SLF001
+        raw_body,
+        headers,
+        lease_duration=lease_duration,
+    )
+
+
+@overload
+def poll(
+    topic: Topic[T],
+    consumer_group: str | SanitizedName,
+    *,
+    limit: int = 1,
+    lease_duration: Duration | None = None,
+) -> Iterator[Delivery[T]]: ...
+
+
+@overload
+def poll(
+    topic: str,
+    consumer_group: str | SanitizedName,
+    *,
+    limit: int = 1,
+    lease_duration: Duration | None = None,
+) -> Iterator[Delivery[Any]]: ...
+
+
+@overload
+def poll(
+    topic: SanitizedName,
+    consumer_group: str | SanitizedName,
+    *,
+    limit: int = 1,
+    lease_duration: Duration | None = None,
+) -> Iterator[Delivery[Any]]: ...
+
+
+def poll(
+    topic: str | SanitizedName | Topic[Any],
+    consumer_group: str | SanitizedName,
+    *,
+    limit: int = 1,
+    lease_duration: Duration | None = None,
+) -> Iterator[Delivery[Any]]:
+    """Poll available deliveries with the default synchronous client."""
+
+    def _iterate() -> Iterator[Delivery[Any]]:
+        client = QueueClient()
+        yield from client.poll(
+            topic,
+            consumer_group,
+            limit=limit,
+            lease_duration=lease_duration,
+        )
+
+    return _iterate()
+
+
+# Only add public symbols to __all__; internal helpers must stay unexported.
+__all__ = (
+    "Delivery",
+    "LeaseRenewal",
+    "QueueClient",
+    "accept_and_handle",
+    "poll",
+    "send",
+)

vercel/queue/_internal/asgi.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from typing import Any, TypeAlias, TypedDict
+
+import logging
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
+
+from vercel.headers import HeadersContext, headers_from_asgi_scope
+
+from .client import QueueClient
+from .config import CURRENT_DEPLOYMENT, BaseUrl, DeploymentOption
+from .errors import ProtocolError
+from .http import AsyncHttpClientFactory
+from .log import configure_asgi_logger, debug_log
+from .types import Duration
+
+logger = logging.getLogger("vercel.queue")
+
+
+class AsgiScope(TypedDict, total=False):
+    type: str
+    method: str
+    headers: list[tuple[bytes, bytes]]
+
+
+AsgiMessage: TypeAlias = dict[str, Any]
+AsgiReceive: TypeAlias = Callable[[], Awaitable[AsgiMessage]]
+AsgiSend: TypeAlias = Callable[[AsgiMessage], Awaitable[None]]
+
+
+class QueueClientAsgiApp:
+    """ASGI push-callback app backed by an async queue client."""
+
+    def __init__(self, client: QueueClient) -> None:
+        configure_asgi_logger()
+        self.client = client
+
+    async def __call__(
+        self,
+        scope: AsgiScope,
+        receive: AsgiReceive,
+        send: AsgiSend,
+    ) -> None:
+        scope_type = scope.get("type")
+        if scope_type == "http":
+            await self._handle_http(scope, receive, send)
+            return
+        if scope_type == "lifespan":
+            await self._handle_lifespan(receive, send)
+            return
+        raise RuntimeError(f"Unsupported ASGI scope type: {scope_type!r}")
+
+    async def _handle_http(
+        self,
+        scope: AsgiScope,
+        receive: AsgiReceive,
+        send: AsgiSend,
+    ) -> None:
+        if scope.get("method") != "POST":
+            await _send_status(send, 405)
+            return
+
+        headers = headers_from_asgi_scope(scope)
+        try:
+            with HeadersContext(headers).use():
+                await self.client.accept_and_handle(
+                    _body_chunks(receive),
+                    headers,
+                )
+        except (ProtocolError, TypeError, ValueError) as exc:
+            debug_log("asgi.bad_request", error=repr(exc))
+            logger.warning("Vercel Queue push callback rejected: %s", exc)
+            await _send_status(send, 400)
+        except Exception as exc:
+            debug_log("asgi.delivery_failure", error=repr(exc))
+            logger.exception("Vercel Queue push callback failed")
+            await _send_status(send, 500)
+        else:
+            await _send_status(send, 204)
+
+    async def _handle_lifespan(self, receive: AsgiReceive, send: AsgiSend) -> None:
+        while True:
+            message = await receive()
+            message_type = message.get("type")
+            if message_type == "lifespan.startup":
+                await send({"type": "lifespan.startup.complete"})
+            elif message_type == "lifespan.shutdown":
+                await send({"type": "lifespan.shutdown.complete"})
+                return
+
+
+def asgi_app(
+    *,
+    client: QueueClient | None = None,
+    token: str | None = None,
+    region: str | None = None,
+    base_url: BaseUrl | None = None,
+    deployment: DeploymentOption = CURRENT_DEPLOYMENT,
+    headers: Mapping[str, str] | None = None,
+    timeout: Duration | None = 10.0,
+    http_client_factory: AsyncHttpClientFactory | None = None,
+) -> QueueClientAsgiApp:
+    """Create an ASGI queue push-callback app."""
+    configure_asgi_logger()
+    resolved_client = client or QueueClient(
+        token=token,
+        region=region,
+        base_url=base_url,
+        deployment=deployment,
+        headers=headers,
+        timeout=timeout,
+        http_client_factory=http_client_factory,
+    )
+    return QueueClientAsgiApp(resolved_client)
+
+
+async def _body_chunks(receive: AsgiReceive) -> AsyncIterator[bytes]:
+    while True:
+        message = await receive()
+        message_type = message.get("type")
+        if message_type == "http.disconnect":
+            raise ValueError("request body disconnected before completion")
+        if message_type != "http.request":
+            raise ValueError(f"unexpected ASGI message: {message_type!r}")
+        body = message.get("body", b"")
+        if body:
+            yield body
+        if not message.get("more_body", False):
+            return
+
+
+async def _send_status(send: AsgiSend, status: int) -> None:
+    headers: list[tuple[bytes, bytes]] = []
+    if status == 405:
+        headers.append((b"allow", b"POST"))
+    await send({
+        "type": "http.response.start",
+        "status": status,
+        "headers": headers,
+    })
+    await send({"type": "http.response.body", "body": b""})
+
+
+# Only add public symbols to __all__; internal helpers must stay unexported.
+__all__ = ("QueueClientAsgiApp", "asgi_app")

vercel/queue/_internal/asynctools.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any, TypeGuard, TypeVar
+
+from collections.abc import AsyncIterator, Awaitable, Coroutine, Iterable, Iterator
+
+T = TypeVar("T")
+
+
+def _is_coroutine(value: Awaitable[T]) -> TypeGuard[Coroutine[Any, Any, T]]:
+    return isinstance(value, Coroutine)
+
+
+def iter_coroutine(coro: Coroutine[Any, Any, T]) -> T:
+    """Execute a non-suspending coroutine synchronously."""
+    try:
+        coro.send(None)
+    except StopIteration as exc:
+        return exc.value
+    else:
+        raise RuntimeError(f"coroutine {coro!r} did not stop after one iteration!")
+    finally:
+        coro.close()
+
+
+def iter_async_iterator(iterator: AsyncIterator[T]) -> Iterator[T]:
+    """Iterate over a non-suspending async iterator synchronously."""
+    while True:
+        try:
+            next_item = anext(iterator)
+            if not _is_coroutine(next_item):
+                raise TypeError("async iterator __anext__() must return a coroutine")
+            yield iter_coroutine(next_item)
+        except StopAsyncIteration:
+            return
+
+
+async def iter_bytes_async(payload: Iterable[bytes]) -> AsyncIterator[bytes]:
+    for chunk in payload:
+        yield chunk