[tor-commits] [bridgedb/develop] Document IPBasedDistributor.prepopulateRings().

[isis at torproject.org]

commit d229941c72e48c3d1550d45983c4ddd2c5ef8961
Author: Isis Lovecruft <isis at torproject.org>
Date:   Thu Apr 2 22:50:04 2015 +0000

    Document IPBasedDistributor.prepopulateRings().
---
 lib/bridgedb/Dist.py |   55 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/lib/bridgedb/Dist.py b/lib/bridgedb/Dist.py
index 78741a7..39e70be 100644
--- a/lib/bridgedb/Dist.py
+++ b/lib/bridgedb/Dist.py
@@ -201,6 +201,61 @@ class IPBasedDistributor(Distributor):
         self.setDistributorName('HTTPS')
 
     def prepopulateRings(self):
+        """Prepopulate this distributor's hashrings and subhashrings with
+        bridges.
+
+        The hashring structure for this distributor is influenced by the
+        ``N_IP_CLUSTERS`` configuration option, as well as the number of
+        ``PROXY_LIST_FILES``.  Essentially, :data:`nClusters` is set to the
+        specified ``N_IP_CLUSTERS``.  The ``PROXY_LIST_FILES`` (plus the
+        :class:`bridgedb.proxy.ProxySet` for the Tor Exit list downloaded into
+        memory with :script:`get-tor-exits`) are stored in :data:`categories`.
+
+        The number of subhashrings which this :class:`Distributor` has active
+        in its hashring is then the :data:`nClusters` plus the number of
+        :data:`categories`.
+
+        As an example, if BridgeDB was configured with ``N_IP_CLUSTERS=4`` and
+        ``PROXY_LIST_FILES=["open-socks-proxies.txt"]``, then the total number
+        of subhashrings is six — four for the "clusters", and two
+        "categories": one for everything contained within the
+        ``"open-socks-proxies.txt"`` file and the other for the downloaded
+        list of Tor Exits.  Thus, the resulting hashring-subhashring structure
+        would look like:
+
+        +------------------+---------------------------------------------------+-------------------------+
+        |                  |               Directly connecting users           | Tor / known proxy users |
+        +------------------+------------+------------+------------+------------+------------+------------+
+        | Clusters /       | Cluster-1  | Cluster-2  | Cluster-3  | Cluster-4  | Cat-1      | Cat-2      |
+        | Categories       |            |            |            |            |            |            |
+        +==================+============+============+============+============+============+============+
+        | Subhashrings     |            |            |            |            |            |            |
+        | (total, assigned)| (6,0)      | (6,1)      | (6,2)      | (6,3)      | (6,4)      | (6,5)      |
+        +------------------+------------+------------+------------+------------+------------+------------+
+        | Filtered         | (6,0)      | (6,1)      | (6,2)      | (6,3)      | (6,4)      | (6,5)      |
+        | Subhashrings     +------------+------------+------------+------------+------------+------------+
+        | bBy requested    | (6,0)-IPv4 | (6,1)-IPv4 | (6,2)-IPv4 | (6,3)-IPv4 | (6,4)-IPv4 | (6,5)-IPv4 |
+        | bridge type)     +------------+------------+------------+------------+------------+------------+
+        |                  | (6,0)-IPv6 | (6,1)-IPv6 | (6,2)-IPv6 | (6,3)-IPv6 | (6,4)-IPv6 | (6,5)-IPv6 |
+        +------------------+------------+------------+------------+------------+------------+------------+
+
+        The "filtered subhashrings" are essentially copies of their respective
+        subhashring, that is, subhashring ``(6,0)`` contains both IPv4 and
+        IPv6 bridges, meaning that its contents are a superset of the filtered
+        subhashrings ``(6,0)-IPv4`` and ``(6,0)-IPv6``.  (I have no idea of
+        the relation between ``(6,0)-IPv4`` and ``(6,0)-IPv6``, including
+        whether or not their contents are disjoint. I didn't design this shit,
+        I'm just redesigning it.)
+
+        "Why does the ``(6,0)`` superset subhashring exist then?"
+
+        you might ask.  That's a very good question.  I don't know either.
+        I'm inclined to think it shouldn't exist, unless we wish to allow
+        clients to request IPv4 bridges and IPv6 bridges simultaneously
+        (there's currently no interface to do this, however).
+
+        Thus, in this example, we end up with **18 total subhashrings**.
+        """
         logging.info("Prepopulating %s distributor hashrings..." % self.name)
         # populate all rings (for dumping assignments and testing)
         for filterFn in [None, filterBridgesByIP4, filterBridgesByIP6]: