Add support for Network Tomography

This commit adds support for Consul's network tomography. The
tomography is a collection of nodes' coordinates and RTT
between the nodes.

See also: [Network Coordinates](https://www.consul.io/docs/internals/coordinates.html)

Author: greenpau

consulate/api/__init__.py

@@ -7,6 +7,7 @@
 from consulate.api.catalog import Catalog
 from consulate.api.event import Event
 from consulate.api.health import Health
+from consulate.api.coordinate import Coordinate
 from consulate.api.kv import KV
 from consulate.api.lock import Lock
 from consulate.api.session import Session

consulate/api/coordinate.py

@@ -0,0 +1,63 @@
+"""
+Consul Coordinate Endpoint Access
+
+"""
+from consulate.api import base
+from math import sqrt
+
+class Coordinate(base.Endpoint):
+    """Used to query node coordinates.
+    """
+
+    def node(self, node_id):
+        """Return coordinates for the given node.
+
+        :param str node_id: The node ID
+        :rtype: dict
+
+        """
+        return self._get(['node', node_id])
+
+    def nodes(self):
+        """Return coordinates for the current datacenter.
+
+        :rtype: list
+
+        """
+        return self._get_list(['nodes'])
+
+    def rtt(self, src, dst):
+        """Calculated RTT between two node coordinates.
+
+        :param dict src
+        :param dict dst
+        :rtype float
+
+        """
+
+        if not isinstance(src, (dict)):
+            raise ValueError('coordinate object must be a dictionary')
+        if not isinstance(dst, (dict)):
+            raise ValueError('coordinate object must be a dictionary')
+        if 'Coord' not in src:
+            raise ValueError('coordinate object has no Coord key')
+        if 'Coord' not in dst:
+            raise ValueError('coordinate object has no Coord key')
+
+        src_coord = src['Coord']
+        dst_coord = dst['Coord']
+
+        if len(src_coord.get('Vec')) != len(dst_coord.get('Vec')):
+            raise ValueError('coordinate objects are not compatible due to different length')
+
+        sumsq = 0.0
+        for i in xrange(len(src_coord.get('Vec'))):
+            diff = src_coord.get('Vec')[i] - dst_coord.get('Vec')[i]
+            sumsq += diff * diff
+
+        rtt = sqrt(sumsq) + src_coord.get('Height') + dst_coord.get('Height')
+        adjusted = rtt + src_coord.get('Adjustment') + dst_coord.get('Adjustment')
+        if adjusted > 0.0:
+            rtt = adjusted
+
+        return rtt * 1000

consulate/client.py

@@ -54,6 +54,7 @@ def __init__(self,
         self._catalog = api.Catalog(base_uri, self._adapter, datacenter, token)
         self._event = api.Event(base_uri, self._adapter, datacenter, token)
         self._health = api.Health(base_uri, self._adapter, datacenter, token)
+        self._coordinate = api.Coordinate(base_uri, self._adapter, datacenter, token)
         self._kv = api.KV(base_uri, self._adapter, datacenter, token)
         self._session = api.Session(base_uri, self._adapter, datacenter, token)
         self._status = api.Status(base_uri, self._adapter, datacenter, token)
@@ -110,6 +111,16 @@ def health(self):
         """
         return self._health
 
+    @property
+    def coordinate(self):
+        """Access the Consul
+        `Coordinate <https://www.consul.io/api/coordinate.html#read-lan-coordinates-for-a-node>`_ API
+
+        :rtype: :py:class:`consulate.api.coordinate.Coordinate`
+
+        """
+        return self._coordinate
+
     @property
     def kv(self):
         """Access the Consul

docs/coordinate.rst

@@ -0,0 +1,28 @@
+Coordinate
+==========
+
+The :py:class:`Coordinate <consulate.api.coordinate.Coordinate>` class provides
+access to Consul's Network Tomography.
+
+.. autoclass:: consulate.api.coordinate.Coordinate
+       :members:
+       :special-members:
+
+Usage
+-----
+
+This code fetches the coordinates for the nodes in ``ny1`` cluster, and then
+calculates the RTT between two random nodes.
+
+.. code:: python
+
+    import consulate
+
+    # Create a new instance of a consulate session
+    session = consulate.Consul()
+
+    # Get coordinates for all notes in ny1 cluster
+    coordinates = session.coordinate.nodes('ny1')
+
+    # Calculate RTT between two nodes
+    session.coordinate.rtt(coordinates[0], coordinates[1])

tests/api_tests.py

@@ -25,11 +25,12 @@ class ConsulTests(unittest.TestCase):
     @mock.patch('consulate.api.Catalog')
     @mock.patch('consulate.api.KV')
     @mock.patch('consulate.api.Health')
+    @mock.patch('consulate.api.Coordinate')
     @mock.patch('consulate.api.ACL')
     @mock.patch('consulate.api.Event')
     @mock.patch('consulate.api.Session')
     @mock.patch('consulate.api.Status')
-    def setUp(self, status, session, event, acl, health, kv, catalog, agent,
+    def setUp(self, status, session, event, acl, health, coordinate, kv, catalog, agent,
               adapter):
         self.host = '127.0.0.1'
         self.port = 8500
@@ -43,6 +44,7 @@ def setUp(self, status, session, event, acl, health, kv, catalog, agent,
         self.event = event
         self.kv = kv
         self.health = health
+        self.coordinate = coordinate
         self.session = session
         self.status = status
 
@@ -93,6 +95,11 @@ def test_health_initialization(self):
             self.health.called_once_with(self.base_uri, self.adapter, self.dc,
                                          self.token))
 
+    def test_coordinate_initialization(self):
+        self.assertTrue(
+            self.coordinate.called_once_with(self.base_uri, self.adapter, self.dc,
+                                         self.token))
+
     def test_session_initialization(self):
         self.assertTrue(
             self.session.called_once_with(self.base_uri, self.adapter, self.dc,
@@ -118,6 +125,9 @@ def test_event_property(self):
     def test_health_property(self):
         self.assertEqual(self.consul.health, self.consul._health)
 
+    def test_coordinate_property(self):
+        self.assertEqual(self.consul.coordinate, self.consul._coordinate)
+
     def test_kv_property(self):
         self.assertEqual(self.consul.kv, self.consul._kv)
 

tests/coordinate_tests.py

@@ -0,0 +1,6 @@
+from . import base
+
+class TestCoordinate(base.TestCase):
+    def test_coordinate(self):
+        coordinates = self.consul.coordinate.nodes()
+        self.assertIsInstance(coordinates, list)