xtr-webhook 4.0.2__py3-none-any.whl

xtr_webhook/bundle/_routed_parsers.py

@@ -0,0 +1,70 @@
+"""The parser each configured webhook type is read by, reached through the container."""
+
+from __future__ import annotations
+
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Final, final
+
+from typing_extensions import override
+from xtr_service_contracts import ServiceProviderInterface
+
+from xtr_webhook.exception import LogicError
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable, Mapping
+
+    from xtr_dependency_injection import ServiceLocator
+
+    from xtr_webhook.client.request_parser_interface import RequestParserInterface
+
+__all__ = ["ROUTE_QUALIFIER", "RoutedParsers"]
+
+#: The qualifier each configured type's parser is aliased under. Apart from the
+#: bundle's own ``webhook`` qualifier, so a type named ``webhook`` reads with the
+#: parser its route names, and no type is served that routing did not name.
+ROUTE_QUALIFIER: Final = "webhook.route.{type}"
+
+
+@final
+class RoutedParsers(ServiceProviderInterface["RequestParserInterface"]):
+    """Hands the controller the parser of each type the routing names, and no other.
+
+    The container's locator over every parser is filtered down to the types
+    the routing names, each reached under its own qualifier, so a parser — and
+    what it needs — is built the first time a webhook of its type arrives.
+    """
+
+    __slots__ = ("_locator", "_qualifiers")
+
+    def __init__(
+        self,
+        locator: ServiceLocator[RequestParserInterface],
+        types: tuple[str, ...],
+    ) -> None:
+        """Serve ``types``, each read through ``locator`` under its route's qualifier."""
+        self._locator = locator
+        self._qualifiers = {name: ROUTE_QUALIFIER.format(type=name) for name in types}
+
+    @override
+    async def get(self, name: Hashable, /) -> RequestParserInterface:
+        """Return the parser reading webhooks of the type ``name``.
+
+        Raises:
+            LogicError: If the routing names no such type. The endpoint asks
+                :meth:`has` first and answers 404 itself.
+        """
+        qualifier = self._qualifiers.get(str(name))
+        if qualifier is None:
+            raise LogicError(f'Unable to find a parser for the webhook type "{name}".')
+        return await self._locator.get(qualifier)
+
+    @override
+    def has(self, name: Hashable, /) -> bool:
+        return str(name) in self._qualifiers
+
+    @override
+    def provided_services(self) -> Mapping[Hashable, type[object]]:
+        provided = self._locator.provided_services()
+        return MappingProxyType(
+            {name: provided[qualifier] for name, qualifier in self._qualifiers.items()}
+        )

xtr_webhook/bundle/no_private_network_config.py

@@ -0,0 +1,59 @@
+"""What the outbound guard refuses, and the few addresses it still allows."""
+
+from __future__ import annotations
+
+import ipaddress
+from dataclasses import dataclass
+from typing import final
+
+from xtr_webhook.exception import InvalidArgumentError
+
+__all__ = ["NoPrivateNetworkConfig"]
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class NoPrivateNetworkConfig:
+    """Whether the client webhooks are sent through refuses to deliver into a private network.
+
+    Off by default: a receiver on this network is a legitimate setup until the
+    application says otherwise. Turned on, it wraps that client in
+    :class:`~xtr_http_client.NoPrivateNetworkHttpClient`, which checks what
+    every destination *resolves to* before anything is sent.
+
+    Attributes:
+        enabled: Whether outgoing webhooks are vetted at all.
+        subnets: The networks to refuse, in CIDR notation, replacing the
+            default. ``None`` refuses every address that is not globally
+            routable — loopback, private, link-local, carrier-grade NAT,
+            unique-local, multicast, reserved and unspecified alike.
+        allow_list: Networks or single addresses exempt from the refusal.
+            Addresses only, never hostnames: the check runs on resolved
+            addresses, and a name could point anywhere by the time it is used.
+    """
+
+    enabled: bool = False
+    subnets: tuple[str, ...] | None = None
+    allow_list: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        """Refuse an entry that names no network, and tuning on a guard that is off.
+
+        The second check exists because this configuration cannot imply
+        consent: naming subnets does not turn the guard on, so accepting them
+        while it is off would leave an application believing it is protected.
+
+        Raises:
+            InvalidArgumentError: When ``subnets`` or ``allow_list`` is given
+                while ``enabled`` is ``False``, or an entry is not an IP
+                network or address.
+        """
+        if not self.enabled and (self.subnets is not None or self.allow_list):
+            raise InvalidArgumentError(
+                "no_private_network.subnets and allow_list take effect only with enabled=True.",
+            )
+        for entry in (*(self.subnets or ()), *self.allow_list):
+            try:
+                _ = ipaddress.ip_network(entry, strict=False)
+            except ValueError as error:
+                raise InvalidArgumentError(f'"{entry}" is not an IP network.') from error

