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

1from typing import Final 

2 

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") 

6 

7 

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. 

15 

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) 

23 

24 

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. 

30 

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: 

33 

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>``. 

38 

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_ 

52 

53 

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("/")) 

58 

59 

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:]) 

70 

71 

72def _segment_rank(seg: str) -> int: 

73 if seg == "#": 

74 return 2 

75 if seg == "+": 

76 return 1 

77 return 0 

78 

79 

80def _filter_specificity(actual_filter: str) -> tuple[int, ...]: 

81 return tuple(_segment_rank(s) for s in actual_filter.split("/"))