[tor-commits] [stem/master] Method to get descriptor of relay we're downloading from

[atagar at torproject.org]

commit 7b05dec592452ff57dbf79a2c20261f18ca51c30
Author: Damian Johnson <atagar at torproject.org>
Date:   Mon Apr 23 10:11:58 2018 -0700

    Method to get descriptor of relay we're downloading from
    
    Besides using this module to download descriptors I'd like to use it for a
    relay health check. For that I'd like to get the descriptor of the relay
    we're downloading from. The DirPort protocol surfaced this but Stem didn't,
    so adding a little function for it.
---
 docs/change_log.rst       |  1 +
 stem/descriptor/remote.py | 36 +++++++++++++++++++++++++++++++++++-
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/docs/change_log.rst b/docs/change_log.rst
index b6121982..18005e1e 100644
--- a/docs/change_log.rst
+++ b/docs/change_log.rst
@@ -59,6 +59,7 @@ The following are only available within Stem's `git repository
   * Added zstd and lzma compression support (:spec:`1cb56af`)
   * Added server descriptor's new is_hidden_service_dir attribute
   * Don't retry downloading descriptors when we've timed out
+  * Added :func:`~stem.descriptor.remote.their_server_descriptor`
   * Added the reply_headers attribute to :class:`~stem.descriptor.remote.Query`
   * Supplying a User-Agent when downloading descriptors.
   * Reduced maximum descriptors fetched by the remote module to match tor's new limit (:trac:`24743`)
diff --git a/stem/descriptor/remote.py b/stem/descriptor/remote.py
index eb9c7b62..c191b02a 100644
--- a/stem/descriptor/remote.py
+++ b/stem/descriptor/remote.py
@@ -45,6 +45,7 @@ content. For example...
 ::
 
   get_instance - Provides a singleton DescriptorDownloader used for...
+    |- their_server_descriptor - provides the server descriptor of the relay we download from
     |- get_server_descriptors - provides present server descriptors
     |- get_extrainfo_descriptors - provides present extrainfo descriptors
     +- get_consensus - provides the present consensus or router status entries
@@ -63,6 +64,7 @@ content. For example...
 
   DescriptorDownloader - Configurable class for issuing queries
     |- use_directory_mirrors - use directory mirrors to download future descriptors
+    |- their_server_descriptor - provides the server descriptor of the relay we download from
     |- get_server_descriptors - provides present server descriptors
     |- get_extrainfo_descriptors - provides present extrainfo descriptors
     |- get_consensus - provides the present consensus or router status entries
@@ -201,6 +203,21 @@ def get_instance():
   return SINGLETON_DOWNLOADER
 
 
+def their_server_descriptor(**query_args):
+  """
+  Provides the server descriptor of the relay we're downloading from.
+
+  .. versionadded:: 1.7.0
+
+  :param query_args: additional arguments for the
+    :class:`~stem.descriptor.remote.Query` constructor
+
+  :returns: :class:`~stem.descriptor.remote.Query` for the server descriptors
+  """
+
+  return get_instance().their_server_descriptor(**query_args)
+
+
 def get_server_descriptors(fingerprints = None, **query_args):
   """
   Shorthand for
@@ -247,9 +264,12 @@ def _download_from_orport(endpoint, resource):
   :returns: **str** with the descirptor data
 
   :raises:
+    * :class:`stem.SocketError` if unable to establish a connection
   """
 
-  with stem.client.Relay.connect(endpoint.address, endpoint.port, endpoint.link_protocols) as relay:
+  link_protocol = endpoint.link_protocols if endpoint.link_protocols else [3]
+
+  with stem.client.Relay.connect(endpoint.address, endpoint.port, link_protocol) as relay:
     with relay.create_circuit() as circ:
       circ.send('RELAY_BEGIN_DIR', stream_id = 1)
       return circ.send('RELAY_DATA', resource, stream_id = 1).data
@@ -694,6 +714,20 @@ class DescriptorDownloader(object):
 
     return consensus
 
+  def their_server_descriptor(self, **query_args):
+    """
+    Provides the server descriptor of the relay we're downloading from.
+
+    .. versionadded:: 1.7.0
+
+    :param query_args: additional arguments for the
+      :class:`~stem.descriptor.remote.Query` constructor
+
+    :returns: :class:`~stem.descriptor.remote.Query` for the server descriptors
+    """
+
+    return self.query('/tor/server/authority', **query_args)
+
   def get_server_descriptors(self, fingerprints = None, **query_args):
     """
     Provides the server descriptors with the given fingerprints. If no