feat(core): add support for watch event zxids

ZooKeeper 3.9.0 began including the zxid responsible for a watch
event in the response header.  This adds support for that by
plumbing the information through to the WatchedEvent.  The
documentation and field name is based on the text in the
ZooKeeper java client.

Author: jeblair

kazoo/protocol/connection.py

@@ -379,7 +379,7 @@ def _find_persistent_recursive_watchers(self, path):
             )
         return watchers
 
-    def _read_watch_event(self, buffer, offset):
+    def _read_watch_event(self, buffer, offset, zxid):
         client = self.client
         watch, offset = Watch.deserialize(buffer, offset)
         path = watch.path
@@ -405,7 +405,8 @@ def _read_watch_event(self, buffer, offset):
 
         # Strip the chroot if needed
         path = client.unchroot(path)
-        ev = WatchedEvent(EVENT_TYPE_MAP[watch.type], client._state, path)
+        ev = WatchedEvent(EVENT_TYPE_MAP[watch.type], client._state, path,
+                          zxid)
 
         # Last check to ignore watches if we've been stopped
         if client._stopped.is_set():
@@ -520,7 +521,7 @@ def _read_socket(self, read_timeout):
             else:
                 async_object.set(True)
         elif header.xid == WATCH_XID:
-            self._read_watch_event(buffer, offset)
+            self._read_watch_event(buffer, offset, header.zxid)
         else:
             self.logger.log(BLATHER, "Reading for header %r", header)
 

kazoo/protocol/states.py

@@ -117,7 +117,8 @@ class EventType(object):
 }
 
 
-class WatchedEvent(namedtuple("WatchedEvent", ("type", "state", "path"))):
+class WatchedEvent(namedtuple("WatchedEvent",
+                              ("type", "state", "path", "zxid"))):
     """A change on ZooKeeper that a Watcher is able to respond to.
 
     The :class:`WatchedEvent` includes exactly what happened, the
@@ -138,8 +139,23 @@ class WatchedEvent(namedtuple("WatchedEvent", ("type", "state", "path"))):
 
         The path of the node for the watch event.
 
+    .. attribute:: zxid
+
+        The zxid of the transaction that triggered this watch if it is
+        of one of the following types:
+
+        * EventType.CREATED
+        * EventType.DELETED
+        * EventType.CHANGED
+        * EventType.CHILD
+
+        Otherwise, returns WatchedEvent.NO_ZXID. Note that NO_ZXID is also
+        returned by old servers that do not support this feature.
+
     """
 
+    NO_ZXID = -1
+
 
 class Callback(namedtuple("Callback", ("type", "func", "args"))):
     """A callback that is handed to a handler for dispatch

kazoo/tests/test_client.py

@@ -1305,6 +1305,24 @@ def test_invalid_remove_all_watch_values(self):
         with pytest.raises(ValueError):
             client.remove_all_watches("/a", 42)
 
+    def test_watch_zxid(self):
+        self._require_zk_version(3, 9)
+        nodepath = "/" + uuid.uuid4().hex
+        event = self.client.handler.event_object()
+
+        def w(watch_event):
+            assert watch_event.path == nodepath
+            assert watch_event.zxid > -1
+            event.set()
+
+        exists = self.client.exists(nodepath, watch=w)
+        assert exists is None
+
+        self.client.create(nodepath, ephemeral=True)
+
+        event.wait(1)
+        assert event.is_set() is True
+
 
 class TestSSLClient(KazooTestCase):
     def setUp(self):