xtr-webhook 4.0.2__py3-none-any.whl

xtr_webhook/controller/webhook_controller.py

@@ -0,0 +1,140 @@
+"""What answers a webhook: read it, hand on what it carried, reply to its sender."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Final, TypeVar, final
+
+from xtr_http_message_contracts import ResponseInterface
+from xtr_remote_event import RemoteEvent
+from xtr_remote_event.messenger import ConsumeRemoteEventMessage
+
+from xtr_webhook.exception import RejectWebhookError
+
+from ._built_parsers import BuiltParsers
+
+if TYPE_CHECKING:
+    from xtr_http_message_contracts import ServerRequestInterface
+    from xtr_messenger import MessageBusInterface
+    from xtr_service_contracts import ServiceProviderInterface
+
+    from xtr_webhook.client import RequestParserInterface
+
+__all__ = ["WebhookController"]
+
+R = TypeVar("R", bound=ResponseInterface)
+
+_NOT_FOUND: Final = 404
+_PLAIN_TEXT: Final = "text/plain; charset=utf-8"
+_NO_PARSER: Final = "No webhook parser found for the type given in the URL."
+_UNPARSABLE: Final = "Unable to parse the webhook payload."
+
+
+async def _as_plain_text(
+    response: R,
+    status_code: int,
+    reason: str,
+    headers: Mapping[str, str],
+) -> R:
+    """Return ``response`` carrying ``reason`` as text under ``status_code``.
+
+    ``headers`` is applied last, so a refusal that needs a header of its own —
+    a challenge under a 401 — sets it, and may override the content type if
+    its own answer is not text.
+    """
+    answered = response.with_status(status_code).with_header("Content-Type", _PLAIN_TEXT)
+    for name, value in headers.items():
+        answered = answered.with_header(name, value)
+    _ = await answered.get_body().write(reason.encode())
+
+    return answered
+
+
+@final
+class WebhookController:
+    """Receives every incoming webhook, whoever sent it.
+
+    One endpoint for every subscriber, told apart by the type in the URL: that
+    type picks the parser that reads the webhook and the secret it is checked
+    against, so adding a subscriber is configuration rather than another route.
+
+    What the endpoint itself does is deliberately small. Reading a webhook is
+    the parser's, handling what it carried is the consumer's, and in between
+    this does the one thing neither can: answer the sender now, and leave the
+    work for a worker. A sender waiting on a handler is a sender that times
+    out and sends the webhook again.
+    """
+
+    __slots__ = ("_bus", "_parsers", "_secrets")
+
+    def __init__(
+        self,
+        parsers: ServiceProviderInterface[RequestParserInterface]
+        | Mapping[str, RequestParserInterface],
+        secrets: Mapping[str, str],
+        bus: MessageBusInterface,
+    ) -> None:
+        """Receive webhooks for the types ``parsers`` speaks for.
+
+        Args:
+            parsers: The parser reading each type, by type. A container's
+                locator builds each on the first webhook for it; a mapping of
+                parsers built by hand is wrapped in one that behaves the same.
+            secrets: What each type's webhooks are checked against, by type.
+                Copied, so what a type is checked against cannot change under
+                a request. A type with no entry is checked against an empty
+                secret, which a parser verifying anything refuses.
+            bus: Where an event that was read is handed on.
+        """
+        self._parsers: ServiceProviderInterface[RequestParserInterface] = (
+            BuiltParsers(parsers) if isinstance(parsers, Mapping) else parsers
+        )
+        self._secrets = dict(secrets)
+        self._bus = bus
+
+    async def index_action(
+        self,
+        event_type: str,
+        request: ServerRequestInterface,
+        response: R,
+    ) -> R:
+        """Read the webhook that arrived for ``event_type``, and answer its sender.
+
+        Every answer but the last is a refusal, and each says as little as the
+        sender needs: a type nothing speaks for is a 404, because from the
+        sender's side that URL does not exist; a webhook the parser would not
+        take is whatever the parser answers; a webhook it read nothing out of
+        is refused as unparsable rather than accepted and dropped.
+
+        Anything else raised on the way out — a bus with nothing to handle the
+        event above all — is left to propagate. The sender then gets a 5xx and
+        sends the webhook again, which is the only outcome that does not lose
+        what it carried.
+
+        Args:
+            event_type: The type in the URL: which subscriber this is for.
+            request: The webhook as it arrived.
+            response: The response to answer with, to fill in and give back.
+
+        Returns:
+            ``response`` with the answer on it.
+        """
+        if not self._parsers.has(event_type):
+            return await _as_plain_text(response, _NOT_FOUND, _NO_PARSER, {})
+
+        parser = await self._parsers.get(event_type)
+
+        try:
+            events = await parser.parse(request, self._secrets.get(event_type, ""))
+        except RejectWebhookError as refused:
+            return await _as_plain_text(
+                response, refused.status_code, str(refused), refused.headers
+            )
+
+        if not events:
+            return await parser.create_rejected_response(_UNPARSABLE, request, response)
+
+        for event in [events] if isinstance(events, RemoteEvent) else events:
+            _ = await self._bus.dispatch(ConsumeRemoteEventMessage(event_type, event))
+
+        return await parser.create_successful_response(request, response)

xtr_webhook/exception/__init__.py

@@ -0,0 +1,25 @@
+"""Every error this library raises.
+
+All of them derive from :class:`WebhookError`, so one ``except`` catches anything a
+webhook can go wrong with, and a narrower one handles a single cause. Each carries what
+went wrong as typed attributes rather than forcing a message to be parsed — and none of
+them repeats a secret.
+"""
+
+from __future__ import annotations
+
+from .delivery_error import DeliveryError
+from .invalid_argument_error import InvalidArgumentError
+from .logic_error import LogicError
+from .reject_webhook_error import RejectWebhookError
+from .webhook_error import WebhookError
+from .webhook_runtime_error import WebhookRuntimeError
+
+__all__ = [
+    "DeliveryError",
+    "InvalidArgumentError",
+    "LogicError",
+    "RejectWebhookError",
+    "WebhookError",
+    "WebhookRuntimeError",
+]

xtr_webhook/exception/delivery_error.py

@@ -0,0 +1,38 @@
+"""An outgoing webhook was not accepted by the receiver."""
+
+from __future__ import annotations
+
+from .webhook_runtime_error import WebhookRuntimeError
+
+__all__ = ["DeliveryError"]
+
+
+class DeliveryError(WebhookRuntimeError):
+    """A receiver answered an outgoing webhook with a status that is not a success.
+
+    Raised rather than returned, because a delivery runs inside a message handler:
+    an error is what makes the bus retry it and, once the attempts are spent, keep
+    the message instead of dropping it. A receiver that was merely restarting then
+    costs nothing, and one that stays broken leaves a message to look at.
+
+    A delivery nothing answered at all is the client's own ``TransportError``, raised
+    before this one could be, so the status here is always one a receiver sent.
+
+    Attributes:
+        status_code: What the receiver answered with.
+        url: Where the webhook was going.
+    """
+
+    status_code: int
+    url: str
+
+    def __init__(self, status_code: int, url: str) -> None:
+        """Record where the webhook was going and what came back.
+
+        Args:
+            status_code: What the receiver answered with.
+            url: Where the webhook was going.
+        """
+        self.status_code = status_code
+        self.url = url
+        super().__init__(f'The webhook to "{url}" was answered with HTTP {status_code}.')

xtr_webhook/exception/invalid_argument_error.py

@@ -0,0 +1,18 @@
+"""A value handed to this library cannot be used."""
+
+from __future__ import annotations
+
+from .webhook_error import WebhookError
+
+__all__ = ["InvalidArgumentError"]
+
+
+class InvalidArgumentError(WebhookError, ValueError):
+    """A value handed to this library cannot be used: a signature format, an empty secret.
+
+    Also a :class:`ValueError`, so code that already guards against a bad value
+    catches it without knowing this library exists. It is never an answer to a
+    request: a webhook refused because of what it carries is a
+    :class:`RejectWebhookError <xtr_webhook.exception.RejectWebhookError>`, while
+    this is a mistake in the configuration to be fixed.
+    """

xtr_webhook/exception/logic_error.py

@@ -0,0 +1,15 @@
+"""This library was used in a way that cannot work."""
+
+from __future__ import annotations
+
+from .webhook_error import WebhookError
+
+__all__ = ["LogicError"]
+
+
+class LogicError(WebhookError, RuntimeError):
+    """This library was used in a way that cannot work, whatever the request carries.
+
+    A parser asked for a header its format never sends, a signer without a secret
+    to sign with: each is a mistake in the code, so retrying it changes nothing.
+    """

xtr_webhook/exception/reject_webhook_error.py

@@ -0,0 +1,52 @@
+"""An incoming webhook is refused, and the answer to send back says so."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .webhook_error import WebhookError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+__all__ = ["RejectWebhookError"]
+
+
+class RejectWebhookError(WebhookError):
+    """An incoming webhook is refused: it carries the answer the sender is given.
+
+    Everything here reaches the sender — the endpoint answers with the status,
+    the headers, and the message as a plain-text body. A sender is not debugged
+    by the receiver, so the message says which check refused it and nothing
+    more: never the values that failed it, nothing an attacker could probe with.
+    The default, 406, says the request was understood and still not acceptable,
+    which is what a wrong signature, a stale timestamp or an unreadable payload
+    all amount to from the sender's side.
+
+    Attributes:
+        status_code: What to answer with.
+        headers: Headers the answer must carry, empty unless the status needs any.
+    """
+
+    status_code: int
+    headers: Mapping[str, str]
+
+    def __init__(
+        self,
+        status_code: int = 406,
+        message: str = "",
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        """Refuse the webhook, and record what to answer.
+
+        Args:
+            status_code: What to answer with.
+            message: Why it was refused. The endpoint sends it to the sender as
+                the answer's plain-text body, so name the check that refused the
+                webhook, never the values that failed it.
+            headers: Headers the answer must carry.
+        """
+        self.status_code = status_code
+        # Copied so the caller's mapping cannot change the answer after the refusal.
+        self.headers = {} if headers is None else dict(headers)
+        super().__init__(message)

xtr_webhook/exception/webhook_error.py

@@ -0,0 +1,9 @@
+"""The error every other error of this package derives from."""
+
+from __future__ import annotations
+
+__all__ = ["WebhookError"]
+
+
+class WebhookError(Exception):
+    """Something a webhook could not be — catch this to catch them all."""

xtr_webhook/exception/webhook_runtime_error.py

@@ -0,0 +1,16 @@
+"""Something a webhook depends on failed while it was being handled."""
+
+from __future__ import annotations
+
+from .webhook_error import WebhookError
+
+__all__ = ["WebhookRuntimeError"]
+
+
+class WebhookRuntimeError(WebhookError, RuntimeError):
+    """Something a webhook depends on failed while it was handled — a receiver that refuses.
+
+    The input was fine and the code is fine; the world did not cooperate. Raising
+    one out of a message handler is what makes a message bus retry the delivery and,
+    once it has run out of attempts, keep the message rather than drop it.
+    """

xtr_webhook/messenger/__init__.py

@@ -0,0 +1,14 @@
+"""Sending a webhook on a message bus: the message, and what handles it.
+
+Delivering through the bus rather than inline is what gives sending everything the
+bus already has — retries with a delay, a dead-letter place for what stays refused,
+and a worker pool to do the waiting — without this library growing a retry policy of
+its own.
+"""
+
+from __future__ import annotations
+
+from .send_webhook_handler import SendWebhookHandler
+from .send_webhook_message import SendWebhookMessage
+
+__all__ = ["SendWebhookHandler", "SendWebhookMessage"]

xtr_webhook/messenger/send_webhook_handler.py

@@ -0,0 +1,49 @@
+"""Delivers the webhook a :class:`SendWebhookMessage` asks for."""
+
+from __future__ import annotations
+
+from typing import final
+
+from xtr_messenger import as_message_handler
+
+from xtr_webhook.server.transport_interface import TransportInterface
+
+from .send_webhook_message import SendWebhookMessage
+
+__all__ = ["SendWebhookHandler"]
+
+
+@as_message_handler(SendWebhookMessage)
+@final
+class SendWebhookHandler:
+    """Hands the message's subscriber and event to the transport, and nothing else.
+
+    It is handed a :class:`~xtr_webhook.server.TransportInterface`, never a
+    container: delivering is the only question it has, so a handler given the
+    container could reach everything else the application registered as well.
+
+    Queueing the delivery is what keeps a slow receiver out of the request that
+    caused the event. The price is that the subscriber secret travels inside the
+    queued message body, so the queue storage must be trusted. The bus itself adds
+    nothing to that: its logging middleware records the message type, the
+    transport, the message id, the handler name and the stamps — never the body.
+    """
+
+    __slots__ = ("_transport",)
+
+    def __init__(self, transport: TransportInterface) -> None:
+        """Deliver through ``transport``."""
+        self._transport = transport
+
+    async def __call__(self, message: SendWebhookMessage) -> None:
+        """Deliver ``message.event`` to ``message.subscriber``.
+
+        Nothing is caught. A refusal is what makes the bus try the delivery
+        again and, once the attempts are spent, keep the message instead of
+        dropping it; swallowing it here would turn every refused webhook into
+        one silently never sent.
+
+        Raises:
+            DeliveryError: When the receiver did not accept the webhook.
+        """
+        await self._transport.send(message.subscriber, message.event)

xtr_webhook/messenger/send_webhook_message.py

@@ -0,0 +1,36 @@
+"""Asks for one event to be signed and delivered to one subscriber."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import final
+
+from xtr_messenger import as_message
+from xtr_remote_event import RemoteEvent
+
+from xtr_webhook.subscriber import Subscriber
+
+__all__ = ["SendWebhookMessage"]
+
+
+@as_message(name="xtr_webhook.send.v1")
+@final
+@dataclass(frozen=True, slots=True)
+class SendWebhookMessage:
+    """Deliver ``event`` to ``subscriber``.
+
+    What turns deciding to send a webhook into sending one, and the reason the
+    two happen in different processes: whatever decided returns at once, and the
+    receiver — which may be slow, restarting or gone — is somebody else's wait.
+
+    It carries the subscriber whole rather than an id to look up, because this
+    library stores no subscribers; the application knows where a webhook goes
+    and what signs it, and says so once, here.
+
+    Attributes:
+        subscriber: Where the webhook goes, and the secret it is signed with.
+        event: What to deliver, exactly as the sender described it.
+    """
+
+    subscriber: Subscriber
+    event: RemoteEvent

xtr_webhook/recipe/__init__.py

@@ -0,0 +1,18 @@
+"""This directory holds the package's recipe: its manifest and its template.
+
+The recipe is what *Use in an application* in the README lists, written as
+data: the bundle to list, the configuration module to write, and the
+environment variable the written module reads. An application applies it with
+``xtr-recipes recipes:sync``, which finds this module through the
+``xtr_recipes`` entry point.
+
+The endpoint needs no step of its own: ``setup`` adds it, and the routes file
+this recipe writes says where. Naming each sender's type is left to a person.
+
+Nothing is importable from here. The manifest and the template are read as
+files, so a recipe is the same from a wheel as from a working tree.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

xtr_webhook/recipe/files/config/routes/webhook.py.tmpl

@@ -0,0 +1,25 @@
+"""Where this application receives webhooks: ``POST /webhook/{type}`` by default.
+
+Give each sender the URL built from the route's name, ``"webhook"``, rather than
+writing the path out: a sender that was told a URL keeps sending to it long
+after the deploy that moved it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from xtr_http_kernel.routing.decorator import as_routes
+
+if TYPE_CHECKING:
+    from xtr_http_kernel.routing.loader.configurator import RoutingConfigurator
+
+__all__ = ["webhook"]
+
+
+@as_routes
+def webhook(routes: RoutingConfigurator) -> None:
+    """Serve the endpoint at its default path."""
+    _ = routes.import_("webhook")
+    # Keep everything a stranger may call under one path:
+    # _ = routes.import_("webhook").prefix("/hooks")

xtr_webhook/recipe/files/config/webhook.py.tmpl

@@ -0,0 +1,33 @@
+"""Webhooks: which types the endpoint serves, and what each is verified against.
+
+One route per sender. The type is the segment in the URL the endpoint serves —
+``POST /webhook/{type}`` — so the subscriber is given that URL and nothing else
+has to change when another sender is added.
+
+The secret is read when the endpoint is built, not when the application boots,
+so a placeholder keeps it out of this file and out of every container report.
+"""
+
+from __future__ import annotations
+
+from xtr_dependency_injection import configure, env
+from xtr_webhook.bundle import RouteConfig, WebhookConfig
+
+__all__ = ["webhook"]
+
+
+@configure
+def webhook() -> WebhookConfig:
+    """One type, verified with the bundle's own parser against ``WEBHOOK_SECRET``."""
+    return WebhookConfig(
+        routing={
+            # A route with no parser uses the bundle's own, which verifies the
+            # signature_format below. Name a class here for a sender that signs
+            # its own way: RouteConfig(parser=AcmeRequestParser, secret=...).
+            "acme": RouteConfig(secret=env("WEBHOOK_SECRET")),
+        },
+        # "legacy", "standard" or "transitional" — both ends must agree. Only
+        # the Standard Webhooks signature covers the timestamp, so only it is
+        # bounded by timestamp_tolerance.
+        signature_format="legacy",
+    )

xtr_webhook/recipe/manifest.toml

@@ -0,0 +1,35 @@
+# The recipe for xtr-webhook: what *Use in an application* in the README takes,
+# as data. Keep the two in step — the README is the source.
+
+[bundles]
+# "<module>:<class>" = the environments it is listed with, exactly as in BUNDLES.
+"xtr_webhook.bundle:WebhookBundle" = { all = true }
+
+[files]
+# Destination under the application package = template under this recipe.
+# Needed to receive anything: with no routing the endpoint knows no type, and
+# every webhook is answered 404.
+"config/webhook.py" = "files/config/webhook.py.tmpl"
+# Where the endpoint is served: POST /webhook/{type}, with the line that moves
+# it under a prefix written beside it.
+"config/routes/webhook.py" = "files/config/routes/webhook.py.tmpl"
+
+[env]
+# The secret the written routing verifies its one example type against. No
+# default to offer — a secret is the sender's — so it is written commented out
+# and stays unset until the sender names one.
+WEBHOOK_SECRET = ""
+
+[gitignore]
+# Nothing of its own: a webhook is read and handed on, never written to disk.
+lines = []
+
+[notes]
+steps = [
+  "Call setup(app, kernel) where the application is built: it adds the endpoint, POST /webhook/{type}, arranged by the written config/routes/webhook.py.",
+  "Name each sender's type in config/webhook.py and give its subscribers the URL that type is served at.",
+]
+check = [
+  "<script> debug:bundles — webhook and remote_event are listed and active",
+  "<script> debug:config webhook — the resolved routing, header names and signature format",
+]

xtr_webhook/routing/__init__.py

@@ -0,0 +1,11 @@
+"""The endpoint webhooks arrive at, contributed to the application's route table.
+
+- :class:`WebhookRouteLoader` — resource ``"webhook"``: ``POST /webhook/{type}``, movable
+  under a prefix.
+"""
+
+from __future__ import annotations
+
+from .webhook_route_loader import WebhookRouteLoader
+
+__all__ = ["WebhookRouteLoader"]

xtr_webhook/routing/_endpoints.py

@@ -0,0 +1,38 @@
+"""The endpoint webhooks arrive at: a thin adapter handing each one to its controller."""
+
+from __future__ import annotations
+
+# Every imported name below annotates an endpoint parameter or its return, and
+# both the web framework and the container read those annotations when the
+# application starts, so none of them can hide under TYPE_CHECKING.
+from xtr_dependency_injection import (
+    Injected,  # noqa: TC002 -- the container reads these endpoint annotations at runtime
+)
+from xtr_http_kernel.bridge import (
+    Response,  # noqa: TC002 -- the container reads these endpoint annotations at runtime
+)
+from xtr_http_message_contracts import (  # noqa: TC002 -- the container reads these endpoint annotations at runtime
+    ServerRequestInterface,
+)
+
+from xtr_webhook.controller.webhook_controller import (  # noqa: TC001 -- the container reads these endpoint annotations at runtime
+    WebhookController,
+)
+
+__all__ = ["webhook"]
+
+
+async def webhook(
+    type: str,  # noqa: A002 -- the path segment the endpoint is declared with
+    controller: Injected[WebhookController],
+    request: Injected[ServerRequestInterface],
+    response: Injected[Response],
+) -> Response:
+    """Read the webhook that arrived, and answer its sender.
+
+    One endpoint serves every subscriber. The type in the URL is what tells them
+    apart: it picks the parser that reads the webhook and the secret it is
+    checked against, both of which are configuration, so a new subscriber needs
+    no new route.
+    """
+    return await controller.index_action(type, request, response)

xtr_webhook/routing/webhook_route_loader.py

@@ -0,0 +1,31 @@
+"""The route webhooks arrive at."""
+
+from __future__ import annotations
+
+from typing import final
+
+from xtr_http_kernel.routing import Route, RouteCollection
+from xtr_http_kernel.routing.decorator import as_route_loader
+
+from xtr_webhook._endpoint_paths import ROUTE_NAME, WEBHOOK_PATH
+
+from ._endpoints import webhook
+
+__all__ = ["WebhookRouteLoader"]
+
+
+@final
+@as_route_loader("webhook")
+class WebhookRouteLoader:
+    """The one endpoint every incoming webhook arrives at, ``POST /webhook/{type}``.
+
+    An application imports it as ``"webhook"`` and may move it under a prefix
+    in a routes file. Wherever it lands, the URL a sender is given has to be the
+    path served, so build it from the route's name rather than writing it out.
+    """
+
+    def load_routes(self) -> RouteCollection:
+        """Return the endpoint at its default path and name."""
+        routes = RouteCollection()
+        routes.add(ROUTE_NAME, Route(WEBHOOK_PATH, webhook, methods=("POST",)))
+        return routes

xtr_webhook/server/__init__.py

@@ -0,0 +1,39 @@
+"""The sending side: what a webhook leaving this application is signed and shaped like.
+
+A webhook is built by a chain of configurators, each writing one part of the same
+:class:`OutgoingRequest` — the headers that name the event, the body the payload is
+written into, the signature over both. They are separate because receivers disagree
+about all three, so an application that has to satisfy an unusual one adds or replaces
+a step rather than the sender.
+
+The :class:`Transport` runs that chain and posts the result through an
+:class:`~xtr_http_client_contracts.HttpClientInterface` — the contract alone, so
+everything here imports with no HTTP client installed; xtr-http-client, the ``client``
+extra, is the client.
+"""
+
+from __future__ import annotations
+
+from .header_signature_configurator import HeaderSignatureConfigurator
+from .headers_configurator import HeadersConfigurator
+from .json_body_configurator import JsonBodyConfigurator
+from .json_payload_serializer import JsonPayloadSerializer
+from .outgoing_request import OutgoingRequest
+from .payload_serializer_interface import PayloadSerializerInterface
+from .request_configurator_interface import RequestConfiguratorInterface
+from .signature_format import SignatureFormat
+from .transport import Transport
+from .transport_interface import TransportInterface
+
+__all__ = [
+    "HeaderSignatureConfigurator",
+    "HeadersConfigurator",
+    "JsonBodyConfigurator",
+    "JsonPayloadSerializer",
+    "OutgoingRequest",
+    "PayloadSerializerInterface",
+    "RequestConfiguratorInterface",
+    "SignatureFormat",
+    "Transport",
+    "TransportInterface",
+]