xtr_webhook/bundle/route_config.py

@@ -0,0 +1,34 @@
+"""One webhook type's route: which parser reads it, and what verifies it."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import final
+
+from xtr_webhook.client.request_parser_interface import RequestParserInterface
+
+__all__ = ["RouteConfig"]
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class RouteConfig:
+    """What the endpoint does with webhooks of one type.
+
+    Attributes:
+        parser: The class reading this type's webhooks, built by the container
+            with its dependencies on the first webhook for it. ``None`` means
+            the bundle's own configured
+            :class:`~xtr_webhook.client.RequestParser`, which verifies the
+            signature scheme the bundle's ``signature_format`` names.
+        secret: What this type's webhooks are verified against. Pass it
+            through the container's ``env("...")`` placeholder, never as a
+            literal: a placeholder is read only when the endpoint is built,
+            and no container report prints it. It must be set in production —
+            with an empty value, depending on the parser, requests from any
+            sender are accepted or every request is rejected. Kept out of the
+            ``repr``.
+    """
+
+    parser: type[RequestParserInterface] | None = None
+    secret: str = field(default="", repr=False)

xtr_webhook/bundle/webhook_bundle.py

@@ -0,0 +1,262 @@
+"""The xtr-webhook bundle: the receiving endpoint and the signing sender, from one config.
+
+An application listing :class:`WebhookBundle` — which brings the remote-event,
+messenger and HTTP kernel bundles with it, and the HTTP client bundle when
+xtr-http-client is installed — gets the endpoint webhooks arrive at, which
+``setup`` mounts, and its controller, a configured
+:class:`~xtr_webhook.client.RequestParser` under the ``webhook`` qualifier,
+and — with xtr-http-client — the transport that delivers a
+``SendWebhookMessage`` and the handler that listens for one. The handler is
+registered only alongside the transport it needs, so a container never holds a
+handler it cannot build; without the ``client`` extra, dispatching a
+``SendWebhookMessage`` fails with the bus's no-handler error.
+"""
+
+from __future__ import annotations
+
+from importlib.util import find_spec
+from typing import TYPE_CHECKING, Annotated, Final, final
+
+from typing_extensions import override
+from xtr_dependency_injection import (
+    Bundle,
+    ContainerBuilder,
+    ServiceConfigurator,
+    ServiceLocator,
+    Target,
+    as_bundle,
+    named_factory,
+    required_bundle,
+)
+from xtr_http_client_contracts import HttpClientInterface
+from xtr_http_kernel.bundle import HttpKernelBundle
+from xtr_messenger import MessageBusInterface
+from xtr_remote_event.bundle import RemoteEventBundle
+
+from xtr_webhook.client.request_parser import RequestParser
+from xtr_webhook.client.request_parser_interface import RequestParserInterface
+from xtr_webhook.controller.webhook_controller import WebhookController
+from xtr_webhook.exception import LogicError
+from xtr_webhook.server.header_signature_configurator import HeaderSignatureConfigurator
+from xtr_webhook.server.headers_configurator import HeadersConfigurator
+from xtr_webhook.server.json_body_configurator import JsonBodyConfigurator
+from xtr_webhook.server.json_payload_serializer import JsonPayloadSerializer
+from xtr_webhook.server.signature_format import SignatureFormat
+from xtr_webhook.server.transport import Transport
+from xtr_webhook.server.transport_interface import TransportInterface
+
+from ._routed_parsers import ROUTE_QUALIFIER, RoutedParsers
+from .webhook_config import WebhookConfig
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+__all__ = ["WebhookBundle"]
+
+_WEBHOOK: Final = "webhook"
+"""The qualifier of the bundle's own parser."""
+
+_SEND_HANDLER_MODULE: Final = "xtr_webhook.messenger.send_webhook_handler"
+
+_ROUTING_MODULE: Final = "xtr_webhook.routing"
+
+
+@final
+@required_bundle(RemoteEventBundle)
+@required_bundle(HttpKernelBundle)
+@required_bundle("xtr_http_client.bundle:HttpClientBundle", ignore_on_invalid=True)
+@as_bundle("webhook", config=WebhookConfig)
+class WebhookBundle(Bundle[WebhookConfig]):
+    """Wires the endpoint's controller and the sender's chain to the container."""
+
+    @override
+    def load_extension(
+        self,
+        config: WebhookConfig,
+        services: ServiceConfigurator,
+        builder: ContainerBuilder,
+    ) -> None:
+        """Register the configurators, the parser, the controller and the sending side.
+
+        The format is converted once, here: the configurators and the parser
+        take a member, and every factory below is handed the same one.
+
+        Raises:
+            LogicError: When the private-network guard is turned on while
+                xtr-http-client, whose client it wraps, is not installed.
+        """
+        del builder
+        fmt = SignatureFormat.parse(config.signature_format)
+
+        _ = services.set(named_factory(_headers_configurator(fmt), "webhook_headers_configurator"))
+        _ = services.set(named_factory(_json_body_configurator(fmt), "webhook_body_configurator"))
+        _ = services.set(named_factory(_signer(fmt), "webhook_signer"))
+
+        _ = services.set(
+            named_factory(_request_parser(fmt), "webhook_request_parser"), qualifier=_WEBHOOK
+        )
+        services.alias(
+            RequestParserInterface,
+            RequestParser,
+            alias_qualifier=_WEBHOOK,
+            target_qualifier=_WEBHOOK,
+        )
+        for parser in _custom_parsers(config):
+            _ = services.set(parser)
+        # Each configured type's parser, under a qualifier of its own: the
+        # controller reaches them through a locator the container injects.
+        for name, route in config.routing.items():
+            services.alias(
+                RequestParserInterface,
+                route.parser if route.parser is not None else RequestParser,
+                alias_qualifier=ROUTE_QUALIFIER.format(type=name),
+                target_qualifier=None if route.parser is not None else _WEBHOOK,
+            )
+
+        _ = services.set(named_factory(_webhook_controller, "webhook_controller"))
+        # The route loader: scanned so the http kernel builds the endpoint into
+        # the application's table, which setup() mounts.
+        services.load(_ROUTING_MODULE)
+
+        if find_spec("xtr_http_client") is not None:
+            _ = services.set(named_factory(_transport(config.http_client), "webhook_transport"))
+            services.alias(TransportInterface, Transport)
+            # The handler needs the transport registered just above, so it is
+            # registered with the bus only here: a container must never hold a
+            # handler it cannot build.
+            services.load(_SEND_HANDLER_MODULE)
+        elif config.no_private_network.enabled:
+            raise LogicError(
+                'Configuring "no_private_network" requires xtr-http-client; '
+                'install it with uv add "xtr-webhook[client]".'
+            )
+
+
+def _custom_parsers(config: WebhookConfig) -> tuple[type[RequestParserInterface], ...]:
+    """Return each distinct parser class the routing names, in first-use order.
+
+    Distinct and once: two routes naming one class share one instance, so what
+    the parser keeps between webhooks does not depend on the route they used.
+    """
+    seen: dict[type[RequestParserInterface], None] = {}
+    for route in config.routing.values():
+        if route.parser is not None:
+            seen.setdefault(route.parser)
+    return tuple(seen)
+
+
+def _headers_configurator(fmt: SignatureFormat) -> Callable[[WebhookConfig], HeadersConfigurator]:
+    """Return the factory of the step writing the identifying headers.
+
+    The configuration is injected rather than closed over: the container
+    hands the factory a copy with every environment placeholder resolved.
+    """
+
+    def build(config: WebhookConfig) -> HeadersConfigurator:
+        return HeadersConfigurator(
+            event_header_name=config.event_header_name,
+            id_header_name=config.id_header_name,
+            timestamp_header_name=config.timestamp_header_name,
+            signature_format=fmt,
+        )
+
+    return build
+
+
+def _json_body_configurator(fmt: SignatureFormat) -> Callable[[], JsonBodyConfigurator]:
+    """Return the factory of the step writing the payload as a JSON body."""
+
+    def build() -> JsonBodyConfigurator:
+        return JsonBodyConfigurator(JsonPayloadSerializer(), fmt)
+
+    return build
+
+
+def _signer(fmt: SignatureFormat) -> Callable[[WebhookConfig], HeaderSignatureConfigurator]:
+    """Return the factory of the step signing what the other two wrote."""
+
+    def build(config: WebhookConfig) -> HeaderSignatureConfigurator:
+        return HeaderSignatureConfigurator(
+            algorithm=config.signing_algorithm,
+            signature_header_name=config.signature_header_name,
+            signature_format=fmt,
+            timestamp_header_name=config.timestamp_header_name,
+        )
+
+    return build
+
+
+def _transport(qualifier: str | None) -> Callable[..., Transport]:
+    """Return the factory of the delivery, over the client ``qualifier`` names.
+
+    The qualifier is configuration, so the client's annotation is written onto
+    the factory at runtime rather than in its signature; ``None`` asks for the
+    default client. The guard is read from the injected configuration, and
+    wraps whichever client that is.
+    """
+
+    def build(
+        config: WebhookConfig,
+        client: HttpClientInterface,
+        headers: HeadersConfigurator,
+        body: JsonBodyConfigurator,
+        signer: HeaderSignatureConfigurator,
+    ) -> Transport:
+        guard = config.no_private_network
+        if guard.enabled:
+            # Imported only now: the factory is registered only once
+            # xtr-http-client was found, and the guard is that package's.
+            from xtr_http_client import (  # noqa: PLC0415 -- guarded behind the client extra
+                NoPrivateNetworkHttpClient,
+            )
+
+            client = NoPrivateNetworkHttpClient(client, guard.subnets, guard.allow_list)
+
+        return Transport(client, headers, body, signer)
+
+    build.__annotations__ = {
+        "config": WebhookConfig,
+        "client": (
+            HttpClientInterface
+            if qualifier is None
+            else Annotated[HttpClientInterface, Target(qualifier)]
+        ),
+        "headers": HeadersConfigurator,
+        "body": JsonBodyConfigurator,
+        "signer": HeaderSignatureConfigurator,
+        "return": Transport,
+    }
+    return build
+
+
+def _request_parser(fmt: SignatureFormat) -> Callable[[WebhookConfig], RequestParser]:
+    """Return the factory of the bundle's own parser, the mirror of its sender."""
+
+    def build(config: WebhookConfig) -> RequestParser:
+        return RequestParser(
+            algorithm=config.signing_algorithm,
+            signature_header_name=config.signature_header_name,
+            event_header_name=config.event_header_name,
+            id_header_name=config.id_header_name,
+            timestamp_header_name=config.timestamp_header_name,
+            signature_format=fmt,
+            timestamp_tolerance=config.timestamp_tolerance,
+        )
+
+    return build
+
+
+def _webhook_controller(
+    config: WebhookConfig,
+    bus: MessageBusInterface,
+    parsers: ServiceLocator[RequestParserInterface],
+) -> WebhookController:
+    """Build the endpoint's controller over the parsers the routing names.
+
+    The container injects a locator over every parser; only the routed types
+    are handed on, each under the qualifier its route was aliased with, so a
+    route's parser is built — with its dependencies — the first time a webhook
+    for it arrives. A route naming no parser reads with the bundle's own.
+    """
+    secrets = {name: route.secret for name, route in config.routing.items()}
+    return WebhookController(RoutedParsers(parsers, tuple(config.routing)), secrets, bus)

