Pre-compile topic filter regex, cache subscription patterns, docs clarify

Author: elijahr

docs/events.md

@@ -242,9 +242,9 @@ async def on_build_event(params: EventParams) -> None:
     print(f"Build: {params.payload}")
 ```
 
-The optional `topic_filter` applies an additional client-side filter using the same wildcard syntax as subscription patterns. Events that do not match the filter are silently dropped before reaching the handler.
+The optional `topic_filter` applies an additional client-side filter using the same wildcard syntax as subscription patterns. The filter is compiled once when the handler is registered and reused for every incoming event. Events that do not match the filter are silently dropped before reaching the handler.
 
-The client also tracks subscribed patterns internally. Events for topics that do not match any active subscription are dropped, even if the server sends them.
+The client also tracks subscribed patterns internally. Once a client has at least one active subscription, events whose topic does not match any subscribed pattern are dropped before reaching the handler, even if the server sends them. A client that never calls `subscribe_events` has no subscription patterns registered and will pass every event received from the server through to the handler, subject only to the optional `topic_filter`. If you want strict subscription-only delivery, subscribe explicitly.
 
 ### Unsubscribing
 

src/mcp/client/session.py

@@ -14,6 +14,7 @@
 from mcp.shared.context import RequestContext
 from mcp.shared.message import SessionMessage
 from mcp.shared.session import BaseSession, ProgressFnT, RequestResponder
+from mcp.shared.topic_patterns import pattern_to_regex
 from mcp.shared.version import SUPPORTED_PROTOCOL_VERSIONS
 
 DEFAULT_CLIENT_INFO = types.Implementation(name="mcp", version="0.1.0")
@@ -148,7 +149,11 @@ def __init__(
         self._experimental_features: ExperimentalClientFeatures | None = None
         self._event_handler: EventHandlerFnT | None = None
         self._event_topic_filter: str | None = None
+        self._event_topic_filter_regex: re.Pattern[str] | None = None
         self._subscribed_patterns: set[str] = set()
+        # Cache compiled regexes for subscription patterns to avoid
+        # recompiling on every incoming event.
+        self._subscription_regex_cache: dict[str, re.Pattern[str]] = {}
 
         # Experimental: Task handlers (use defaults if not provided)
         self._task_handlers = experimental_task_handlers or ExperimentalTaskHandlers()
@@ -239,6 +244,8 @@ async def subscribe_events(self, topics: list[str]) -> types.EventSubscribeResul
         )
         for sub in result.subscribed:
             self._subscribed_patterns.add(sub.pattern)
+            if sub.pattern not in self._subscription_regex_cache:
+                self._subscription_regex_cache[sub.pattern] = pattern_to_regex(sub.pattern)
         return result
 
     async def unsubscribe_events(self, topics: list[str]) -> types.EventUnsubscribeResult:
@@ -253,6 +260,7 @@ async def unsubscribe_events(self, topics: list[str]) -> types.EventUnsubscribeR
         )
         for pattern in result.unsubscribed:
             self._subscribed_patterns.discard(pattern)
+            self._subscription_regex_cache.pop(pattern, None)
         return result
 
     async def list_events(self) -> types.EventListResult:
@@ -268,9 +276,17 @@ def set_event_handler(
         *,
         topic_filter: str | None = None,
     ) -> None:
-        """Register a callback for incoming event notifications."""
+        """Register a callback for incoming event notifications.
+
+        If *topic_filter* is provided, it is compiled once here and the
+        cached regex is reused for every incoming event. The filter uses
+        the same MQTT-style wildcard syntax as subscription patterns
+        (``+`` for a single segment, ``#`` as a trailing multi-segment
+        wildcard).
+        """
         self._event_handler = handler
         self._event_topic_filter = topic_filter
+        self._event_topic_filter_regex = pattern_to_regex(topic_filter) if topic_filter is not None else None
 
     def on_event(self, topic_filter: str | None = None):
         """Decorator for registering an event handler."""
@@ -282,58 +298,43 @@ def decorator(fn: EventHandlerFnT) -> EventHandlerFnT:
         return decorator
 
     def _topic_matches_subscriptions(self, topic: str) -> bool:
-        """Check if a topic matches any of our subscribed patterns."""
+        """Check if *topic* matches any of our subscribed patterns.
+
+        Compiled regexes are cached per subscription pattern so incoming
+        events do not pay a recompile cost on every match attempt.
+        """
         for pattern in self._subscribed_patterns:
-            parts = pattern.split("/")
-            regex_parts: list[str] = []
-            for i, part in enumerate(parts):
-                if part == "#":
-                    if regex_parts:
-                        regex = "^" + "/".join(regex_parts) + "(/.*)?$"
-                    else:
-                        regex = "^.*$"
-                    if re.match(regex, topic):
-                        return True
-                    break
-                elif part == "+":
-                    regex_parts.append("[^/]+")
-                else:
-                    regex_parts.append(re.escape(part))
-            else:
-                regex = "^" + "/".join(regex_parts) + "$"
-                if re.match(regex, topic):
-                    return True
+            regex = self._subscription_regex_cache.get(pattern)
+            if regex is None:
+                regex = pattern_to_regex(pattern)
+                self._subscription_regex_cache[pattern] = regex
+            if regex.match(topic):
+                return True
         return False
 
     async def _handle_event(self, params: types.EventParams) -> None:
-        """Dispatch an incoming event to the registered handler."""
+        """Dispatch an incoming event to the registered handler.
+
+        Filtering order:
+
+        1. If no handler is registered, drop the event.
+        2. If the client has any active subscriptions, the topic must
+           match at least one of them. Events for unsubscribed topics
+           are dropped. (A client with zero subscriptions accepts any
+           topic the server chooses to deliver; this is the "pass
+           through" fallback documented in ``docs/events.md``.)
+        3. If an additional ``topic_filter`` was provided to
+           ``set_event_handler``, the topic must also match that
+           filter.
+        """
         if self._event_handler is None:
             return
 
         if self._subscribed_patterns and not self._topic_matches_subscriptions(params.topic):
             return
 
-        if self._event_topic_filter is not None:
-            parts = self._event_topic_filter.split("/")
-            regex_parts: list[str] = []
-            matched = False
-            for i, part in enumerate(parts):
-                if part == "#":
-                    if regex_parts:
-                        regex = "^" + "/".join(regex_parts) + "(/.*)?$"
-                    else:
-                        regex = "^.*$"
-                    matched = bool(re.match(regex, params.topic))
-                    break
-                elif part == "+":
-                    regex_parts.append("[^/]+")
-                else:
-                    regex_parts.append(re.escape(part))
-            else:
-                regex = "^" + "/".join(regex_parts) + "$"
-                matched = bool(re.match(regex, params.topic))
-            if not matched:
-                return
+        if self._event_topic_filter_regex is not None and not self._event_topic_filter_regex.match(params.topic):
+            return
 
         await self._event_handler(params)
 

src/mcp/server/events.py

@@ -15,35 +15,10 @@
 import re
 from datetime import datetime, timezone
 
+from mcp.shared.topic_patterns import pattern_to_regex as _pattern_to_regex
 from mcp.types import RetainedEvent
 
 
-def _pattern_to_regex(pattern: str) -> re.Pattern[str]:
-    """Convert an MQTT-style topic pattern to a compiled regex.
-
-    ``+`` becomes a single-segment match, ``#`` becomes a greedy
-    multi-segment match (only valid as the final segment).
-    """
-    parts = pattern.split("/")
-    regex_parts: list[str] = []
-    for i, part in enumerate(parts):
-        if part == "#":
-            if i != len(parts) - 1:
-                raise ValueError("'#' wildcard is only valid as the last segment")
-            # # matches zero or more trailing segments.
-            # If preceding segments exist, the / before # is optional
-            # so "myapp/#" matches both "myapp" and "myapp/anything".
-            # If # is the sole segment, it matches everything.
-            if regex_parts:
-                return re.compile("^" + "/".join(regex_parts) + "(/.*)?$")
-            else:
-                return re.compile("^.*$")
-        elif part == "+":
-            regex_parts.append("[^/]+")
-        else:
-            regex_parts.append(re.escape(part))
-    return re.compile("^" + "/".join(regex_parts) + "$")
-
 
 class SubscriptionRegistry:
     """Thread-safe registry mapping session IDs to topic subscription patterns.

src/mcp/shared/topic_patterns.py

@@ -0,0 +1,41 @@
+"""Shared helpers for MQTT-style topic pattern matching.
+
+Both the client (for subscription filtering) and the server (for the
+subscription registry and retained-event store) need to compile MQTT-style
+topic patterns into regular expressions. Keeping the implementation here
+avoids a client -> server import and guarantees identical semantics on both
+sides of the protocol.
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = ["pattern_to_regex"]
+
+
+def pattern_to_regex(pattern: str) -> re.Pattern[str]:
+    """Convert an MQTT-style topic pattern to a compiled regex.
+
+    ``+`` becomes a single-segment match, ``#`` becomes a greedy
+    multi-segment match (only valid as the final segment).
+    """
+    parts = pattern.split("/")
+    regex_parts: list[str] = []
+    for i, part in enumerate(parts):
+        if part == "#":
+            if i != len(parts) - 1:
+                raise ValueError("'#' wildcard is only valid as the last segment")
+            # # matches zero or more trailing segments.
+            # If preceding segments exist, the / before # is optional
+            # so "myapp/#" matches both "myapp" and "myapp/anything".
+            # If # is the sole segment, it matches everything.
+            if regex_parts:
+                return re.compile("^" + "/".join(regex_parts) + "(/.*)?$")
+            else:
+                return re.compile("^.*$")
+        elif part == "+":
+            regex_parts.append("[^/]+")
+        else:
+            regex_parts.append(re.escape(part))
+    return re.compile("^" + "/".join(regex_parts) + "$")