encore-dev 2.0.0a7__py3-none-any.whl

encore/pubsub/__init__.py

@@ -0,0 +1,425 @@
+"""Pub/Sub topics and subscriptions.
+
+Typical usage example:
+
+    from encore import pubsub
+
+    orders = pubsub.Topic(
+        "orders",
+        exactly_once=True,
+    )
+
+    async def place_order(order):
+        await orders.publish({"id": order.id})
+
+    ordered = pubsub.OrderedTopic(
+        "ordered-orders",
+        exactly_once=True,
+    )
+
+    async def place_order_in_sequence(order):
+        await ordered.publish({"id": order.id}, ordering_key=str(order.id))
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from datetime import datetime
+import json
+import types
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Generic,
+    ForwardRef,
+    TYPE_CHECKING,
+    TypeVar,
+    Union,
+    get_args,
+    get_origin,
+)
+
+from ..internal.lazy import Lazy
+from ..internal.runtime import _native, runtime
+from ..tracing._context import active_ctx_bytes
+
+try:
+    from pydantic import BaseModel
+except ImportError:
+    BaseModel = None
+
+
+_UNION_ORIGINS = (Union, getattr(types, "UnionType", Union))
+_json_ref = ForwardRef("JSON", module=__name__)
+# Union syntax keeps these aliases compatible with Python 3.9.
+
+if TYPE_CHECKING:
+    JSON = Union[dict[str, "JSON"], list["JSON"], str, int, float, bool, None]
+
+    from pydantic import BaseModel as _PydanticBaseModel
+
+    Payload = Union[_PydanticBaseModel, JSON, bytes]
+else:
+    # Resolve the recursive alias in this module, even when a handler imports
+    # pubsub under an alias or imports Message without importing JSON directly.
+    JSON = Union[dict[str, _json_ref], list[_json_ref], str, int, float, bool, None]
+    Payload = (
+        Union[BaseModel, JSON, bytes] if BaseModel is not None else Union[JSON, bytes]
+    )
+
+_T = TypeVar("_T", bound=Payload)
+
+
+def _validate_payload_type(payload_type: Any) -> None:
+    """Check decoder support, without validating individual JSON values."""
+    if payload_type is bytes or (
+        BaseModel is not None
+        and isinstance(payload_type, type)
+        and issubclass(payload_type, BaseModel)
+    ):
+        return
+
+    pending = [payload_type]
+    seen: set[int] = set()
+    while pending:
+        current = pending.pop()
+        if id(current) in seen:
+            continue
+        seen.add(id(current))
+        if current in (Any, str, int, float, bool, type(None), None, list, dict):
+            continue
+        # Only our recursive JSON alias is supported, not arbitrary forward refs.
+        if current is _json_ref:
+            continue
+        origin, args = get_origin(current), get_args(current)
+        if origin in _UNION_ORIGINS or origin is list:
+            pending.extend(args)
+        elif origin is dict and (not args or args[0] in (str, Any)):
+            pending.extend(args[1:])
+        else:
+            raise TypeError(
+                f"Unsupported Pub/Sub payload type {payload_type!r}. Use JSON "
+                "types, bytes, or a top-level Pydantic v2 model. "
+                "Use Subscription[bytes] for custom decoding. "
+                "Pass types directly rather than as string forward references."
+            )
+
+
+def _decode_message_data(payload_type: Any, data: bytes) -> Payload:
+    """Decode using the subscription's validated type argument.
+
+    Bytes pass through unchanged. Pydantic v2 models validate their own JSON.
+    Other supported annotations use ordinary JSON decoding; nested annotations
+    do not coerce or validate JSON values. Use a model for field validation.
+    """
+    if payload_type is bytes:
+        return data
+
+    if (
+        BaseModel is not None
+        and isinstance(payload_type, type)
+        and issubclass(payload_type, BaseModel)
+    ):
+        try:
+            return payload_type.model_validate_json(data)
+        except ValueError as error:
+            raise ValueError(
+                f"Cannot decode Pub/Sub message as {payload_type.__name__}. "
+                f"Update the published payload or the model fields. {error}"
+            ) from error
+
+    try:
+        value = json.loads(data)
+    except json.JSONDecodeError as error:
+        raise ValueError(
+            f"Cannot decode Pub/Sub message as JSON at line {error.lineno}, "
+            f"column {error.colno}: {error.msg}. Publish valid JSON or use "
+            "Subscription[bytes] to handle the raw payload."
+        ) from error
+    except UnicodeDecodeError as error:
+        raise ValueError(
+            "Cannot decode Pub/Sub message: invalid text encoding. "
+            "Publish JSON encoded as UTF-8, UTF-16, or UTF-32, or use "
+            "Subscription[bytes] to handle the raw payload."
+        ) from error
+
+    return value
+
+
+@dataclass(frozen=True)
+class Message(Generic[_T]):
+    """A delivered message with its decoded payload and provider metadata.
+
+    Attributes:
+        data: The payload decoded according to the subscription's type argument.
+        raw_data: The original payload bytes.
+        attributes: Message attributes supplied alongside the payload.
+        id: The provider-assigned message identifier.
+        delivery_attempt: The delivery attempt number, starting at one.
+        publish_time: The publication time as a UTC datetime.
+        ordering_key: The ordering key, if supplied.
+    """
+
+    data: _T
+    raw_data: bytes
+    attributes: dict[str, str]
+    id: str
+    delivery_attempt: int
+    publish_time: datetime
+    ordering_key: str | None
+
+    @classmethod
+    def _from_native(cls, message: _native.PubSubMessage, data: _T) -> Message:
+        return cls(
+            data=data,
+            raw_data=message.data,
+            attributes=message.attributes,
+            id=message.id,
+            delivery_attempt=message.delivery_attempt,
+            publish_time=message.publish_time,
+            ordering_key=message.ordering_key,
+        )
+
+
+def _serialize_payload(value: Any) -> bytes:
+    if isinstance(value, bytes):
+        return value
+
+    if BaseModel is not None and isinstance(value, BaseModel):
+        return value.model_dump_json().encode("utf-8")
+
+    try:
+        return json.dumps(value).encode("utf-8")
+    except (TypeError, ValueError) as error:
+        raise TypeError(
+            "Cannot publish Pub/Sub message. Use JSON values, bytes, or a top-level "
+            "Pydantic v2 model. Dataclasses and models nested in plain JSON containers "
+            "are not supported."
+        ) from error
+
+
+class Topic(Generic[_T]):
+    """A pub/sub topic declared at module scope."""
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        exactly_once: bool = False,
+    ) -> None:
+        """Declare a pub/sub topic.
+
+        Args:
+            name: The topic's resource name.
+            exactly_once: Whether to request exactly-once delivery instead of
+                the default at-least-once delivery.
+        """
+        self._name = name
+        self._exactly_once = exactly_once
+        self._handle = Lazy(lambda: runtime().pubsub_topic(name))
+
+    @property
+    def _impl(self) -> _native.PubSubTopic:
+        return self._handle.get()
+
+    @classmethod
+    def named(cls, name: str) -> Topic[_T]:
+        """Reference an existing topic declared by another service.
+
+        The declaring service may use another language. Construct Topic
+        directly to declare a new topic.
+
+        Args:
+            name: The topic name as a string literal for static resolution.
+
+        Returns:
+            A reference to the configured topic.
+        """
+        return cls(name)
+
+    async def publish(
+        self, message: _T, attributes: dict[str, str] | None = None
+    ) -> str:
+        """Publish a message and return its provider-assigned identifier.
+
+        Args:
+            message: A JSON value, bytes, or a top-level Pydantic v2 model.
+            attributes: Optional string metadata to send alongside the payload.
+
+        Returns:
+            The published message identifier.
+
+        Raises:
+            TypeError: The payload cannot be serialized as a supported type.
+        """
+        return await self._impl.publish(
+            _serialize_payload(message), attributes, source=active_ctx_bytes()
+        )
+
+
+class OrderedTopic(Generic[_T]):
+    """A ordered pub/sub topic declared at module scope."""
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        exactly_once: bool = False,
+    ) -> None:
+        """Declare a ordered pub/sub topic.
+
+        Args:
+            name: The topic's resource name.
+            exactly_once: Whether to request exactly-once delivery instead of
+                the default at-least-once delivery.
+        """
+        self._name = name
+        self._exactly_once = exactly_once
+        self._handle = Lazy(lambda: runtime().pubsub_topic(name))
+
+    @property
+    def _impl(self) -> _native.PubSubTopic:
+        return self._handle.get()
+
+    @classmethod
+    def named(cls, name: str) -> OrderedTopic[_T]:
+        """Reference an existing topic declared by another service.
+
+        The declaring service may use another language. Construct OrderedTopic
+        directly to declare a new topic.
+
+        Args:
+            name: The topic name as a string literal for static resolution.
+
+        Returns:
+            A reference to the configured topic.
+        """
+        return cls(name)
+
+    async def publish(
+        self, message: _T, ordering_key: str, attributes: dict[str, str] | None = None
+    ) -> str:
+        """Publish a message and return its provider-assigned identifier.
+
+        Args:
+            message: A JSON value, bytes, or a top-level Pydantic v2 model.
+            ordering_key: The key grouping messages for ordered delivery.
+            attributes: Optional string metadata to send alongside the payload.
+
+        Returns:
+            The published message identifier.
+
+        Raises:
+            TypeError: The payload cannot be serialized as a supported type.
+        """
+        return await self._impl.publish(
+            _serialize_payload(message),
+            attributes,
+            source=active_ctx_bytes(),
+            ordering_key=ordering_key,
+        )
+
+
+_subscriptions: list[Subscription] = []
+
+
+class SubscriptionLoopError(RuntimeError):
+    """The subscription belongs to another asyncio loop."""
+
+
+class Subscription(Generic[_T]):
+    """A subscription and async handler declared at module scope.
+
+    Await encore.start() to begin consumption on the application's asyncio
+    loop. The explicit type argument selects payload decoding; omitting it
+    uses ordinary JSON decoding.
+    """
+
+    def __init__(
+        self,
+        topic: Topic[_T] | OrderedTopic[_T],
+        name: str,
+        *,
+        handler: Callable[[Message[_T]], Awaitable[None]],
+        ack_deadline: str | None = None,
+        message_retention: str | None = None,
+        min_backoff: str | None = None,
+        max_backoff: str | None = None,
+        max_retries: int | None = None,
+        max_concurrency: int | None = None,
+    ) -> None:
+        """Declare a subscription and register its handler for startup.
+
+        Timing and retry options configure provisioning through Encore's parser.
+        None leaves an option at its platform default.
+
+        Args:
+            topic: The topic to subscribe to.
+            name: The subscription name within the topic.
+            handler: An async callable receiving each decoded Message.
+            ack_deadline: The acknowledgement deadline as a duration string.
+            message_retention: The message retention period as a duration string.
+            min_backoff: The minimum retry delay as a duration string.
+            max_backoff: The maximum retry delay as a duration string.
+            max_retries: The maximum number of delivery retries.
+            max_concurrency: The maximum number of concurrent handler calls.
+
+        Raises:
+            TypeError: The handler is not callable.
+        """
+        if not callable(handler):
+            raise TypeError(
+                "Subscription handler must be callable. "
+                "Pass an async function, for example handler=handle_order, "
+                "rather than calling it with handler=handle_order()."
+            )
+        self._topic = topic
+        self._name = name
+        self._handler = handler
+        self._handle = Lazy(self._resolve)
+        self._consumer: asyncio.Future[None] | None = None
+        _subscriptions.append(self)
+
+    def _resolve(self) -> _native.PubSubSubscription:
+        # Generic instance metadata is available after construction, at startup.
+        args = get_args(getattr(self, "__orig_class__", None))
+        tp = args[0] if args else JSON
+        _validate_payload_type(tp)
+
+        async def dispatch(message: _native.PubSubMessage) -> None:
+            data = _decode_message_data(tp, message.data)
+            await self._handler(Message._from_native(message, data))
+
+        return runtime().pubsub_subscription(
+            _native.PubSubSubscriptionConfig(
+                topic_name=self._topic._name,
+                subscription_name=self._name,
+                handler=dispatch,
+            )
+        )
+
+    def _check_loop(self) -> None:
+        if self._consumer is not None:
+            if self._consumer.get_loop() is not asyncio.get_running_loop():
+                raise SubscriptionLoopError(
+                    "subscription already started on a different asyncio loop"
+                )
+
+    def _start(self) -> asyncio.Future[None]:
+        self._check_loop()
+        if self._consumer is None:
+            self._consumer = asyncio.ensure_future(self._handle.get().subscribe())
+            self._consumer.add_done_callback(self._consumer_done)
+        return self._consumer
+
+    def _consumer_done(self, consumer: asyncio.Future[None]) -> None:
+        if not consumer.cancelled() and (error := consumer.exception()) is not None:
+            consumer.get_loop().call_exception_handler(
+                {
+                    "message": f"Encore subscription {self._topic._name}/{self._name} failed",
+                    "exception": error,
+                    "future": consumer,
+                }
+            )

encore/secrets/__init__.py

@@ -0,0 +1,139 @@
+"""Typed application secrets declared at module scope.
+
+Secret[T] belongs to its declaring service. SharedSecret[T] declares a
+shared secret with tracked usage. GlobalSecret[T] is available to every
+service without usage tracking. Each exposes its current value through
+value and requires an explicit str or bytes type argument.
+
+Service-private secrets have a separate namespace from shared and global
+secrets. SharedSecret and GlobalSecret use the same namespace.
+
+Typical usage example:
+    from encore.secrets import Secret, SharedSecret
+
+    shared_api_key = SharedSecret[str]("api_key")
+    api_key = Secret[str]("api_key")
+"""
+
+from __future__ import annotations
+from typing import Callable, Generic, Optional, TypeVar, cast, get_args
+
+from ..internal.lazy import Lazy
+from ..internal.runtime import _native, runtime
+
+_T = TypeVar("_T", str, bytes)
+
+
+class _SecretValue(Generic[_T]):
+    def __init__(
+        self, name: str, load: Callable[[str], Optional[_native.Secret]]
+    ) -> None:
+        self._name = name
+        self._handle = Lazy(lambda: load(name))
+
+    def read(self, value_type: type[str] | type[bytes]) -> _T:
+        if value_type is not str and value_type is not bytes:
+            raise TypeError(
+                f"For {type(self).__name__}[T](name) T must be str or bytes"
+            )
+        secret = self._handle.get()
+        if secret is None:
+            raise KeyError(f"secret {self._name!r} is not configured")
+        raw = secret.get_bytes()
+
+        if value_type is bytes:
+            return cast(_T, raw)
+
+        return cast(_T, raw.decode("utf-8"))
+
+
+class _Secret(Generic[_T]):
+    """Common public behavior, backed by a scope-specific lookup."""
+
+    def __init__(
+        self, name: str, load: Callable[[str], Optional[_native.Secret]]
+    ) -> None:
+        self._name = name
+        self._value: _SecretValue[_T] = _SecretValue(name, load)
+
+    @property
+    def name(self) -> str:
+        """The original name, without an internal namespace prefix."""
+        return self._name
+
+    @property
+    def value(self) -> _T:
+        """The secret value decoded using the constructor type argument.
+
+        A variable annotation alone does not supply the runtime type.
+
+        Raises:
+            TypeError: The constructor type argument is missing or is neither
+                str nor bytes.
+            KeyError: The secret is not configured.
+            UnicodeDecodeError: A str secret contains invalid UTF-8.
+        """
+        args = get_args(getattr(self, "__orig_class__", None))
+        if not args:
+            raise TypeError(f"Use {type(self).__name__}[T](name) with an explicit type")
+        return self._value.read(args[0])
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self._name!r}: *********)"
+
+
+class Secret(_Secret[_T]):
+    """A secret belonging only to the service that declares it.
+
+    The type parameter must be specified explicitly.
+
+    Example:
+        secret = Secret[str]("ApiKey")
+    """
+
+    def __init__(self, name: str) -> None:
+        """Declare a service-private secret at module scope.
+
+        Args:
+            name: The configured secret name. Instantiate with an explicit str
+                or bytes type argument, such as Secret[str]("ApiKey").
+        """
+        super().__init__(name, lambda key: runtime().secret(key))
+
+
+class SharedSecret(_Secret[_T]):
+    """A shared secret with tracked usage; may be declared outside services.
+
+    The type parameter must be specified explicitly.
+
+    Example:
+        secret = SharedSecret[str]("ApiKey")
+    """
+
+    def __init__(self, name: str) -> None:
+        """Declare a shared secret at module scope.
+
+        Args:
+            name: The configured secret name. Instantiate with an explicit str
+                or bytes type argument, such as SharedSecret[str]("ApiKey").
+        """
+        super().__init__(name, lambda key: runtime().shared_secret(key))
+
+
+class GlobalSecret(_Secret[_T]):
+    """A global secret available to every service without usage tracking.
+
+    The type parameter must be specified explicitly.
+
+    Example:
+        secret = GlobalSecret[str]("ApiKey")
+    """
+
+    def __init__(self, name: str) -> None:
+        """Declare a global secret at module scope.
+
+        Args:
+            name: The configured secret name. Instantiate with an explicit str
+                or bytes type argument, such as GlobalSecret[str]("ApiKey").
+        """
+        super().__init__(name, lambda key: runtime().shared_secret(key))