[tor-commits] [stem/master] Add is_valid() and is_fresh() methods to the conensus

[atagar at torproject.org]

commit 49c6a17a0a7c5c860f0fe59f6d2c18d9e37025a5
Author: Damian Johnson <atagar at torproject.org>
Date:   Sat Nov 17 16:41:41 2018 -0800

    Add is_valid() and is_fresh() methods to the conensus
    
    Nice idea from Iain...
    
      https://trac.torproject.org/projects/tor/ticket/28448
---
 docs/change_log.rst                               |  1 +
 stem/descriptor/networkstatus.py                  | 29 +++++++++++++++++++++++
 test/unit/descriptor/networkstatus/document_v3.py | 28 ++++++++++++++++++++++
 3 files changed, 58 insertions(+)

diff --git a/docs/change_log.rst b/docs/change_log.rst
index a0d89db7..0c427784 100644
--- a/docs/change_log.rst
+++ b/docs/change_log.rst
@@ -53,6 +53,7 @@ The following are only available within Stem's `git repository
 
   * Added :func:`~stem.descriptor.Descriptor.type_annotation` method (:trac:`28397`)
   * Added the **hash_type** and **encoding** arguments to `ServerDescriptor <api/descriptor/server_descriptor.html#stem.descriptor.server_descriptor.ServerDescriptor.digest>`_ and `ExtraInfo's <api/descriptor/extrainfo_descriptor.html#stem.descriptor.extrainfo_descriptor.ExtraInfoDescriptor.digest>`_ digest methods (:trac:`28398`)
+  * Added :func:`~stem.descriptor.networkstatus.NetworkStatusDocumentV3.is_valid` and :func:`~stem.descriptor.networkstatus.NetworkStatusDocumentV3.is_fresh` methods (:trac:`28448`)
   * DescriptorDownloader crashed if **use_mirrors** is set (:trac:`28393`)
   * Don't download from Serge, a bridge authority that frequently timeout
 
diff --git a/stem/descriptor/networkstatus.py b/stem/descriptor/networkstatus.py
index 02dd55fb..6c14097f 100644
--- a/stem/descriptor/networkstatus.py
+++ b/stem/descriptor/networkstatus.py
@@ -55,6 +55,7 @@ For more information see :func:`~stem.descriptor.__init__.DocumentHandler`...
 """
 
 import collections
+import datetime
 import hashlib
 import io
 
@@ -1102,6 +1103,34 @@ class NetworkStatusDocumentV3(NetworkStatusDocument):
 
       return TypeAnnotation('network-status-microdesc-consensus-3', 1, 0)
 
+  def is_valid(self):
+    """
+    Checks if the current time is between this document's **valid_after** and
+    **valid_until** timestamps. To be valid means the information within this
+    document reflects the current network state.
+
+    .. versionadded:: 1.8.0
+
+    :returns: **True** if this consensus is presently valid and **False**
+      otherwise
+    """
+
+    return self.valid_after < datetime.datetime.utcnow() < self.valid_until
+
+  def is_fresh(self):
+    """
+    Checks if the current time is between this document's **valid_after** and
+    **fresh_until** timestamps. To be fresh means this should be the latest
+    consensus.
+
+    .. versionadded:: 1.8.0
+
+    :returns: **True** if this consensus is presently fresh and **False**
+      otherwise
+    """
+
+    return self.valid_after < datetime.datetime.utcnow() < self.fresh_until
+
   def validate_signatures(self, key_certs):
     """
     Validates we're properly signed by the signing certificates.
diff --git a/test/unit/descriptor/networkstatus/document_v3.py b/test/unit/descriptor/networkstatus/document_v3.py
index e4258dab..a9e5f35b 100644
--- a/test/unit/descriptor/networkstatus/document_v3.py
+++ b/test/unit/descriptor/networkstatus/document_v3.py
@@ -664,6 +664,34 @@ DnN5aFtYKiTc19qIC7Nmo+afPdDEf0MlJvEOP5EWl3w=
       document = NetworkStatusDocumentV3(content, False)
       self.assertEqual(None, document.published)
 
+  def test_is_valid(self):
+    """
+    Checks our time against both a valid and expired descriptor.
+    """
+
+    past = '2012-09-02 22:00:00'
+    future = '2212-09-02 22:00:00'
+
+    document = NetworkStatusDocumentV3.create({'valid-after': past, 'valid-until': future})
+    self.assertTrue(document.is_valid())
+
+    document = NetworkStatusDocumentV3.create({'valid-after': past, 'valid-until': past})
+    self.assertFalse(document.is_valid())
+
+  def test_is_fresh(self):
+    """
+    Checks our time against both a fresh and unfresh descriptor.
+    """
+
+    past = '2012-09-02 22:00:00'
+    future = '2212-09-02 22:00:00'
+
+    document = NetworkStatusDocumentV3.create({'valid-after': past, 'fresh-until': future})
+    self.assertTrue(document.is_fresh())
+
+    document = NetworkStatusDocumentV3.create({'valid-after': past, 'fresh-until': past})
+    self.assertFalse(document.is_fresh())
+
   def test_voting_delay(self):
     """
     Parses the voting-delay field.