xtr-remote-event 4.0.2__py3-none-any.whl

xtr_remote_event/.agents/skills/xtr-remote-event/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: xtr-remote-event
+description: How to hand an event that came from another system to the code that handles it with xtr-remote-event — one RemoteEvent value type, a one-method consumer declared with as_remote_event_consumer, a ConsumerLocator that finds it by source name, and ConsumeRemoteEventMessage so the work happens on a worker. Use when a delivery report, a payment notice, a provider callback or any inbound event needs routing to the code that handles that sender; when writing or declaring a consumer; when translating a sender's payload with a PayloadConverterInterface; when adding RemoteEventBundle to an application; or when a webhook read by xtr-webhook has to reach a consumer.
+---
+
+# xtr-remote-event
+
+An event from elsewhere arrives in whatever shape its sender chose. Once it is read, what the
+application does with it is always the same: hand it to the code that handles events from that
+sender. This package is that last step and nothing else.
+
+## Quick reference
+
+- `RemoteEvent(name, id, payload)` — frozen, three fields, no behaviour. `name` is the source
+  and decides who is handed it; `payload` is a `dict[str, object]` as it arrived.
+- `@as_remote_event_consumer("<source>")` on a class with `async def consume(self, event)`.
+  Stack it for several sources.
+- `ConsumerLocator({"<source>": consumer})` → `await locator.get("<source>")`. Also takes a
+  `ServiceProviderInterface`, which is what the bundle gives it.
+- `ConsumeRemoteEventMessage(type, event)` + `ConsumeRemoteEventHandler(locator)` move the work
+  onto a worker through [xtr-messenger](https://github.com/xterr/python-xtr).
+- `PayloadConverterInterface.convert(payload)` → `RemoteEvent`. Synchronous, takes the payload
+  already decoded.
+- In an application: activate `RemoteEventBundle`, declare consumers where they live, route
+  `ConsumeRemoteEventMessage`. There is no configuration module.
+- Everything derives from `RemoteEventError`.
+
+## Declare a consumer
+
+```python
+from xtr_remote_event import RemoteEvent, as_remote_event_consumer
+
+
+@as_remote_event_consumer("acme")
+class AcmeConsumer:
+    async def consume(self, event: RemoteEvent) -> None:
+        await do_something_with(event.payload)
+```
+
+- The declaration is written onto the class, so whatever gathers consumers finds it where it
+  finds the class — a container's scan sees it, and a test that declares one leaves nothing
+  behind for the next.
+- Stack the decorator for a consumer answering for several sources. The names are recorded from
+  the one nearest the class outwards, so reading them back reads as it was written.
+- One method, returning nothing: a consumer is the end of the line, not a step in a chain.
+- Async, because consuming is where the work is — a row written, a mail sent, a call back.
+- An empty name, or a class with no `consume()`, raises `InvalidArgumentError` where the
+  declaration is written, not when the first event arrives.
+- Read it back with `remote_event_consumers_declared_on(cls)` from `xtr_remote_event.decorator`.
+  Only what was written on that class: a subclass answers for nothing until it is decorated too.
+
+## Find the consumer of a source
+
+```python
+from xtr_remote_event import ConsumerLocator
+
+consumers = ConsumerLocator({"acme": AcmeConsumer(), "stripe": PaymentConsumer()})
+
+consumer = await consumers.get("acme")
+await consumer.consume(event)
+```
+
+`consumers.has(name)` asks first; `provided_services()` reports what it covers. A source nothing
+is registered under raises `LogicError` with
+`Unable to find a consumer for message of type "<name>".`
+
+Pass a `ServiceProviderInterface` instead of a mapping — the bundle passes a container-backed
+one — and each consumer is built, with its dependencies, when an event for it first arrives.
+
+## Consume on a worker
+
+```python
+from xtr_messenger import HandlersLocator, MessageBusConfig, MessageBusFactory, TransportConfig
+from xtr_remote_event import ConsumerLocator
+from xtr_remote_event.messenger import ConsumeRemoteEventHandler, ConsumeRemoteEventMessage
+
+handlers = HandlersLocator()
+_ = handlers.register(
+    ConsumeRemoteEventMessage,
+    ConsumeRemoteEventHandler(ConsumerLocator({"acme": AcmeConsumer()})),
+)
+
+bus = MessageBusFactory(
+    MessageBusConfig(
+        transports={"sync": TransportConfig("sync://")},
+        routing={ConsumeRemoteEventMessage: "sync"},
+    ),
+    handlers=handlers,
+).bus()
+
+_ = await bus.dispatch(ConsumeRemoteEventMessage("acme", event))
+```
+
+- The message is declared `"xtr_remote_event.consume.v1"`, so it keeps its name across a deploy.
+- `type` is separate from `event.name`, so a payload converter can decide which consumer an
+  event belongs to without rewriting the event it read.
+- It carries the event rather than an id, because nothing has stored it. A consumer that wants
+  it kept is the one that stores it.
+- `"sync://"` handles in the dispatching process; a broker transport hands it to a worker.
+- In a wired application the bundle registers the handler, so you never register it yourself.
+
+## Translate a sender's payload
+
+```python
+from collections.abc import Mapping
+
+from xtr_remote_event import PayloadConverterInterface, RemoteEvent
+from xtr_remote_event.exception import ParseError
+
+
+class AcmeConverter(PayloadConverterInterface):
+    def convert(self, payload: Mapping[str, object]) -> RemoteEvent:
+        kind = payload.get("kind")
+        if not isinstance(kind, str):
+            raise ParseError('The payload has no "kind" naming the event.')
+        return RemoteEvent(kind, str(payload["id"]), dict(payload))
+```
+
+This is where a sender's vocabulary is translated and nowhere else: adding a sender is writing
+one converter rather than touching whatever dispatches events. It takes the payload already
+decoded — reading the bytes, and deciding whether they are to be trusted at all, belongs to
+whatever received them — and it is synchronous, because translating a mapping reaches for
+nothing.
+
+## Testing
+
+A consumer is a class with one method, so test it directly:
+
+```python
+import pytest
+from xtr_remote_event import ConsumerLocator, RemoteEvent
+
+
+@pytest.mark.anyio
+async def test_a_paid_order_is_marked_paid() -> None:
+    consumer = AcmeConsumer(orders)
+
+    await consumer.consume(RemoteEvent("order.paid", "evt_1", {"order_id": "7"}))
+
+    assert await orders.is_paid("7")
+```
+
+- `RemoteEvent` is a frozen dataclass, so two with the same three fields compare equal — assert
+  on the whole event rather than field by field.
+- For the handler, build a `ConsumerLocator` over a recording consumer and assert what it was
+  handed. No bus is needed: the handler is callable.
+- A missing consumer is testable without a container:
+  `pytest.raises(LogicError)` on `locator.get("absent")`.
+- Declaring a consumer in a test leaves nothing behind, because the declaration lives on the
+  class.
+
+## Use in an application
+
+`uv run xtr-recipes recipes:sync` applies the recipe shipped with this package: it lists
+`RemoteEventBundle`. That is all a recipe can do here; it prints the two steps below it cannot.
+
+1. **Install** — `uv add "xtr-remote-event[di]"`. There are no other extras.
+2. **Activate** — `RemoteEventBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`
+   (`from xtr_remote_event.bundle import RemoteEventBundle`). Nothing to do when xtr-webhook's
+   bundle is listed, which requires this one.
+3. **Brings along** — the messenger bundle, always: the handler is registered on its bus.
+4. **Configure** — nothing. `RemoteEventConfig` takes no value, because which consumer answers
+   for which source is declared beside the class that consumes.
+5. **Environment** — nothing. **Ignore** — nothing.
+6. **Use** — declare consumers where they live; each is a service, so it asks for what it needs:
+
+   ```python
+   # app/consumer/payment_consumer.py
+   from xtr_remote_event import RemoteEvent
+   from xtr_remote_event.decorator import as_remote_event_consumer
+
+
+   @as_remote_event_consumer("acme")
+   class PaymentConsumer:
+       def __init__(self, orders: OrderRepository) -> None:
+           self._orders = orders
+
+       async def consume(self, event: RemoteEvent) -> None:
+           await self._orders.mark_paid(event.payload["order_id"])
+   ```
+
+   A class declared for two sources is registered once, so what it remembers between events does
+   not depend on which name the event arrived under.
+7. **Consume elsewhere** — route `ConsumeRemoteEventMessage` to a transport in
+   `<app>/config/messenger.py` to handle it on a worker; left unrouted it is handled in the
+   process that dispatched it.
+8. **Check** — `debug:bundles` shows `remote_event` as `listed` and `active`.
+9. **Remove** — drop the `BUNDLES` entry, then `uv remove xtr-remote-event` — unless xtr-webhook
+   is installed, which depends on it.
+
+## Errors
+
+Everything derives from `RemoteEventError`.
+
+| Error | Raised when | Also a |
+| --- | --- | --- |
+| `InvalidArgumentError` | a value cannot be used — an empty consumer name, a class with no `consume()` | `ValueError` |
+| `ParseError` | a converter cannot read a payload as an event | `InvalidArgumentError` |
+| `LogicError` | nothing is registered for a source, or what is registered is not a consumer | `RuntimeError` |
+
+A `ParseError` is the sender's doing, so the answer is to tell the sender. A `LogicError` is
+wiring the application got wrong, and is said where the event would otherwise be lost.
+
+## Do not
+
+- Do not mutate a `RemoteEvent` or its `payload` in a consumer: the event is a record of
+  something that already happened, and the next consumer is given the same one. Copy it first.
+- Do not inject the container into a consumer or into the handler. The handler takes a
+  `ConsumerLocator`, which answers the only question it has.
+- Do not keep a table of source names in the application: declare each consumer beside the class
+  that consumes, which is the one place that cannot drift.
+- Do not rely on a decorated base class to declare its subclasses — it does not, deliberately,
+  or every derived class would answer for its parent's sources.
+- Do not put a provider's own vocabulary in a consumer. Translate in a
+  `PayloadConverterInterface` and keep the consumer about what the application does.
+- Do not expect `event.name` and a message's `type` to be the same string; they are separate on
+  purpose.

xtr_remote_event/__init__.py

@@ -0,0 +1,22 @@
+"""Events received from another system, handed to the consumer registered under their name.
+
+An event from elsewhere — a delivery report, a payment notice, a message from a provider — is
+one value type here: the name of where it came from, an id, and the payload as it arrived. A
+consumer is registered under that name, and the event reaches it directly or through a message
+bus.
+"""
+
+from __future__ import annotations
+
+from .consumer import ConsumerInterface, ConsumerLocator
+from .decorator import as_remote_event_consumer
+from .payload_converter_interface import PayloadConverterInterface
+from .remote_event import RemoteEvent
+
+__all__ = [
+    "ConsumerInterface",
+    "ConsumerLocator",
+    "PayloadConverterInterface",
+    "RemoteEvent",
+    "as_remote_event_consumer",
+]

xtr_remote_event/bundle/__init__.py

@@ -0,0 +1,8 @@
+"""The xtr-dependency-injection bundle for xtr-remote-event."""
+
+from __future__ import annotations
+
+from .remote_event_bundle import RemoteEventBundle
+from .remote_event_config import RemoteEventConfig
+
+__all__ = ["RemoteEventBundle", "RemoteEventConfig"]

xtr_remote_event/bundle/_declared_consumers.py

@@ -0,0 +1,56 @@
+"""What a kernel's scan found declared: the class answering for each source name."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from xtr_remote_event.exception import LogicError
+
+if TYPE_CHECKING:
+    from collections.abc import ItemsView
+
+__all__ = ["DeclaredConsumers"]
+
+
+@final
+class DeclaredConsumers:
+    """The consumer classes one kernel found, by the name each answers for.
+
+    One kernel's own, never a registry shared by the process: two kernels in
+    one test run declare into one of these each, so a consumer scanned by both
+    is a service of both and a clash in one is not a clash in the other.
+    """
+
+    __slots__ = ("_by_name", "_classes")
+
+    def __init__(self) -> None:
+        """Start with nothing declared."""
+        self._by_name: dict[str, type[object]] = {}
+        self._classes: set[type[object]] = set()
+
+    def add(self, name: str, consumer: type[object]) -> bool:
+        """Record ``consumer`` as the consumer of the source ``name``.
+
+        Returns whether ``consumer`` is new here, so the caller registers it as
+        a service once however many names it answers for — one instance serving
+        every source it declared, rather than one per name.
+
+        Raises:
+            LogicError: If another class already answers for ``name``. Which
+                of the two should have it is a choice only the application can
+                make, and either answer silently loses the events of the other.
+        """
+        claimed = self._by_name.get(name)
+        if claimed is not None and claimed is not consumer:
+            raise LogicError(
+                f'The remote event consumer name "{name}" is declared by both '
+                f"{claimed.__qualname__} and {consumer.__qualname__}."
+            )
+        self._by_name[name] = consumer
+        is_new = consumer not in self._classes
+        self._classes.add(consumer)
+        return is_new
+
+    def items(self) -> ItemsView[str, type[object]]:
+        """Return each source name with the class that answers for it."""
+        return self._by_name.items()

xtr_remote_event/bundle/remote_event_bundle.py

@@ -0,0 +1,109 @@
+"""The xtr-remote-event bundle: declared consumers, reachable by the name of their source.
+
+An application listing :class:`RemoteEventBundle` — which brings
+``MessengerBundle`` with it — gets every class declared with
+``@as_remote_event_consumer`` built by the container with its dependencies,
+and a ``ConsumeRemoteEventMessage`` dispatched on the bus handed to whichever
+of them answers for its source. The handler is registered with it, so a wired
+application never meets ``NoHandlerForMessageError`` for that message.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final, final
+
+from typing_extensions import override
+from xtr_dependency_injection import (
+    Bundle,
+    ContainerBuilder,
+    ServiceConfigurator,
+    ServiceLocator,
+    as_bundle,
+    named_factory,
+    required_bundle,
+)
+from xtr_messenger.bundle import MessengerBundle
+
+from xtr_remote_event.consumer.consumer_interface import ConsumerInterface
+from xtr_remote_event.consumer.consumer_locator import ConsumerLocator
+from xtr_remote_event.decorator import remote_event_consumers_declared_on
+from xtr_remote_event.exception import LogicError
+
+from ._declared_consumers import DeclaredConsumers
+from .remote_event_config import RemoteEventConfig
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Coroutine
+
+__all__ = ["RemoteEventBundle"]
+
+_CONSUMER_LOCATOR: Final = "remote_event_consumers"
+
+_NO_CONTAINER: Final = "the remote event bundle has no container; it is used before it booted"
+
+_HANDLER_MODULE: Final = "xtr_remote_event.messenger.consume_remote_event_handler"
+
+
+@final
+@required_bundle(MessengerBundle)
+@as_bundle("remote_event", config=RemoteEventConfig)
+class RemoteEventBundle(Bundle[RemoteEventConfig]):
+    """Wires declared consumers to the container, and the handler to the message bus."""
+
+    def __init__(self) -> None:
+        """Start with nothing declared."""
+        self._declared = DeclaredConsumers()
+
+    @override
+    def build(self, builder: ContainerBuilder) -> None:
+        """Collect every declared consumer, and register each class as one service.
+
+        Unqualified and once, however many sources a class declared: a
+        consumer answering for two of them is one instance answering for both,
+        so what it remembers between events does not depend on which name the
+        event arrived under.
+        """
+        declared = self._declared
+
+        def register(obj: object, name: str, services: ServiceConfigurator) -> None:
+            if isinstance(obj, type) and declared.add(name, obj):
+                _ = services.set(obj)
+
+        builder.register_attribute_for_autoconfiguration(
+            remote_event_consumers_declared_on, register
+        )
+
+    @override
+    def load_extension(
+        self,
+        config: RemoteEventConfig,
+        services: ServiceConfigurator,
+        builder: ContainerBuilder,
+    ) -> None:
+        """Register the consumer locator, and the handler that looks consumers up in it."""
+        del config, builder
+        _ = services.set(named_factory(_consumer_locator(self, self._declared), _CONSUMER_LOCATOR))
+        services.load(_HANDLER_MODULE)
+
+
+def _consumer_locator(
+    bundle: RemoteEventBundle, declared: DeclaredConsumers
+) -> Callable[[], Coroutine[None, None, ConsumerLocator]]:
+    """Return a factory serving the container's consumers through a :class:`ServiceLocator`.
+
+    The locator is what the handler is given, so the handler never holds the
+    container, and a consumer is built — with its dependencies — only when an
+    event for its source first arrives.
+    """
+
+    async def build() -> ConsumerLocator:
+        container = bundle.container
+        if container is None:
+            raise LogicError(_NO_CONTAINER)
+        return ConsumerLocator(
+            ServiceLocator[ConsumerInterface](
+                container, {name: (cls, None) for name, cls in declared.items()}
+            )
+        )
+
+    return build

xtr_remote_event/bundle/remote_event_config.py

@@ -0,0 +1,22 @@
+"""Configuration for the remote event bundle."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import final
+
+__all__ = ["RemoteEventConfig"]
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class RemoteEventConfig:
+    """What the remote event bundle builds from: nothing.
+
+    Which consumer answers for which source is declared beside each class
+    with ``as_remote_event_consumer``, where the code that consumes is — never
+    in a table an application keeps in step with it by hand. That leaves this
+    bundle with no value to take, so the type exists only to give the bundle
+    the shape every bundle has, and to leave somewhere for a setting to go if
+    one is ever needed.
+    """

xtr_remote_event/consumer/__init__.py

@@ -0,0 +1,8 @@
+"""What an event from another system is handed to."""
+
+from __future__ import annotations
+
+from .consumer_interface import ConsumerInterface
+from .consumer_locator import ConsumerLocator
+
+__all__ = ["ConsumerInterface", "ConsumerLocator"]

xtr_remote_event/consumer/_built_consumers.py

@@ -0,0 +1,65 @@
+"""Consumers already built, handed over by name."""
+
+from __future__ import annotations
+
+from types import MappingProxyType
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+from xtr_service_contracts import ServiceProviderInterface
+
+from xtr_remote_event.exception import LogicError
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable, Mapping
+
+    from .consumer_interface import ConsumerInterface
+
+__all__ = ["BuiltConsumers", "missing_consumer"]
+
+
+def missing_consumer(name: Hashable) -> LogicError:
+    """Return the error for an event of ``name`` that nothing is registered to consume.
+
+    One sentence, written once, because both ways of reaching a consumer end
+    at it: a mapping that never had the name, and a container's locator that
+    was never told about it. A consumer arriving under one name and being
+    asked for under another is the same mistake either way.
+    """
+    return LogicError(f'Unable to find a consumer for message of type "{name}".')
+
+
+@final
+class BuiltConsumers(ServiceProviderInterface["ConsumerInterface"]):
+    """Hands over consumers from a mapping — the locator for code with no container."""
+
+    __slots__ = ("_consumers",)
+
+    def __init__(self, consumers: Mapping[str, ConsumerInterface]) -> None:
+        """Hand over ``consumers``, by name.
+
+        The mapping is copied: what it holds is fixed once a locator is built,
+        so a caller still writing to its own dict cannot change who answers
+        for a source halfway through a worker's run.
+        """
+        self._consumers = dict(consumers)
+
+    @override
+    async def get(self, name: Hashable, /) -> ConsumerInterface:
+        """Return the consumer registered under ``name``.
+
+        Raises:
+            LogicError: If there is none.
+        """
+        consumer = self._consumers.get(str(name))
+        if consumer is None:
+            raise missing_consumer(name)
+        return consumer
+
+    @override
+    def has(self, name: Hashable, /) -> bool:
+        return str(name) in self._consumers
+
+    @override
+    def provided_services(self) -> Mapping[Hashable, type[object]]:
+        return MappingProxyType({name: type(c) for name, c in self._consumers.items()})

xtr_remote_event/consumer/consumer_interface.py

@@ -0,0 +1,29 @@
+"""What an event from another system is handed to."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from xtr_remote_event.remote_event import RemoteEvent
+
+__all__ = ["ConsumerInterface"]
+
+
+@runtime_checkable
+class ConsumerInterface(Protocol):
+    """Does whatever this application does with the events of a source.
+
+    One method, returning nothing: a consumer is the end of the line, not a
+    step in a chain. Which sources it answers for is not its business either —
+    that is declared beside the class with ``as_remote_event_consumer``, so one
+    consumer can serve several sources, and a source can be moved to another
+    consumer without either of them changing.
+
+    Async because consuming is where the work is: a row written, a mail sent,
+    a call back to the sender.
+    """
+
+    async def consume(self, event: RemoteEvent) -> None:
+        """Do what this application does with ``event``."""
+        ...

xtr_remote_event/consumer/consumer_locator.py

@@ -0,0 +1,59 @@
+"""Consumers by the name of the source they answer for."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+from xtr_service_contracts import ServiceProviderInterface
+
+from ._built_consumers import BuiltConsumers, missing_consumer
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable
+
+    from .consumer_interface import ConsumerInterface
+
+__all__ = ["ConsumerLocator"]
+
+
+@final
+class ConsumerLocator(ServiceProviderInterface["ConsumerInterface"]):
+    """Hands over the consumer of a source, by the name the source is known under.
+
+    Over consumers already built, or over a container's locator that builds
+    each one — with its dependencies — when an event for it first arrives.
+    The handler takes this rather than either, so where the consumers come
+    from is the application's business and not the handler's.
+    """
+
+    __slots__ = ("_consumers",)
+
+    def __init__(
+        self,
+        consumers: Mapping[str, ConsumerInterface] | ServiceProviderInterface[ConsumerInterface],
+    ) -> None:
+        """Hand over ``consumers``, by name."""
+        self._consumers: ServiceProviderInterface[ConsumerInterface] = (
+            BuiltConsumers(consumers) if isinstance(consumers, Mapping) else consumers
+        )
+
+    @override
+    async def get(self, name: Hashable, /) -> ConsumerInterface:
+        """Return the consumer of the source ``name``.
+
+        Raises:
+            LogicError: If there is none.
+        """
+        if not self._consumers.has(name):
+            raise missing_consumer(name)
+        return await self._consumers.get(name)
+
+    @override
+    def has(self, name: Hashable, /) -> bool:
+        return self._consumers.has(name)
+
+    @override
+    def provided_services(self) -> Mapping[Hashable, type[object]]:
+        return self._consumers.provided_services()

xtr_remote_event/decorator/__init__.py

@@ -0,0 +1,10 @@
+"""The declarations an application writes beside its consumers."""
+
+from __future__ import annotations
+
+from .as_remote_event_consumer import (
+    as_remote_event_consumer,
+    remote_event_consumers_declared_on,
+)
+
+__all__ = ["as_remote_event_consumer", "remote_event_consumers_declared_on"]