commit eee4dd2b6a04e46dfda0d2517c9ac6a0b4dffffc Author: teor teor@riseup.net Date: Mon May 18 13:22:46 2020 +1000
Undo a bunch of unnecessary whitespace changes --- lib/chutney/TorNet.py | 71 ++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 62 insertions(+), 9 deletions(-)
diff --git a/lib/chutney/TorNet.py b/lib/chutney/TorNet.py index 20e28c1..b4ec606 100644 --- a/lib/chutney/TorNet.py +++ b/lib/chutney/TorNet.py @@ -49,8 +49,10 @@ class MissingBinaryException(Exception): pass
def getenv_type(env_var, default, type_, type_name=None): - """ Return the value of the environment variable 'envar' as type_, + """ + Return the value of the environment variable 'envar' as type_, or 'default' if no such variable exists. + Raise ValueError using type_name if the environment variable is set, but type_() raises a ValueError on its value. (If type_name is None or empty, the ValueError uses type_'s string representation instead.) @@ -71,6 +73,7 @@ def getenv_int(env_var, default): """ Return the value of the environment variable 'envar' as an int, or 'default' if no such variable exists. + Raise ValueError if the environment variable is set, but is not an int. """ return getenv_type(env_var, default, int, type_name='an int') @@ -79,7 +82,9 @@ def getenv_bool(env_var, default): """ Return the value of the environment variable 'envar' as a bool, or 'default' if no such variable exists. + Unlike bool(), converts 0, "False", and "No" to False. + Raise ValueError if the environment variable is set, but is not a bool. """ try: @@ -96,9 +101,11 @@ def getenv_bool(env_var, default): def mkdir_p(d, mode=448): """Create directory 'd' and all of its parents as needed. Unlike os.makedirs, does not give an error if d already exists. + 448 is the decimal representation of the octal number 0700. Since python2 only supports 0700 and python3 only supports 0o700, we can use neither. + Note that python2 and python3 differ in how they create the permissions for the intermediate directories. In python3, 'mode' only sets the mode for the last directory created. @@ -134,12 +141,15 @@ def get_absolute_net_path(): """ Returns the absolute path of the "net" directory that chutney should use to store "node*" directories containing torrcs and tor runtime data. + If the CHUTNEY_DATA_DIR environmental variable is an absolute path, it is returned unmodified, regardless of whether the path actually exists. (Chutney creates any directories that do not exist.) + Otherwise, if it is a relative path, and there is an existing directory with that name in the directory containing the chutney executable script, return that path (this check exists for legacy reasons). + Finally, return the path relative to the current working directory, regardless of whether the path actually exists. """ @@ -169,6 +179,8 @@ def get_absolute_nodes_path():
This path is also used as a prefix for the unique nodes directory names. + + See get_new_absolute_nodes_path() for more details. """ return os.path.join(get_absolute_net_path(), 'nodes')
@@ -176,8 +188,10 @@ def get_new_absolute_nodes_path(now=time.time()): """ Returns the absolute path of a unique "nodes*" directory that chutney should use to store the current network's torrcs and tor runtime data. + The nodes directory suffix is based on the current timestamp, incremented if necessary to avoid collisions with existing directories. + (The existing directory check contains known race conditions: running multiple simultaneous chutney instances on the same "net" directory is not supported. The uniqueness check is only designed to avoid @@ -219,7 +233,9 @@ def _warnMissingTor(tor_path, cmdline, tor_name="tor"): def run_tor(cmdline, exit_on_missing=True): """Run the tor command line cmdline, which must start with the path or name of a tor binary. + Returns the combined stdout and stderr of the process. + If exit_on_missing is true, warn and exit if the tor binary is missing. Otherwise, raise a MissingBinaryException. """ @@ -256,6 +272,7 @@ def launch_process(cmdline, tor_name="tor", stdin=None, exit_on_missing=True): """Launch the command line cmdline, which must start with the path or name of a binary. Use tor_name as the canonical name of the binary in logs. Pass stdin to the Popen constructor. + Returns the Popen object for the launched process. """ if tor_name == "tor": @@ -289,6 +306,7 @@ def run_tor_gencert(cmdline, passphrase): """Run the tor-gencert command line cmdline, which must start with the path or name of a tor-gencert binary. Then send passphrase to the stdin of the process. + Returns the combined stdout and stderr of the process. """ p = launch_process(cmdline, @@ -359,6 +377,7 @@ def get_tor_modules(tor): """Check the list of compile-time modules advertised by the given 'tor' binary, and return a map from module name to a boolean describing whether it is supported. + Unlisted modules are ones that Tor did not treat as compile-time optional modules. """ @@ -392,6 +411,7 @@ class Node(object):
"""A Node represents a Tor node or a set of Tor nodes. It's created in a network configuration file. + This class is responsible for holding the user's selected node configuration, and figuring out how the node needs to be configured and launched. @@ -406,7 +426,7 @@ class Node(object): # Users are expected to call these:
def __init__(self, parent=None, **kwargs): - """Create a new Node. + """Create a new Node.
Initial fields in this Node's environment are set from 'kwargs'.
@@ -701,6 +721,7 @@ class LocalNodeBuilder(NodeBuilder):
def _makeHiddenServiceDir(self): """Create the hidden service subdirectory for this node. + The directory name is stored under the 'hs_directory' environment key. It is combined with the 'dir' data directory key to yield the path to the hidden service directory. @@ -760,7 +781,7 @@ class LocalNodeBuilder(NodeBuilder): .format(repr(" ".join(cmdline)), repr(stdouterr))) sys.exit(1) self._env['fingerprint'] = fingerprint - + def _getAltAuthLines(self, hasbridgeauth=False): """Return a combination of AlternateDirAuthority, and AlternateBridgeAuthority lines for @@ -844,7 +865,7 @@ class LocalNodeBuilder(NodeBuilder):
class LocalNodeController(NodeController): - + def _setEd25519Id(self): """Read the ed25519 identity key for this router, and set up the 'ed25519-id' entry in the Environ""" datadir = self._env['dir'] @@ -870,13 +891,13 @@ class LocalNodeController(NodeController): raise ValueError("The current length of the key is {}, which is not matching the expected length of {}".format(CURRENT_ED25519_BASE64_KEY_SIZE, EXPECTED_ED25519_BASE64_KEY_SIZE)) else: self._env['ed25519_id'] = ed25519_id - + def __init__(self, env): - NodeController.__init__(self,env) + NodeController.__init__(self, env) self._env = env #print('abcd') self._setEd25519Id() - + def getNick(self): """Return the nickname for this node.""" return self._env['nick'] @@ -963,6 +984,7 @@ class LocalNodeController(NodeController): """Returns the minimum start time before verifying, regardless of whether the network has bootstrapped, or the dir info has been distributed. + Based on $CHUTNEY_EXTRA_START_TIME and the tor version. """ # User overrode the dynamic time @@ -987,6 +1009,7 @@ class LocalNodeController(NodeController): def getUncheckedDirInfoWaitTime(self): """Returns the amount of time to wait before verifying, after the network has bootstrapped, and the dir info has been distributed. + Based on whether this node is an onion service. """ if self.getOnionService(): @@ -1242,14 +1265,17 @@ class LocalNodeController(NodeController): * a boolean indicating whether this node is a bridge client, and * a dict with the expected paths to the consensus files for this node. + If v2_dir_paths is True, returns the v3 directory paths. Otherwise, returns the bridge status path. If v2_dir_paths is True, but this node is not a bridge client or bridge authority, returns None. (There are no paths.) + Directory servers usually have both consensus flavours. Clients usually have the microdesc consensus, but they may have either flavour. (Or both flavours.) Only the bridge authority has the bridge networkstatus. + The dict keys are: * "ns_cons", "desc", and "desc_new"; * "md_cons", "md", and "md_new"; and @@ -1302,7 +1328,9 @@ class LocalNodeController(NodeController): def getNodePublishedDirInfoPaths(self): """Return a dict of paths to consensus files, where we expect this node to be published. + The dict keys are the nicks for each node. + See getNodeCacheDirInfoPaths() for the path data structure, and which nodes appear in each type of directory. """ @@ -1334,7 +1362,7 @@ class LocalNodeController(NodeController): """ nickname = self.getNick() ed25519_key = self.getEd25519Id() - + cons = dir_format in ["ns_cons", "md_cons", "br_status"] @@ -1364,10 +1392,11 @@ class LocalNodeController(NodeController): else: # If there is no ed25519_id, then we can't search for it return None - + def getFileDirInfoStatus(self, dir_format, dir_path): """Check dir_path, a directory path used by another node, to see if this node is present. The directory path is a dir_format file. + Returns a status 3-tuple containing: * an integer status code: * negative numbers correspond to errors, @@ -1413,11 +1442,15 @@ class LocalNodeController(NodeController): """Combine the directory statuses in dir_status, if their keys appear in status_key_list. Keys may be directory formats, or node nicks. + If best is True, choose the best status, otherwise, choose the worst status. + If ignore_missing is True, ignore missing statuses, if there is any other status available. + If statuses are equal, combine their format sets. + Returns None if the status list is empty. """ dir_status_list = [ dir_status[status_key] @@ -1466,19 +1499,24 @@ class LocalNodeController(NodeController): to_bridge_client): """Summarise the statuses for this node, among all the files used by the other node. + to_dir_server is True if the other node is a directory server. to_bridge_client is True if the other node is a bridge client. + Combine these alternate files by choosing the best status: * desc_alts: "desc" and "desc_new" * md_alts: "md" and "md_new" + Handle these alternate formats by ignoring missing directory files, then choosing the worst status: * cons_all: "ns_cons" and "md_cons" * desc_all: "desc"/"desc_new" and "md"/"md_new" + Add an "node_dir" status that describes the overall status, which is the worst status among descriptors, consensuses, and the bridge networkstatus (if relevant). Return this status. + Returns None if no status is expected. """ from_bridge = self.getBridge() @@ -1577,10 +1615,13 @@ class LocalNodeController(NodeController): to_bridge_client): """Check all the directory paths used by another node, to see if this node is present. + to_dir_server is True if the other node is a directory server. to_bridge_client is True if the other node is a bridge client. + Returns a dict containing a status 3-tuple for every relevant directory format. See getFileDirInfoStatus() for more details. + Returns None if the node doesn't have any directory files containing published information from this node. """ @@ -1609,6 +1650,7 @@ class LocalNodeController(NodeController): def getNodeDirInfoStatusList(self): """Look through the directories on each node, and work out if this node is in that directory. + Returns a dict containing a status 3-tuple for each relevant node. The 3-tuple contains: * a status code, @@ -1616,11 +1658,14 @@ class LocalNodeController(NodeController): * a status message string. See getNodeCacheDirInfoStatus() and getFileDirInfoStatus() for more details. + If this node is a directory authority, bridge authority, or relay (including exits), checks v3 directory consensuses, descriptors, microdesc consensuses, and microdescriptors. + If this node is a bridge, checks bridge networkstatuses, and descriptors on bridge authorities and bridge clients. + If this node is a client (including onion services), returns None. """ dir_files = self.getNodePublishedDirInfoPaths() @@ -1658,6 +1703,7 @@ class LocalNodeController(NodeController): def summariseNodeDirInfoStatus(self, dir_status): """Summarise the statuses for this node's descriptor, among all the directory files used by all other nodes. + Returns a dict containing a status 4-tuple for each status code. The 4-tuple contains: * a status code, @@ -1667,9 +1713,11 @@ class LocalNodeController(NodeController): * a status message string. See getNodeCacheDirInfoStatus() and getFileDirInfoStatus() for more details. + Also add an "node_all" status that describes the overall status, which is the worst status among all the other nodes' directory files. + Returns None if no status is expected. """ node_status = dict() @@ -1736,6 +1784,7 @@ class LocalNodeController(NodeController): def getNodeDirInfoStatus(self): """Return a 4-tuple describing the status of this node's descriptor, in all the directory documents across the network. + If this node does not have a descriptor, returns None. """ dir_status = self.getNodeDirInfoStatusList() @@ -1757,6 +1806,7 @@ class LocalNodeController(NodeController): def isInExpectedDirInfoDocs(self): """Return True if the descriptors for this node are in all expected directory documents. + Return None if this node does not publish descriptors. """ node_status = self.getNodeDirInfoStatus() @@ -1849,7 +1899,9 @@ class TorEnviron(chutney.Templating.Environ):
"""Subclass of chutney.Templating.Environ to implement commonly-used substitutions. + Environment fields provided: + orport, controlport, socksport, dirport: *Port torrc option dir: DataDirectory torrc option nick: Nickname torrc option @@ -1868,6 +1920,7 @@ class TorEnviron(chutney.Templating.Environ): Chutney users can disable the sandbox using: export CHUTNEY_TOR_SANDBOX=0 if it doesn't work on their version of glibc. + Environment fields used: nodenum: chutney's internal node number for the node tag: a short text string that represents the type of node