xtr_webhook/bundle/webhook_config.py

@@ -0,0 +1,80 @@
+"""The one configuration an application writes to receive and send webhooks."""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import final
+
+from xtr_webhook.exception import InvalidArgumentError
+from xtr_webhook.server.signature_format import SignatureFormat
+
+from .no_private_network_config import NoPrivateNetworkConfig
+from .route_config import RouteConfig
+
+__all__ = ["WebhookConfig"]
+
+
+def _no_routes() -> dict[str, RouteConfig]:
+    """The empty routing a zero-config application starts with."""
+    return {}
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class WebhookConfig:
+    """Values the bundle builds the endpoint's and the sender's services from.
+
+    Buildable with no arguments: the zero-config path routes nothing, signs
+    with the legacy scheme under the default header names, and sends through
+    the application's default HTTP client.
+
+    Attributes:
+        http_client: The qualifier of the
+            :class:`~xtr_http_client_contracts.HttpClientInterface` webhooks are
+            sent through — a scoped client of the HTTP client configuration.
+            ``None`` means the default, unqualified one.
+        no_private_network: Whether that client is wrapped in a guard refusing
+            to deliver into a private network, and what counts as one.
+        event_header_name: The header the event's name travels in, where the
+            signature scheme sends one.
+        id_header_name: The header the event's id travels in.
+        timestamp_header_name: The header the send time travels in.
+        signature_header_name: The header the signature entries travel in.
+        signing_algorithm: The digest the legacy signature is made with.
+        signature_format: The signature scheme both ends must share — a
+            :class:`~xtr_webhook.server.SignatureFormat` or the string one
+            carries. Validated here; readers convert with
+            :meth:`SignatureFormat.parse <xtr_webhook.server.SignatureFormat.parse>`.
+        timestamp_tolerance: How many seconds either side of now an incoming
+            signed timestamp may be. Zero turns the replay bound off.
+        routing: What the endpoint does with each webhook type, by the type in
+            the URL. Keys are kept verbatim — dashes too.
+    """
+
+    http_client: str | None = None
+    no_private_network: NoPrivateNetworkConfig = field(default_factory=NoPrivateNetworkConfig)
+    event_header_name: str = "Webhook-Event"
+    id_header_name: str = "Webhook-Id"
+    timestamp_header_name: str = "Webhook-Timestamp"
+    signature_header_name: str = "Webhook-Signature"
+    signing_algorithm: str = "sha256"
+    signature_format: SignatureFormat | str = SignatureFormat.LEGACY
+    timestamp_tolerance: int = 300
+    routing: Mapping[str, RouteConfig] = field(default_factory=_no_routes)
+
+    def __post_init__(self) -> None:
+        """Refuse values no service built from them could honour.
+
+        Raises:
+            InvalidArgumentError: When the tolerance is negative, the
+                algorithm is not available, or the format names no scheme.
+        """
+        if self.timestamp_tolerance < 0:
+            raise InvalidArgumentError("timestamp_tolerance must be greater than or equal to 0.")
+        if self.signing_algorithm not in hashlib.algorithms_available:
+            raise InvalidArgumentError(
+                f'The signing algorithm "{self.signing_algorithm}" is not available.',
+            )
+        _ = SignatureFormat.parse(self.signature_format)

xtr_webhook/client/__init__.py

@@ -0,0 +1,23 @@
+"""The receiving side: what an incoming webhook is checked against and read into.
+
+One parser speaks for one sender. It states which requests are that sender's with a
+matcher, checks that one is genuine, and gives back the events it carried — or refuses
+it, with the answer its sender is to be given.
+
+The matchers themselves come from
+[xtr-http-foundation](https://pypi.org/project/xtr-http-foundation/), so a webhook
+endpoint says which requests are its sender's the same way a firewall or a rate limiter
+does.
+"""
+
+from __future__ import annotations
+
+from .abstract_request_parser import AbstractRequestParser
+from .request_parser import RequestParser
+from .request_parser_interface import RequestParserInterface
+
+__all__ = [
+    "AbstractRequestParser",
+    "RequestParser",
+    "RequestParserInterface",
+]