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.
Files changed (56) hide show
  1. xtr_webhook/.agents/skills/xtr-webhook/SKILL.md +350 -0
  2. xtr_webhook/.agents/skills/xtr-webhook/references/signature-formats.md +189 -0
  3. xtr_webhook/__init__.py +10 -0
  4. xtr_webhook/_endpoint_paths.py +22 -0
  5. xtr_webhook/_standard_webhooks_signature.py +76 -0
  6. xtr_webhook/bundle/__init__.py +15 -0
  7. xtr_webhook/bundle/_routed_parsers.py +70 -0
  8. xtr_webhook/bundle/no_private_network_config.py +59 -0
  9. xtr_webhook/bundle/route_config.py +34 -0
  10. xtr_webhook/bundle/webhook_bundle.py +262 -0
  11. xtr_webhook/bundle/webhook_config.py +80 -0
  12. xtr_webhook/client/__init__.py +23 -0
  13. xtr_webhook/client/abstract_request_parser.py +248 -0
  14. xtr_webhook/client/request_parser.py +272 -0
  15. xtr_webhook/client/request_parser_interface.py +90 -0
  16. xtr_webhook/controller/__init__.py +12 -0
  17. xtr_webhook/controller/_built_parsers.py +65 -0
  18. xtr_webhook/controller/webhook_controller.py +140 -0
  19. xtr_webhook/exception/__init__.py +25 -0
  20. xtr_webhook/exception/delivery_error.py +38 -0
  21. xtr_webhook/exception/invalid_argument_error.py +18 -0
  22. xtr_webhook/exception/logic_error.py +15 -0
  23. xtr_webhook/exception/reject_webhook_error.py +52 -0
  24. xtr_webhook/exception/webhook_error.py +9 -0
  25. xtr_webhook/exception/webhook_runtime_error.py +16 -0
  26. xtr_webhook/messenger/__init__.py +14 -0
  27. xtr_webhook/messenger/send_webhook_handler.py +49 -0
  28. xtr_webhook/messenger/send_webhook_message.py +36 -0
  29. xtr_webhook/py.typed +0 -0
  30. xtr_webhook/recipe/__init__.py +18 -0
  31. xtr_webhook/recipe/files/config/routes/webhook.py.tmpl +25 -0
  32. xtr_webhook/recipe/files/config/webhook.py.tmpl +33 -0
  33. xtr_webhook/recipe/manifest.toml +35 -0
  34. xtr_webhook/routing/__init__.py +11 -0
  35. xtr_webhook/routing/_endpoints.py +38 -0
  36. xtr_webhook/routing/webhook_route_loader.py +31 -0
  37. xtr_webhook/server/__init__.py +39 -0
  38. xtr_webhook/server/header_signature_configurator.py +128 -0
  39. xtr_webhook/server/headers_configurator.py +92 -0
  40. xtr_webhook/server/json_body_configurator.py +80 -0
  41. xtr_webhook/server/json_payload_serializer.py +45 -0
  42. xtr_webhook/server/outgoing_request.py +35 -0
  43. xtr_webhook/server/payload_serializer_interface.py +34 -0
  44. xtr_webhook/server/request_configurator_interface.py +39 -0
  45. xtr_webhook/server/signature_format.py +65 -0
  46. xtr_webhook/server/transport.py +106 -0
  47. xtr_webhook/server/transport_interface.py +40 -0
  48. xtr_webhook/subscriber.py +41 -0
  49. xtr_webhook/testing/__init__.py +18 -0
  50. xtr_webhook/testing/_parser_cases.py +141 -0
  51. xtr_webhook/testing/parser_case.py +37 -0
  52. xtr_webhook-4.0.2.dist-info/METADATA +704 -0
  53. xtr_webhook-4.0.2.dist-info/RECORD +56 -0
  54. xtr_webhook-4.0.2.dist-info/WHEEL +4 -0
  55. xtr_webhook-4.0.2.dist-info/entry_points.txt +6 -0
  56. 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]