vercel-queue 0.7.0__py3-none-any.whl

vercel/queue/_internal/client_sync.py

@@ -0,0 +1,432 @@
+from __future__ import annotations
+
+from typing import Any, TypeVar, overload
+
+import concurrent.futures
+from collections.abc import Iterator, Mapping
+from types import TracebackType
+
+from vercel.headers import HeadersContext
+
+from .asynctools import iter_async_iterator, iter_coroutine
+from .client import BaseQueueClient, Delivery
+from .config import CURRENT_DEPLOYMENT, BaseUrl, DeploymentOption
+from .http import (
+    AsyncQueueRuntime,
+    HttpResponse,
+    PushDeliveryBody,
+    SyncHttpClientFactory,
+    SyncQueueRuntime,
+)
+from .lease import (
+    LeaseRenewal,
+    finalize_payload_sync,
+    processing_lease_seconds,
+    retry_message_after_sync,
+)
+from .log import debug_log_for_msg
+from .messages import sync_message_payload
+from .names import SanitizedName
+from .polling import run_poll_and_handle_sync, start_sync_polling_thread
+from .push import accept_input_sync, parse_push_delivery_metadata
+from .retry import retry_sync_follow_up
+from .streams import SyncStreamPayload, SyncTextStreamPayload
+from .subscribers import (
+    QueueSubscriber,
+    call_subscribers_sync,
+    infer_subscriber_transport,
+    reject_async_subscriber_for_sync,
+)
+from .types import (
+    Duration,
+    Handoff,
+    Message,
+    MessageID,
+    MessageMetadata,
+    RawHeaders,
+    RetryAfter,
+    StrContainer,
+    Topic,
+    Transport,
+)
+
+T = TypeVar("T")
+
+
+class QueueClient(BaseQueueClient):
+    """Synchronous Vercel Queues client.
+
+    Args:
+        token: Vercel OIDC token. Defaults to environment/OIDC resolution.
+        region: Queue region, such as ``"iad1"``.
+        base_url: Custom service base URL or region resolver for tests or proxies.
+        deployment: Deployment partition selection. Use ``ALL_DEPLOYMENTS``
+            to omit ``Vqs-Deployment-Id``.
+        headers: Default custom headers for send requests.
+        timeout: HTTP timeout in seconds.
+        http_client_factory: Optional factory for the underlying HTTP client.
+
+    """
+
+    def __init__(
+        self,
+        *,
+        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: SyncHttpClientFactory | None = None,
+    ) -> None:
+        super().__init__(
+            runtime=SyncQueueRuntime(
+                timeout=timeout,
+                client_factory=http_client_factory,
+            ),
+            token=token,
+            region=region,
+            base_url=base_url,
+            deployment=deployment,
+            headers=headers,
+            timeout=timeout,
+        )
+
+    def send(
+        self,
+        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 to a topic."""
+        return iter_coroutine(
+            self._send(
+                topic,
+                payload,
+                idempotency_key=idempotency_key,
+                retention=retention,
+                delay=delay,
+                deployment=deployment,
+                headers=headers,
+            )
+        )
+
+    def _accept_impl(
+        self,
+        raw_body: PushDeliveryBody | HttpResponse,
+        headers: RawHeaders | None = None,
+        *,
+        transport: Transport[T] | None = None,
+        lease_duration: Duration | None = None,
+    ) -> Message[T]:
+        raw_body, headers = accept_input_sync(raw_body, headers)
+        message = iter_coroutine(
+            self._accept(
+                raw_body,
+                headers,
+                transport=transport,
+                lease_duration=lease_duration,
+            )
+        )
+        return sync_message_payload(message)
+
+    @overload
+    def accept_and_handle(
+        self,
+        raw_body: PushDeliveryBody,
+        headers: RawHeaders,
+        *,
+        lease_duration: Duration | None = None,
+    ) -> None: ...
+
+    @overload
+    def accept_and_handle(
+        self,
+        raw_body: HttpResponse,
+        headers: None = None,
+        *,
+        lease_duration: Duration | None = None,
+    ) -> None: ...
+
+    def accept_and_handle(
+        self,
+        raw_body: PushDeliveryBody | HttpResponse,
+        headers: RawHeaders | None = None,
+        *,
+        lease_duration: Duration | None = None,
+    ) -> None:
+        """Accept a push callback and dispatch matching subscribers."""
+        self._accept_and_handle(
+            raw_body,
+            headers,
+            lease_duration=lease_duration,
+        )
+
+    def _accept_and_handle(
+        self,
+        raw_body: PushDeliveryBody | HttpResponse,
+        headers: RawHeaders | None = None,
+        *,
+        transport: Transport[T] | None = None,
+        lease_duration: Duration | None = None,
+    ) -> None:
+        raw_body, headers = accept_input_sync(raw_body, headers)
+        processing_lease_duration = processing_lease_seconds(lease_duration)
+        if transport is None:
+            metadata = parse_push_delivery_metadata(headers)
+            transport = infer_subscriber_transport(metadata)
+        # Delivery headers carry the auth context for follow-up queue calls,
+        # including lease renewals running outside this call stack.
+        with HeadersContext(headers).use():
+            message = sync_message_payload(
+                iter_coroutine(
+                    self._accept(
+                        raw_body,
+                        headers,
+                        transport=transport,
+                        lease_duration=processing_lease_duration,
+                    )
+                )
+            )
+            lifecycle = _MessageLifecycle(
+                message,
+                client=self,
+                lease_duration=processing_lease_duration,
+            )
+            with lifecycle:
+                call_subscribers_sync(message)
+
+    @overload
+    def poll(
+        self,
+        topic: Topic[SyncStreamPayload],
+        consumer_group: str | SanitizedName,
+        *,
+        limit: int = 1,
+        lease_duration: Duration | None = None,
+    ) -> Iterator[Delivery[SyncStreamPayload]]: ...
+
+    @overload
+    def poll(
+        self,
+        topic: Topic[SyncTextStreamPayload],
+        consumer_group: str | SanitizedName,
+        *,
+        limit: int = 1,
+        lease_duration: Duration | None = None,
+    ) -> Iterator[Delivery[SyncTextStreamPayload]]: ...
+
+    @overload
+    def poll(
+        self,
+        topic: Topic[T],
+        consumer_group: str | SanitizedName,
+        *,
+        limit: int = 1,
+        lease_duration: Duration | None = None,
+    ) -> Iterator[Delivery[T]]: ...
+
+    @overload
+    def poll(
+        self,
+        topic: str,
+        consumer_group: str | SanitizedName,
+        *,
+        limit: int = 1,
+        lease_duration: Duration | None = None,
+    ) -> Iterator[Delivery[Any]]: ...
+
+    @overload
+    def poll(
+        self,
+        topic: SanitizedName,
+        consumer_group: str | SanitizedName,
+        *,
+        limit: int = 1,
+        lease_duration: Duration | None = None,
+    ) -> Iterator[Delivery[Any]]: ...
+
+    def poll(
+        self,
+        topic: str | SanitizedName | Topic[Any],
+        consumer_group: str | SanitizedName,
+        *,
+        limit: int = 1,
+        lease_duration: Duration | None = None,
+    ) -> Iterator[Delivery[Any]]:
+        """Poll available deliveries for a consumer group."""
+        messages = self._receive(
+            topic,
+            consumer_group,
+            limit=limit,
+            lease_duration=lease_duration,
+        )
+        for message in iter_async_iterator(messages):
+            yield Delivery(
+                sync_message_payload(message),
+                client=self,
+                lease_duration=lease_duration,
+            )
+
+    def poll_and_handle(
+        self,
+        subscriber: QueueSubscriber[..., Any],
+        *,
+        topics: StrContainer | None = None,
+        interval: Duration = 1.0,
+        limit: int | None = None,
+        lease_duration: Duration | None = None,
+    ) -> concurrent.futures.Future[None]:
+        """Start a background thread that polls and dispatches one subscriber."""
+        reject_async_subscriber_for_sync(subscriber)
+        return start_sync_polling_thread(
+            lambda stop: run_poll_and_handle_sync(
+                poll=self.poll,
+                subscriber=subscriber,
+                topics=topics,
+                interval=interval,
+                limit=limit,
+                lease_duration=lease_duration,
+                stop=stop,
+            ),
+            name="vercel-queue-poll-and-handle",
+        )
+
+    def acknowledge(self, message: Message[T] | MessageMetadata) -> None:
+        """Acknowledge a received message.
+
+        This is a lower-level API for integrations that manage message
+        lifecycles manually. Application code should usually process messages
+        through ``poll`` delivery context managers or ``accept_and_handle`` so
+        acknowledgement happens automatically.
+        """
+        retry_sync_follow_up(
+            lambda: iter_coroutine(self._acknowledge(message)),
+            event_prefix="ack",
+        )
+
+    def extend_lease(
+        self,
+        message: Message[T] | MessageMetadata,
+        duration: Duration,
+    ) -> None:
+        """Extend message processing.
+
+        This is a lower-level API for integrations that manage message
+        lifecycles manually. Application code should usually rely on delivery
+        context managers or ``LeaseRenewal`` to keep leases alive while a
+        handler runs.
+        """
+        retry_sync_follow_up(
+            lambda: iter_coroutine(self._extend_lease(message, duration)),
+            event_prefix="visibility",
+        )
+
+    def retry_after(
+        self,
+        message: Message[T] | MessageMetadata,
+        delay: Duration,
+    ) -> None:
+        """Request redelivery of a received message after ``delay``.
+
+        This is a lower-level API for integrations that manage message
+        lifecycles manually. Application code should usually raise
+        ``RetryAfter`` from a handler instead of calling this directly.
+
+        Unlike ``extend_lease``, this is a settlement-style follow-up:
+        transient failures are retried, and a lease that no longer exists is
+        tolerated with a warning because the message will be redelivered
+        anyway.
+        """
+        retry_message_after_sync(message, delay, self._extend_lease_sync)
+
+    def _extend_lease_sync(
+        self,
+        message: Message[Any] | MessageMetadata,
+        duration: Duration,
+    ) -> None:
+        iter_coroutine(self._extend_lease(message, duration))
+
+    async def _renew_lease(self, message: Message[Any], duration: Duration) -> None:
+        runtime = AsyncQueueRuntime(timeout=self.timeout)
+        runtime.configure_base_url(self.base_url)
+        await self._extend_lease(message, duration, runtime=runtime)
+
+
+class _MessageLifecycle:
+    def __init__(
+        self,
+        message: Message[Any],
+        *,
+        client: QueueClient,
+        lease_duration: Duration | None = None,
+    ) -> None:
+        self._message = message
+        self._client = client
+        self._renewal = LeaseRenewal(
+            message,
+            client=client,
+            lease_duration=processing_lease_seconds(lease_duration),
+        )
+
+    def __enter__(self) -> LeaseRenewal:
+        self._renewal.__enter__()
+        return self._renewal
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> bool | None:
+        # ACK, Handoff, and RetryAfter deliberately use different renewal shutdown
+        # semantics. Server-side, background renewal and final directives are
+        # all conditional writes against the same active lease record. If a
+        # renewal races with ACK, the final state is safe either way: renewal
+        # first still leaves the same receipt handle valid for ACK, and ACK
+        # first makes the later renewal fail with a 4xx because the message is
+        # no longer INFLIGHT. Waiting for cancellation in the success path only
+        # adds tail latency without improving correctness.
+        #
+        # Handoff leaves the delivery open for another owner, so a best-effort
+        # stop failure can keep the hidden renewal alive past handoff.
+        #
+        # RetryAfter is different because it is itself a visibility update. A
+        # late automatic renewal can overwrite the shorter retry delay the
+        # handler requested, delaying redelivery until the normal processing
+        # lease. For that path we wait for the renewal worker to finish or
+        # cancel any in-flight extension before applying the RetryAfter
+        # visibility change. If stopping times out, we still apply the
+        # directive: the worst remaining case is the pre-existing race, while
+        # refusing to apply RetryAfter would always leave the long lease behind.
+        wait_for_renewal_stop = isinstance(exc, (Handoff, RetryAfter))
+        try:
+            self._renewal.stop(wait=wait_for_renewal_stop)
+        finally:
+            finalize_payload_sync(self._message.payload)
+
+        if isinstance(exc, Handoff):
+            debug_log_for_msg("message.handoff", self._message)
+            return True
+        if isinstance(exc, RetryAfter):
+            self._renewal.extend(exc.timeout_seconds)
+            debug_log_for_msg(
+                "message.retry_after",
+                self._message,
+                retry_after_seconds=exc.timeout_seconds,
+            )
+            return True
+        if exc is None:
+            # acknowledge() already retries transient failures internally.
+            self._client.acknowledge(self._message)
+            debug_log_for_msg("message.ack", self._message)
+        return None
+
+
+# Only add public symbols to __all__; internal helpers must stay unexported.
+__all__ = ("LeaseRenewal", "QueueClient")

vercel/queue/_internal/config.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from typing import Final, TypeAlias, final
+
+import os
+import re
+from collections.abc import Callable, Mapping
+
+from vercel.oidc import get_vercel_oidc_token
+from vercel.oidc.aio import get_vercel_oidc_token as get_vercel_oidc_token_async
+
+from .constants import (
+    HEADER_AUTHORIZATION,
+    HEADER_CONTENT_TYPE,
+    VQS_HEADER_DELAY_SECONDS,
+    VQS_HEADER_DEPLOYMENT_ID,
+    VQS_HEADER_IDEMPOTENCY_KEY,
+    VQS_HEADER_MAX_MESSAGES,
+    VQS_HEADER_RETENTION_SECONDS,
+    VQS_HEADER_VISIBILITY_TIMEOUT_SECONDS,
+)
+from .errors import DeploymentResolutionError, TokenResolutionError
+
+DeploymentID: TypeAlias = str
+BaseUrl: TypeAlias = str | Callable[[str], str]
+
+
+@final
+class CurrentDeployment:
+    pass
+
+
+@final
+class AllDeployments:
+    pass
+
+
+CURRENT_DEPLOYMENT: Final = CurrentDeployment()
+ALL_DEPLOYMENTS: Final = AllDeployments()
+DeploymentOption: TypeAlias = DeploymentID | CurrentDeployment | AllDeployments
+REGION_PATTERN = re.compile(r"^[a-z]{2,5}[0-9]{1,2}$")
+
+PROTECTED_HEADERS = {
+    HEADER_AUTHORIZATION.lower(),
+    HEADER_CONTENT_TYPE.lower(),
+    VQS_HEADER_DELAY_SECONDS.lower(),
+    VQS_HEADER_DEPLOYMENT_ID.lower(),
+    VQS_HEADER_IDEMPOTENCY_KEY.lower(),
+    VQS_HEADER_MAX_MESSAGES.lower(),
+    VQS_HEADER_RETENTION_SECONDS.lower(),
+    VQS_HEADER_VISIBILITY_TIMEOUT_SECONDS.lower(),
+}
+
+
+def resolve_region(region: str | None = None) -> str:
+    resolved = region or os.environ.get("VERCEL_REGION")
+    if resolved is None:
+        raise ValueError("Queue region is required. Provide 'region' or set VERCEL_REGION.")
+    if not REGION_PATTERN.fullmatch(resolved):
+        raise ValueError(f"Invalid queue region: {resolved!r}")
+    return resolved
+
+
+def validate_region(region: str | None) -> str | None:
+    if region is None:
+        return None
+    if not REGION_PATTERN.fullmatch(region):
+        raise ValueError(f"Invalid queue region: {region!r}")
+    return region
+
+
+def resolve_base_url(base_url: BaseUrl | None = None, *, region: str | None = None) -> str:
+    resolved_region = resolve_region(region)
+    if base_url is not None:
+        if isinstance(base_url, str):
+            resolved = base_url.format(region=resolved_region)
+        else:
+            resolved = base_url(resolved_region)
+        return resolved.rstrip("/")
+    env_base_url = os.environ.get("VERCEL_QUEUE_BASE_URL")
+    if env_base_url:
+        return env_base_url.format(region=resolved_region).rstrip("/")
+    return f"https://{resolved_region}.vercel-queue.com"
+
+
+def resolve_deployment(deployment: DeploymentOption = CURRENT_DEPLOYMENT) -> str | None:
+    if deployment is ALL_DEPLOYMENTS:
+        return None
+    if isinstance(deployment, str):
+        return deployment
+    env_deployment = os.environ.get("VERCEL_DEPLOYMENT_ID")
+    if env_deployment:
+        return env_deployment
+    raise DeploymentResolutionError(
+        "Failed to resolve queue deployment ID. Provide 'deployment', "
+        "set VERCEL_DEPLOYMENT_ID, or pass deployment=ALL_DEPLOYMENTS "
+        "to explicitly omit it."
+    )
+
+
+def resolve_token(token: str | None = None) -> str:
+    if token:
+        return token
+    env_token = os.environ.get("VERCEL_QUEUE_TOKEN")
+    if env_token:
+        return env_token
+    try:
+        resolved = get_vercel_oidc_token()
+    except Exception as exc:
+        raise TokenResolutionError(
+            "Failed to resolve queue token. Provide 'token', set VERCEL_QUEUE_TOKEN, "
+            "or make a Vercel OIDC token available."
+        ) from exc
+    if not resolved:
+        raise TokenResolutionError("Failed to resolve queue token: OIDC returned an empty token")
+    return resolved
+
+
+async def resolve_token_async(token: str | None = None) -> str:
+    if token:
+        return token
+    env_token = os.environ.get("VERCEL_QUEUE_TOKEN")
+    if env_token:
+        return env_token
+    try:
+        resolved = await get_vercel_oidc_token_async()
+    except Exception as exc:
+        raise TokenResolutionError(
+            "Failed to resolve queue token. Provide 'token', set VERCEL_QUEUE_TOKEN, "
+            "or make a Vercel OIDC token available."
+        ) from exc
+    if not resolved:
+        raise TokenResolutionError("Failed to resolve queue token: OIDC returned an empty token")
+    return resolved
+
+
+def apply_custom_headers(headers: dict[str, str], custom_headers: Mapping[str, str] | None) -> None:
+    for key, value in (custom_headers or {}).items():
+        if key.lower() in PROTECTED_HEADERS or key.lower().startswith("vqs-"):
+            continue
+        headers[str(key)] = str(value)
+
+
+# Only add public symbols to __all__; internal helpers must stay unexported.
+__all__ = (
+    "ALL_DEPLOYMENTS",
+    "CURRENT_DEPLOYMENT",
+    "AllDeployments",
+    "BaseUrl",
+    "CurrentDeployment",
+    "DeploymentID",
+    "DeploymentOption",
+    "apply_custom_headers",
+    "resolve_base_url",
+    "resolve_deployment",
+    "resolve_region",
+    "resolve_token",
+    "resolve_token_async",
+    "validate_region",
+)

vercel/queue/_internal/constants.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import platform
+import sys
+
+from ..version import __version__ as _ver
+
+CONTENT_TYPE_JSON = "application/json"
+CONTENT_TYPE_NDJSON = "application/x-ndjson"
+CONTENT_TYPE_OCTET_STREAM = "application/octet-stream"
+CONTENT_TYPE_TEXT = "text/plain; charset=utf-8"
+CONTENT_TYPE_MULTIPART_MIXED = "multipart/mixed"
+
+HEADER_ACCEPT = "Accept"
+HEADER_AUTHORIZATION = "Authorization"
+HEADER_CONTENT_TYPE = "Content-Type"
+HEADER_RETRY_AFTER = "Retry-After"
+HEADER_USER_AGENT = "User-Agent"
+
+VQS_NAME_PATTERN = r"^[A-Za-z0-9_-]+$"
+
+DEFAULT_RETRY_AFTER_SECONDS = 60
+
+VQS_HEADER_DELAY_SECONDS = "Vqs-Delay-Seconds"
+VQS_HEADER_CLIENT_TS = "Vqs-Client-Ts"
+VQS_HEADER_DELIVERY_COUNT = "Vqs-Delivery-Count"
+VQS_HEADER_DEPLOYMENT_ID = "Vqs-Deployment-Id"
+VQS_HEADER_EXPIRES_AT = "Vqs-Expires-At"
+VQS_HEADER_IDEMPOTENCY_KEY = "Vqs-Idempotency-Key"
+VQS_HEADER_MAX_MESSAGES = "Vqs-Max-Messages"
+VQS_HEADER_MESSAGE_ID = "Vqs-Message-Id"
+VQS_HEADER_RECEIPT_HANDLE = "Vqs-Receipt-Handle"
+VQS_HEADER_RETENTION_SECONDS = "Vqs-Retention-Seconds"
+VQS_HEADER_TIMESTAMP = "Vqs-Timestamp"
+VQS_HEADER_VISIBILITY_TIMEOUT_SECONDS = "Vqs-Visibility-Timeout-Seconds"
+
+CLOUD_EVENT_TYPE_V2BETA = "com.vercel.queue.v2beta"
+CLOUD_EVENT_HEADER_TYPE = "ce-type"
+CLOUD_EVENT_HEADER_VQS_CONSUMER_GROUP = "ce-vqsconsumergroup"
+CLOUD_EVENT_HEADER_VQS_CREATED_AT = "ce-vqscreatedat"
+CLOUD_EVENT_HEADER_VQS_DELIVERY_COUNT = "ce-vqsdeliverycount"
+CLOUD_EVENT_HEADER_VQS_EXPIRES_AT = "ce-vqsexpiresat"
+CLOUD_EVENT_HEADER_VQS_MESSAGE_ID = "ce-vqsmessageid"
+CLOUD_EVENT_HEADER_VQS_TOPIC = "ce-vqsqueuename"
+CLOUD_EVENT_HEADER_VQS_RECEIPT_HANDLE = "ce-vqsreceipthandle"
+CLOUD_EVENT_HEADER_VQS_REGION = "ce-vqsregion"
+CLOUD_EVENT_HEADER_VQS_VISIBILITY_DEADLINE = "ce-vqsvisibilitydeadline"
+
+PLATFORM = platform.uname()
+USER_AGENT = f"vercel/queue/{_ver} (Python/{sys.version}; {PLATFORM.system}/{PLATFORM.machine})"