Coverage for src / zmqtt / _internal / topic_matching.py: 97%
36 statements
« prev ^ index » next coverage.py v7.13.4, created at 2026-11-12 08:49 +0000
« prev ^ index » next coverage.py v7.13.4, created at 2026-11-12 08:49 +0000
1from typing import Final
3# Group-less decorator prefixes the broker strips before delivery (unlike $SYS,
4# which it delivers on as-is). Extend via MQTTClient(stripped_prefixes=...).
5_DEFAULT_STRIPPED_PREFIXES: Final = ("$queue", "$exclusive")
8def topic_matches(
9 topic_filter: str,
10 topic: str,
11 *,
12 stripped_prefixes: tuple[str, ...] = _DEFAULT_STRIPPED_PREFIXES,
13) -> bool:
14 """Return whether an MQTT topic filter matches a published topic.
16 MQTT wildcards (``+`` and ``#``), shared subscriptions
17 (``$share/<group>/...``), and broker-stripped decorator prefixes are
18 supported. By default, ``$queue`` and ``$exclusive`` are treated as
19 stripped prefixes; pass ``stripped_prefixes`` to configure another broker.
20 """
21 actual_filter = _shared_filter_to_actual(topic_filter, stripped_prefixes)
22 return _topic_matches(actual_filter, topic)
25def _shared_filter_to_actual(
26 filter_: str,
27 stripped_prefixes: tuple[str, ...],
28) -> str:
29 """Return the filter the broker matches incoming PUBLISH topics against.
31 A shared/decorator subscription is sent with a prefix the broker strips before
32 delivery, so matching must run against the filter *without* it:
34 - ``$share/<group>/<filter>`` — MQTT 5 shared subscription (the only form that
35 carries a group), handled here directly;
36 - each entry in ``stripped_prefixes`` — a group-less decorator such as
37 ``$queue/<filter>`` or ``$exclusive/<filter>``.
39 Anything else — a plain filter, or a real namespace like ``$SYS/#`` the broker
40 delivers on unchanged — is returned untouched. The allowlist fails safe: an
41 unrecognised prefix is left as-is, so a mismatch surfaces as a loud
42 "No subscriber" rather than a silent mis-route.
43 """
44 if filter_.startswith("$share/"):
45 _, separator, actual_filter = filter_.removeprefix("$share/").partition("/")
46 if separator:
47 return actual_filter
48 for prefix in stripped_prefixes:
49 if filter_.startswith(f"{prefix}/"):
50 return filter_.split("/", 1)[1]
51 return filter_
54def _topic_matches(actual_filter: str, topic: str) -> bool:
55 if topic.startswith("$") != actual_filter.startswith("$"):
56 return False
57 return _match_parts(actual_filter.split("/"), topic.split("/"))
60def _match_parts(fparts: list[str], tparts: list[str]) -> bool:
61 if not fparts:
62 return not tparts
63 if fparts[0] == "#":
64 return True
65 if not tparts:
66 return False
67 if fparts[0] != "+" and fparts[0] != tparts[0]:
68 return False
69 return _match_parts(fparts[1:], tparts[1:])
72def _segment_rank(seg: str) -> int:
73 if seg == "#":
74 return 2
75 if seg == "+":
76 return 1
77 return 0
80def _filter_specificity(actual_filter: str) -> tuple[int, ...]:
81 return tuple(_segment_rank(s) for s in actual_filter.split("/"))