Add BOOKMARK event support to SharedInformer

Co-authored-by: brendandburns <5751682+brendandburns@users.noreply.github.com>

Author: Copilot

kubernetes/informer/__init__.py

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 from .cache import ObjectCache, _meta_namespace_key
-from .informer import SharedInformer, ADDED, MODIFIED, DELETED, ERROR
+from .informer import SharedInformer, ADDED, MODIFIED, DELETED, BOOKMARK, ERROR
 
 __all__ = [
     "ObjectCache",
@@ -22,5 +22,6 @@
     "ADDED",
     "MODIFIED",
     "DELETED",
+    "BOOKMARK",
     "ERROR",
 ]

kubernetes/informer/informer.py

@@ -35,6 +35,7 @@
 ADDED = "ADDED"
 MODIFIED = "MODIFIED"
 DELETED = "DELETED"
+BOOKMARK = "BOOKMARK"
 ERROR = "ERROR"
 
 
@@ -83,7 +84,7 @@ def __init__(
         self._field_selector = field_selector
 
         self._cache = ObjectCache(key_func=key_func)
-        self._handlers = {ADDED: [], MODIFIED: [], DELETED: [], ERROR: []}
+        self._handlers = {ADDED: [], MODIFIED: [], DELETED: [], BOOKMARK: [], ERROR: []}
         self._handler_lock = threading.Lock()
 
         self._watch = None
@@ -105,8 +106,8 @@ def add_event_handler(self, event_type, handler):
         Parameters
         ----------
         event_type:
-            One of :data:`ADDED`, :data:`MODIFIED`, :data:`DELETED` or
-            :data:`ERROR`.
+            One of :data:`ADDED`, :data:`MODIFIED`, :data:`DELETED`,
+            :data:`BOOKMARK` or :data:`ERROR`.
         handler:
             Callable invoked with the event object (or the raw exception for
             ERROR events).
@@ -227,6 +228,11 @@ def _run_loop(self):
                     elif evt_type == DELETED:
                         self._cache._remove(obj)
                         self._fire(DELETED, obj)
+                    elif evt_type == BOOKMARK:
+                        # BOOKMARK events carry an updated resource version but
+                        # no object state change; the Watch instance already
+                        # records the new resource_version internally.
+                        self._fire(BOOKMARK, event.get("raw_object", obj))
                     elif evt_type == ERROR:
                         self._fire(ERROR, obj)
                     # Periodic resync: re-list and fire MODIFIED for all cached objects

kubernetes/test/test_informer.py

@@ -22,6 +22,7 @@
 from kubernetes.informer.cache import ObjectCache, _meta_namespace_key
 from kubernetes.informer.informer import (
     ADDED,
+    BOOKMARK,
     DELETED,
     ERROR,
     MODIFIED,
@@ -269,6 +270,7 @@ def fake_stream(func, **kw):
         cached = informer.cache.get_by_key("default/mod-pod")
         self.assertIs(cached, pod_v2)
 
+
     def test_start_is_idempotent(self):
         list_func = MagicMock()
         list_resp = MagicMock()
@@ -289,6 +291,75 @@ def test_start_is_idempotent(self):
             self.assertIs(informer._thread, first_thread)
             informer.stop()
 
+    def test_bookmark_event_fires_handler(self):
+        bookmark_obj = {"metadata": {"resourceVersion": "42"}}
+        events = [
+            {"type": "BOOKMARK", "object": bookmark_obj, "raw_object": bookmark_obj},
+        ]
+
+        received = []
+        list_func = MagicMock()
+        list_resp = MagicMock()
+        list_resp.items = []
+        list_resp.metadata = MagicMock(resource_version="1")
+        list_func.return_value = list_resp
+
+        informer = SharedInformer(list_func=list_func)
+        informer.add_event_handler(BOOKMARK, received.append)
+
+        with patch("kubernetes.informer.informer.Watch") as MockWatch:
+            mock_w = MagicMock()
+
+            def fake_stream(func, **kw):
+                yield from events
+                informer._stop_event.set()
+
+            mock_w.stream.side_effect = fake_stream
+            MockWatch.return_value = mock_w
+
+            informer.start()
+            informer._thread.join(timeout=3)
+
+        self.assertEqual(len(received), 1)
+        self.assertEqual(received[0], bookmark_obj)
+        # Cache should be unchanged (BOOKMARK does not add/modify/delete objects)
+        self.assertEqual(informer.cache.list(), [])
+
+    def test_bookmark_event_does_not_modify_cache(self):
+        pod = _make_pod("default", "stable-pod")
+        bookmark_obj = {"metadata": {"resourceVersion": "99"}}
+        events = [
+            {"type": "ADDED", "object": pod},
+            {"type": "BOOKMARK", "object": bookmark_obj, "raw_object": bookmark_obj},
+        ]
+
+        list_func = MagicMock()
+        list_resp = MagicMock()
+        list_resp.items = []
+        list_resp.metadata = MagicMock(resource_version="1")
+        list_func.return_value = list_resp
+
+        informer = SharedInformer(list_func=list_func)
+
+        with patch("kubernetes.informer.informer.Watch") as MockWatch:
+            mock_w = MagicMock()
+
+            def fake_stream(func, **kw):
+                yield from events
+                informer._stop_event.set()
+
+            mock_w.stream.side_effect = fake_stream
+            MockWatch.return_value = mock_w
+
+            informer.start()
+            informer._thread.join(timeout=3)
+
+        # BOOKMARK must not have altered the cache content
+        cached = informer.cache.list()
+        self.assertEqual(len(cached), 1)
+        self.assertIs(cached[0], pod)
+
 
 if __name__ == "__main__":
     unittest.main()
+