xtr-webhook 4.0.2__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- xtr_webhook/.agents/skills/xtr-webhook/SKILL.md +350 -0
- xtr_webhook/.agents/skills/xtr-webhook/references/signature-formats.md +189 -0
- xtr_webhook/__init__.py +10 -0
- xtr_webhook/_endpoint_paths.py +22 -0
- xtr_webhook/_standard_webhooks_signature.py +76 -0
- xtr_webhook/bundle/__init__.py +15 -0
- xtr_webhook/bundle/_routed_parsers.py +70 -0
- xtr_webhook/bundle/no_private_network_config.py +59 -0
- xtr_webhook/bundle/route_config.py +34 -0
- xtr_webhook/bundle/webhook_bundle.py +262 -0
- xtr_webhook/bundle/webhook_config.py +80 -0
- xtr_webhook/client/__init__.py +23 -0
- xtr_webhook/client/abstract_request_parser.py +248 -0
- xtr_webhook/client/request_parser.py +272 -0
- xtr_webhook/client/request_parser_interface.py +90 -0
- xtr_webhook/controller/__init__.py +12 -0
- xtr_webhook/controller/_built_parsers.py +65 -0
- xtr_webhook/controller/webhook_controller.py +140 -0
- xtr_webhook/exception/__init__.py +25 -0
- xtr_webhook/exception/delivery_error.py +38 -0
- xtr_webhook/exception/invalid_argument_error.py +18 -0
- xtr_webhook/exception/logic_error.py +15 -0
- xtr_webhook/exception/reject_webhook_error.py +52 -0
- xtr_webhook/exception/webhook_error.py +9 -0
- xtr_webhook/exception/webhook_runtime_error.py +16 -0
- xtr_webhook/messenger/__init__.py +14 -0
- xtr_webhook/messenger/send_webhook_handler.py +49 -0
- xtr_webhook/messenger/send_webhook_message.py +36 -0
- xtr_webhook/py.typed +0 -0
- xtr_webhook/recipe/__init__.py +18 -0
- xtr_webhook/recipe/files/config/routes/webhook.py.tmpl +25 -0
- xtr_webhook/recipe/files/config/webhook.py.tmpl +33 -0
- xtr_webhook/recipe/manifest.toml +35 -0
- xtr_webhook/routing/__init__.py +11 -0
- xtr_webhook/routing/_endpoints.py +38 -0
- xtr_webhook/routing/webhook_route_loader.py +31 -0
- xtr_webhook/server/__init__.py +39 -0
- xtr_webhook/server/header_signature_configurator.py +128 -0
- xtr_webhook/server/headers_configurator.py +92 -0
- xtr_webhook/server/json_body_configurator.py +80 -0
- xtr_webhook/server/json_payload_serializer.py +45 -0
- xtr_webhook/server/outgoing_request.py +35 -0
- xtr_webhook/server/payload_serializer_interface.py +34 -0
- xtr_webhook/server/request_configurator_interface.py +39 -0
- xtr_webhook/server/signature_format.py +65 -0
- xtr_webhook/server/transport.py +106 -0
- xtr_webhook/server/transport_interface.py +40 -0
- xtr_webhook/subscriber.py +41 -0
- xtr_webhook/testing/__init__.py +18 -0
- xtr_webhook/testing/_parser_cases.py +141 -0
- xtr_webhook/testing/parser_case.py +37 -0
- xtr_webhook-4.0.2.dist-info/METADATA +704 -0
- xtr_webhook-4.0.2.dist-info/RECORD +56 -0
- xtr_webhook-4.0.2.dist-info/WHEEL +4 -0
- xtr_webhook-4.0.2.dist-info/entry_points.txt +6 -0
- xtr_webhook-4.0.2.dist-info/licenses/LICENSE +22 -0
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
"""Who receives an outgoing webhook, and the secret it is signed with."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass, field
|
|
6
|
+
from typing import final
|
|
7
|
+
|
|
8
|
+
from xtr_webhook.exception import InvalidArgumentError
|
|
9
|
+
|
|
10
|
+
__all__ = ["Subscriber"]
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
@final
|
|
14
|
+
@dataclass(frozen=True, slots=True)
|
|
15
|
+
class Subscriber:
|
|
16
|
+
"""One receiver of outgoing webhooks: where they go, and what signs them.
|
|
17
|
+
|
|
18
|
+
The pair travels together because neither is useful alone β a url without a
|
|
19
|
+
secret cannot be signed for, and a secret belongs to exactly one receiver. It
|
|
20
|
+
is frozen so the url cannot be changed after a signature was made over it, and
|
|
21
|
+
so one can be put on a message bus and read back as it was sent.
|
|
22
|
+
|
|
23
|
+
Attributes:
|
|
24
|
+
url: Where the webhook is posted.
|
|
25
|
+
secret: What its signature is made with. Kept out of ``repr`` so a log
|
|
26
|
+
line, a traceback or a dumped message cannot carry it.
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
url: str
|
|
30
|
+
secret: str = field(repr=False)
|
|
31
|
+
|
|
32
|
+
def __post_init__(self) -> None:
|
|
33
|
+
"""Refuse a subscriber nothing could be signed for.
|
|
34
|
+
|
|
35
|
+
An empty secret still signs β over the empty key β so it would send
|
|
36
|
+
perfectly formed webhooks no receiver can accept. That is a
|
|
37
|
+
misconfiguration to fix, not a request to refuse, so it is caught here
|
|
38
|
+
rather than at the first delivery.
|
|
39
|
+
"""
|
|
40
|
+
if not self.secret:
|
|
41
|
+
raise InvalidArgumentError("A non-empty secret is required.")
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
"""Testing a parser against the payloads its sender actually posts.
|
|
2
|
+
|
|
3
|
+
A parser is only as trustworthy as the captures it has been shown, and those
|
|
4
|
+
come from the sender: posted once, caught, kept. Keeping each in a file beside
|
|
5
|
+
the events it must become turns adding a case into adding two files β nothing
|
|
6
|
+
to register, nothing to write in the test β and leaves the payloads readable as
|
|
7
|
+
what they are, byte for byte, which is what a signature is made over.
|
|
8
|
+
|
|
9
|
+
The helpers build their requests with xtr-http-message, so they need the
|
|
10
|
+
``testing`` extra: ``uv add --dev "xtr-webhook[testing]"``.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
from ._parser_cases import assert_parses, parser_cases
|
|
16
|
+
from .parser_case import ParserCase
|
|
17
|
+
|
|
18
|
+
__all__ = ["ParserCase", "assert_parses", "parser_cases"]
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
"""Reading a directory of fixture pairs, and driving a parser over one of them."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import runpy
|
|
6
|
+
from typing import TYPE_CHECKING, cast
|
|
7
|
+
|
|
8
|
+
from xtr_http_message import ServerRequest
|
|
9
|
+
|
|
10
|
+
from xtr_webhook.exception import InvalidArgumentError
|
|
11
|
+
|
|
12
|
+
from .parser_case import ParserCase
|
|
13
|
+
|
|
14
|
+
if TYPE_CHECKING:
|
|
15
|
+
from collections.abc import Mapping
|
|
16
|
+
from pathlib import Path
|
|
17
|
+
|
|
18
|
+
from xtr_remote_event import RemoteEvent
|
|
19
|
+
|
|
20
|
+
from xtr_webhook.client import RequestParserInterface
|
|
21
|
+
|
|
22
|
+
__all__ = ["assert_parses", "parser_cases"]
|
|
23
|
+
|
|
24
|
+
_EXPECTATION = "EXPECTED"
|
|
25
|
+
_JSON = "application/json"
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def parser_cases(fixtures_dir: Path, extension: str = "json") -> list[ParserCase]:
|
|
29
|
+
"""Read every fixture pair under ``fixtures_dir`` into a case.
|
|
30
|
+
|
|
31
|
+
A pair is a capture β ``*.<extension>``, the bytes as the sender posted
|
|
32
|
+
them β and a ``*.py`` beside it naming ``EXPECTED``: one
|
|
33
|
+
:class:`~xtr_remote_event.RemoteEvent`, or a list of them for a capture
|
|
34
|
+
that carried a batch. The expectation is Python rather than data so it can
|
|
35
|
+
say exactly which events, with the types the parser will produce, instead
|
|
36
|
+
of a second format to agree on.
|
|
37
|
+
|
|
38
|
+
The directory is walked recursively, so captures can be grouped by the
|
|
39
|
+
event kind they belong to, and the result is sorted by id, so a run reports
|
|
40
|
+
the same order whatever order the file system hands the files back in.
|
|
41
|
+
|
|
42
|
+
Args:
|
|
43
|
+
fixtures_dir: The directory the captures lie under.
|
|
44
|
+
extension: What the captures are named with, without the dot. A sender
|
|
45
|
+
whose captures are not JSON is kept in files named for what they
|
|
46
|
+
are.
|
|
47
|
+
|
|
48
|
+
Returns:
|
|
49
|
+
One case per capture, sorted by id.
|
|
50
|
+
|
|
51
|
+
Raises:
|
|
52
|
+
InvalidArgumentError: When a capture has no expectation file beside it,
|
|
53
|
+
or that file names no ``EXPECTED``. Either is a pair half-added,
|
|
54
|
+
and silently skipping it would leave a payload nothing ever checks.
|
|
55
|
+
"""
|
|
56
|
+
return sorted(
|
|
57
|
+
(_read(capture, fixtures_dir) for capture in fixtures_dir.rglob(f"*.{extension}")),
|
|
58
|
+
key=lambda case: case.id,
|
|
59
|
+
)
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
async def assert_parses(
|
|
63
|
+
parser: RequestParserInterface,
|
|
64
|
+
case: ParserCase,
|
|
65
|
+
*,
|
|
66
|
+
secret: str = "",
|
|
67
|
+
headers: Mapping[str, str] | None = None,
|
|
68
|
+
method: str = "POST",
|
|
69
|
+
) -> None:
|
|
70
|
+
"""Post ``case`` to ``parser`` and check it read what the case expects.
|
|
71
|
+
|
|
72
|
+
The request is built from the capture's bytes under
|
|
73
|
+
``Content-Type: application/json``, which is what the matchers of a JSON
|
|
74
|
+
sender's parser look for. A sender that signs its webhooks needs its
|
|
75
|
+
signature headers too, and the secret they were made with::
|
|
76
|
+
|
|
77
|
+
await assert_parses(AcmeParser(), case, secret=SECRET, headers=signed(case.payload))
|
|
78
|
+
|
|
79
|
+
Args:
|
|
80
|
+
parser: The parser under test.
|
|
81
|
+
case: The pair to drive it over.
|
|
82
|
+
secret: What the parser checks the sender's signature against.
|
|
83
|
+
headers: Headers to send alongside the content type β a signature, a
|
|
84
|
+
timestamp, whatever the sender puts on its webhooks. An entry named
|
|
85
|
+
``Content-Type`` replaces the default.
|
|
86
|
+
method: The method the sender posts with.
|
|
87
|
+
|
|
88
|
+
Raises:
|
|
89
|
+
AssertionError: When the parser read something other than
|
|
90
|
+
``case.expected``. Raised rather than asserted so the check holds
|
|
91
|
+
however the test suite is run, and carries both sides so the
|
|
92
|
+
difference is in the failure itself.
|
|
93
|
+
"""
|
|
94
|
+
request = ServerRequest(
|
|
95
|
+
method,
|
|
96
|
+
"/",
|
|
97
|
+
{"Content-Type": _JSON, **(headers or {})},
|
|
98
|
+
case.payload,
|
|
99
|
+
)
|
|
100
|
+
|
|
101
|
+
read = await parser.parse(request, secret)
|
|
102
|
+
if read != case.expected:
|
|
103
|
+
raise AssertionError(f'"{case.id}" was read as {read!r}, not {case.expected!r}.')
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def _read(capture: Path, fixtures_dir: Path) -> ParserCase:
|
|
107
|
+
"""Pair one capture with the expectation file beside it.
|
|
108
|
+
|
|
109
|
+
Args:
|
|
110
|
+
capture: The file holding the bytes the sender posted.
|
|
111
|
+
fixtures_dir: The directory the walk started from, which the case's id
|
|
112
|
+
is relative to.
|
|
113
|
+
|
|
114
|
+
Returns:
|
|
115
|
+
The capture and its expectation, as one case.
|
|
116
|
+
|
|
117
|
+
Raises:
|
|
118
|
+
InvalidArgumentError: When the expectation file is missing or names no
|
|
119
|
+
``EXPECTED``.
|
|
120
|
+
"""
|
|
121
|
+
expectation = capture.with_suffix(".py")
|
|
122
|
+
if not expectation.is_file():
|
|
123
|
+
raise InvalidArgumentError(
|
|
124
|
+
f'The fixture "{capture}" has no expectation file "{expectation}".'
|
|
125
|
+
)
|
|
126
|
+
|
|
127
|
+
# Run rather than import: a capture is grouped by what it is, not by what
|
|
128
|
+
# makes an importable module name, and nothing else reads these files.
|
|
129
|
+
named: dict[str, object] = runpy.run_path(str(expectation))
|
|
130
|
+
if _EXPECTATION not in named:
|
|
131
|
+
raise InvalidArgumentError(
|
|
132
|
+
f'The expectation file "{expectation}" defines no {_EXPECTATION}.'
|
|
133
|
+
)
|
|
134
|
+
|
|
135
|
+
return ParserCase(
|
|
136
|
+
capture.relative_to(fixtures_dir).as_posix(),
|
|
137
|
+
capture.read_bytes(),
|
|
138
|
+
# The expectation file states the type; a value of any other kind shows
|
|
139
|
+
# itself as the mismatch it is when the parser is driven over the case.
|
|
140
|
+
cast("RemoteEvent | list[RemoteEvent]", named[_EXPECTATION]),
|
|
141
|
+
)
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
"""One captured payload, and the events a parser must read out of it."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
from typing import final
|
|
7
|
+
|
|
8
|
+
from xtr_remote_event import RemoteEvent
|
|
9
|
+
|
|
10
|
+
__all__ = ["ParserCase"]
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
@final
|
|
14
|
+
@dataclass(frozen=True, slots=True)
|
|
15
|
+
class ParserCase:
|
|
16
|
+
"""A fixture pair as it was read off disk: what arrived, and what it must become.
|
|
17
|
+
|
|
18
|
+
A sender's payloads are the one thing a parser's test cannot invent β they
|
|
19
|
+
come from the sender, captured once and kept. So a case is a record of two
|
|
20
|
+
files rather than something assembled in a test, and it is frozen because
|
|
21
|
+
the files it came from are: a case changed half way through a run would
|
|
22
|
+
leave the failure naming a payload that was never on disk.
|
|
23
|
+
|
|
24
|
+
Attributes:
|
|
25
|
+
expected: What the parser must read out of ``payload`` β one event, or
|
|
26
|
+
every event when the capture carried a batch of them.
|
|
27
|
+
id: Where the capture lies under the directory it was found in, as a
|
|
28
|
+
slash-separated relative path, extension and all. It names the case
|
|
29
|
+
in the test report, so a failure says which file to look at.
|
|
30
|
+
payload: The bytes of the capture, exactly as they lie on disk. A
|
|
31
|
+
signature is made over the bytes that arrived, so nothing decodes,
|
|
32
|
+
re-encodes or reformats them on the way here.
|
|
33
|
+
"""
|
|
34
|
+
|
|
35
|
+
id: str
|
|
36
|
+
payload: bytes
|
|
37
|
+
expected: RemoteEvent | list[RemoteEvent]
|