June 2012 - tor-commits - lists.torproject.org

[tor/master] Change the default for DynamicDHGroups to 0
by nickm＠torproject.org 11 Jun '12

11 Jun '12

commit 8a341cc429879e642862cb16a9de5da889867020 Author: Nick Mathewson <nickm(a)torproject.org> Date: Wed Jun 6 12:00:04 2012 -0400 Change the default for DynamicDHGroups to 0 This feature can make Tor relays less identifiable by their use of the mod_ssl DH group, but at the cost of some usability (#4721) and bridge tracing (#6087) regressions. We should try to turn this on by default again if we find that the mod_ssl group is uncommon and/or we move to a different DH group size (see #6088). Before we can do so, we need a fix for bugs #6087 and Resolves ticket #5598 for now. --- changes/bug5598 | 5 +++++ doc/tor.1.txt | 2 +- src/or/config.c | 2 +- 3 files changed, 7 insertions(+), 2 deletions(-) diff --git a/changes/bug5598 b/changes/bug5598 new file mode 100644 index 0000000..e8e6741 --- /dev/null +++ b/changes/bug5598 @@ -0,0 +1,5 @@ + o Changed defaults: + - Change the default value for DynamicDHGroups to 0. This feature can + make Tor relays less identifiable by their use of the mod_ssl DH + group, but at the cost of some usability (#4721) and bridge tracing + (#6087) regressions. Resolves ticket #5598. diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 00371c3..f5e5b86 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -266,7 +266,7 @@ Other options can be specified either on the command-line (--option If this option is set to 1, when running as a server, generate our own Diffie-Hellman group instead of using the one from Apache's mod_ssl. This option may help circumvent censorship based on static - Diffie-Hellman parameters. (Default: 1). + Diffie-Hellman parameters. (Default: 0). **AlternateDirAuthority** [__nickname__] [**flags**] __address__:__port__ __fingerprint__ + diff --git a/src/or/config.c b/src/or/config.c index 090d96c..cf6ae84 100644 --- a/src/or/config.c +++ b/src/or/config.c @@ -257,7 +257,7 @@ static config_var_t _option_vars[] = { V(DisableAllSwap, BOOL, "0"), V(DisableDebuggerAttachment, BOOL, "1"), V(DisableIOCP, BOOL, "1"), - V(DynamicDHGroups, BOOL, "1"), + V(DynamicDHGroups, BOOL, "0"), V(DNSPort, LINELIST, NULL), V(DNSListenAddress, LINELIST, NULL), V(DownloadExtraInfo, BOOL, "0"),

1 0

[tor/master] Merge remote-tracking branch 'public/bug5598'
by nickm＠torproject.org 11 Jun '12

11 Jun '12

commit 70910479e383806b98f15490abc5e45ceb1066d5 Merge: a6180b7 8a341cc Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Jun 11 10:26:48 2012 -0400 Merge remote-tracking branch 'public/bug5598' Conflicts: doc/tor.1.txt Conflict was on a formatting issue in the manpage. changes/bug5598 | 5 +++++ doc/tor.1.txt | 2 +- src/or/config.c | 2 +- 3 files changed, 7 insertions(+), 2 deletions(-) diff --cc doc/tor.1.txt index 3e7541b,f5e5b86..78a33ca --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@@ -266,7 -266,7 +266,7 @@@ Other options can be specified either o If this option is set to 1, when running as a server, generate our own Diffie-Hellman group instead of using the one from Apache's mod_ssl. This option may help circumvent censorship based on static - Diffie-Hellman parameters. (Default: 1) - Diffie-Hellman parameters. (Default: 0). ++ Diffie-Hellman parameters. (Default: 0) **AlternateDirAuthority** [__nickname__] [**flags**] __address__:__port__ __fingerprint__ +

1 0

[tor/master] Be more careful calling wcstombs
by nickm＠torproject.org 11 Jun '12

11 Jun '12

commit 1e5683b167a612bf76d4ae9ba508027e0d473e52 Author: Nick Mathewson <nickm(a)torproject.org> Date: Thu May 17 10:08:48 2012 -0400 Be more careful calling wcstombs The function is not guaranteed to NUL-terminate its output. It *is*, however, guaranteed not to generate more than two bytes per multibyte character (plus terminating nul), so the general approach I'm taking is to try to allocate enough space, AND to manually add a NUL at the end of each buffer just in case I screwed up the "enough space" thing. Fixes bug 5909. --- changes/bug5909 | 5 +++++ src/common/compat.c | 23 ++++++++++++++++------- src/common/util.c | 3 ++- src/or/config.c | 5 +++-- src/or/eventdns.c | 3 ++- src/or/ntmain.c | 3 ++- 6 files changed, 30 insertions(+), 12 deletions(-) diff --git a/changes/bug5909 b/changes/bug5909 new file mode 100644 index 0000000..61990fa --- /dev/null +++ b/changes/bug5909 @@ -0,0 +1,5 @@ + o Major bugfixes: + - When building Tor on Windows with -DUNICODE (not default), + ensure that error messages, filenames, and DNS server names are + always NUL-terminated when we convert them to a single-byte + encoding. Fixes bug 5909; bugfix on 0.2.2.16-alpha. diff --git a/src/common/compat.c b/src/common/compat.c index 334ea1b..db2187b 100644 --- a/src/common/compat.c +++ b/src/common/compat.c @@ -3046,28 +3046,37 @@ format_win32_error(DWORD err) { TCHAR *str = NULL; char *result; + DWORD n; /* Somebody once decided that this interface was better than strerror(). */ - FormatMessage(FORMAT_MESSAGE_ALLOCATE_BUFFER | + n = FormatMessage(FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS, NULL, err, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), - (LPVOID)&str, + (LPVOID)&str, 0, NULL); - if (str) { + if (str && n) { #ifdef UNICODE - char abuf[1024] = {0}; - wcstombs(abuf,str,1024); - result = tor_strdup(abuf); + size_t len; + if (n > 128*1024) + len = (128 * 1024) * 2 + 1; /* This shouldn't be possible, but let's + * make sure. */ + else + len = n * 2 + 1; + result = tor_malloc(len); + wcstombs(result,str,len); + result[len-1] = '\0'; #else result = tor_strdup(str); #endif - LocalFree(str); /* LocalFree != free() */ } else { result = tor_strdup("<unformattable error>"); } + if (str) { + LocalFree(str); /* LocalFree != free() */ + } return result; } #endif diff --git a/src/common/util.c b/src/common/util.c index 4c086e8..dc8f8b7 100644 --- a/src/common/util.c +++ b/src/common/util.c @@ -2855,7 +2855,7 @@ tor_listdir(const char *dirname) #ifdef _WIN32 char *pattern=NULL; TCHAR tpattern[MAX_PATH] = {0}; - char name[MAX_PATH] = {0}; + char name[MAX_PATH*2+1] = {0}; HANDLE handle; WIN32_FIND_DATA findData; tor_asprintf(&pattern, "%s\\*", dirname); @@ -2872,6 +2872,7 @@ tor_listdir(const char *dirname) while (1) { #ifdef UNICODE wcstombs(name,findData.cFileName,MAX_PATH); + name[sizeof(name)-1] = '\0'; #else strlcpy(name,findData.cFileName,sizeof(name)); #endif diff --git a/src/or/config.c b/src/or/config.c index 090d96c..2e3ce64 100644 --- a/src/or/config.c +++ b/src/or/config.c @@ -4302,7 +4302,7 @@ static char * get_windows_conf_root(void) { static int is_set = 0; - static char path[MAX_PATH+1]; + static char path[MAX_PATH*2+1]; TCHAR tpath[MAX_PATH] = {0}; LPITEMIDLIST idl; @@ -4332,7 +4332,8 @@ get_windows_conf_root(void) /* Convert the path from an "ID List" (whatever that is!) to a path. */ result = SHGetPathFromIDList(idl, tpath); #ifdef UNICODE - wcstombs(path,tpath,MAX_PATH); + wcstombs(path,tpath,sizeof(path)); + path[sizeof(path)-1] = '\0'; #else strlcpy(path,tpath,sizeof(path)); #endif diff --git a/src/or/eventdns.c b/src/or/eventdns.c index 61a2836..768693a 100644 --- a/src/or/eventdns.c +++ b/src/or/eventdns.c @@ -3213,7 +3213,7 @@ static int config_nameserver_from_reg_key(HKEY key, const TCHAR *subkey) { char *buf; - char ansibuf[MAX_PATH] = {0}; + char ansibuf[MAX_PATH] = {0}; DWORD bufsz = 0, type = 0; int status = 0; @@ -3226,6 +3226,7 @@ config_nameserver_from_reg_key(HKEY key, const TCHAR *subkey) if (RegQueryValueEx(key, subkey, 0, &type, (LPBYTE)buf, &bufsz) == ERROR_SUCCESS && bufsz > 1) { wcstombs(ansibuf,(wchar_t*)buf,MAX_PATH);/*XXXX UNICODE */ + abuf[MAX_PATH-1] = '\0'; status = evdns_nameserver_ip_add_line(ansibuf); } diff --git a/src/or/ntmain.c b/src/or/ntmain.c index 01244c4..d001f7b 100644 --- a/src/or/ntmain.c +++ b/src/or/ntmain.c @@ -455,7 +455,7 @@ static char * nt_service_command_line(int *using_default_torrc) { TCHAR tor_exe[MAX_PATH+1]; - char tor_exe_ascii[MAX_PATH+1]; + char tor_exe_ascii[MAX_PATH*2+1]; char *command=NULL, *options=NULL; smartlist_t *sl; int i; @@ -483,6 +483,7 @@ nt_service_command_line(int *using_default_torrc) #ifdef UNICODE wcstombs(tor_exe_ascii, tor_exe, sizeof(tor_exe_ascii)); + tor_exe_ascii[sizeof(tor_exe_ascii)-1] = '\0'; #else strlcpy(tor_exe_ascii, tor_exe, sizeof(tor_exe_ascii)); #endif

1 0

[tor/master] Fix mingw build with -DUNICODE -D_UNICODE
by nickm＠torproject.org 11 Jun '12

11 Jun '12

commit bf9252587b4d7d970f02631b308451fb05ec5560 Author: Nick Mathewson <nickm(a)torproject.org> Date: Thu Jun 7 11:59:32 2012 -0400 Fix mingw build with -DUNICODE -D_UNICODE This is a very blunt fix, and mostly just turns some func() calls into FuncA() to make things build again. Fixes bug 6097. --- changes/fix_unicode | 3 +++ src/common/util.c | 4 ++-- src/test/test.c | 2 +- src/test/test_util.c | 6 +++++- 4 files changed, 11 insertions(+), 4 deletions(-) diff --git a/changes/fix_unicode b/changes/fix_unicode new file mode 100644 index 0000000..b97c393 --- /dev/null +++ b/changes/fix_unicode @@ -0,0 +1,3 @@ + o Minor bugfixes: + - Make Tor build correctly again with -DUNICODE -D_UNICODE defined. + Bugfix on 0.2.2.16-alpha; fixes bug 6097. diff --git a/src/common/util.c b/src/common/util.c index dc8f8b7..28ecff3 100644 --- a/src/common/util.c +++ b/src/common/util.c @@ -3381,7 +3381,7 @@ tor_spawn_background(const char *const filename, const char **argv, process_handle_t *process_handle; int status; - STARTUPINFO siStartInfo; + STARTUPINFOA siStartInfo; BOOL retval = FALSE; SECURITY_ATTRIBUTES saAttr; @@ -3442,7 +3442,7 @@ tor_spawn_background(const char *const filename, const char **argv, /* Create the child process */ - retval = CreateProcess(filename, // module name + retval = CreateProcessA(filename, // module name joined_argv, // command line /* TODO: should we set explicit security attributes? (#2046, comment 5) */ NULL, // process security attributes diff --git a/src/test/test.c b/src/test/test.c index 4f19f36..89b4ced 100644 --- a/src/test/test.c +++ b/src/test/test.c @@ -91,7 +91,7 @@ setup_directory(void) char buf[MAX_PATH]; const char *tmp = buf; /* If this fails, we're probably screwed anyway */ - if (!GetTempPath(sizeof(buf),buf)) + if (!GetTempPathA(sizeof(buf),buf)) tmp = "c:\\windows\\temp"; tor_snprintf(temp_dir, sizeof(temp_dir), "%s\\tor_test_%d", tmp, (int)getpid()); diff --git a/src/test/test_util.c b/src/test/test_util.c index 4b628ea..7484b9e 100644 --- a/src/test/test_util.c +++ b/src/test/test_util.c @@ -14,6 +14,10 @@ #include "mempool.h" #include "memarea.h" +#ifdef _WIN32 +#include <tchar.h> +#endif + static void test_util_time(void) { @@ -2113,7 +2117,7 @@ test_util_parent_dir(void *ptr) static void test_util_load_win_lib(void *ptr) { - HANDLE h = load_windows_system_library("advapi32.dll"); + HANDLE h = load_windows_system_library(_T("advapi32.dll")); (void) ptr; tt_assert(h);

1 0

[tor/master] Merge branch 'bug6097'
by nickm＠torproject.org 11 Jun '12

11 Jun '12

commit a6180b7f290c52b03f8abe3caf2ce233399dd66f Merge: cb01aae bf92525 Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Jun 11 10:14:01 2012 -0400 Merge branch 'bug6097' changes/bug5909 | 5 +++++ changes/fix_unicode | 3 +++ src/common/compat.c | 23 ++++++++++++++++------- src/common/util.c | 7 ++++--- src/or/config.c | 5 +++-- src/or/eventdns.c | 3 ++- src/or/ntmain.c | 3 ++- src/test/test.c | 2 +- src/test/test_util.c | 6 +++++- 9 files changed, 41 insertions(+), 16 deletions(-)

1 0

[tor/master] Merge branch 'bug2865'
by nickm＠torproject.org 11 Jun '12

11 Jun '12

commit cb01aaea12b5ed217a1af2595aa9d658c4a52709 Merge: 8be6058 2d127ea Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Jun 11 09:53:49 2012 -0400 Merge branch 'bug2865' changes/bug2865 | 4 ++ doc/tor.1.txt | 88 +++++++++++++++++++++++++++--------------------------- 2 files changed, 48 insertions(+), 44 deletions(-)

1 0

[tor/master] Correct the defaults for the *Statistics options
by nickm＠torproject.org 11 Jun '12

11 Jun '12

commit b74f851861fb14780e7aa2edb9199d74f7ec0cf3 Author: Nick Mathewson <nickm(a)torproject.org> Date: Thu Jun 7 13:46:51 2012 -0400 Correct the defaults for the *Statistics options --- changes/bug2865 | 4 ++++ doc/tor.1.txt | 8 ++++---- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/changes/bug2865 b/changes/bug2865 new file mode 100644 index 0000000..4a7a332 --- /dev/null +++ b/changes/bug2865 @@ -0,0 +1,4 @@ + o Documentation fixes: + - Correct the manpage's descriptions for the default values of + DirReqStatistics and ExtraInfoStatistics. Fixes bug 2865; bugfix + on 0.2.3.1-alpha. diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 00371c3..9473ba4 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -1372,9 +1372,9 @@ is non-zero): cells spend in circuit queues to disk every 24 hours. (Default: 0) **DirReqStatistics** **0**|**1**:: - When this option is enabled, Tor writes statistics on the number and - response time of network status requests to disk every 24 hours. - (Default: 0) + When this option is enabled, a Tor directory writes statistics on the + number and response time of network status requests to disk every 24 + hours. (Default: 1). **EntryStatistics** **0**|**1**:: When this option is enabled, Tor writes statistics on the number of @@ -1391,7 +1391,7 @@ is non-zero): **ExtraInfoStatistics** **0**|**1**:: When this option is enabled, Tor includes previously gathered statistics in its extra-info documents that it uploads to the directory authorities. - (Default: 0) + (Default: 1) DIRECTORY SERVER OPTIONS ------------------------

1 0

[tor/master] List defaults consistently in manpage
by nickm＠torproject.org 11 Jun '12

11 Jun '12

commit 2d127eacd992c6533d653217632efb49f6df9fc0 Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Jun 11 09:48:46 2012 -0400 List defaults consistently in manpage Nearly everywhere, we end options with "(Default: foo)". But in a few places, we inserted an extra period after or before the close parenthesis, and in a few other places we said "(Defaults to foo)". Let's not do that. --- doc/tor.1.txt | 82 ++++++++++++++++++++++++++++---------------------------- 1 files changed, 41 insertions(+), 41 deletions(-) diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 9473ba4..3e7541b 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -167,7 +167,7 @@ Other options can be specified either on the command-line (--option You should **not** enable this feature unless you encounter the "no buffer space available" issue. Reducing the TCP buffers affects window size for the TCP stream and will reduce throughput in proportion to round trip - time on long paths. (Default: 0.) + time on long paths. (Default: 0) **ConstrainedSockSize** __N__ **bytes**|**KB**:: When **ConstrainedSockets** is enabled the receive and transmit buffers for @@ -183,15 +183,15 @@ Other options can be specified either on the command-line (--option host to control it. (Setting both authentication methods means either method is sufficient to authenticate to Tor.) This option is required for many Tor controllers; most use the value of 9051. - Set it to "auto" to have Tor pick a port for you. (Default: 0). + Set it to "auto" to have Tor pick a port for you. (Default: 0) **ControlListenAddress** __IP__[:__PORT__]:: Bind the controller listener to this address. If you specify a port, bind to this port rather than the one specified in ControlPort. We strongly recommend that you leave this alone unless you know what you're doing, since giving attackers access to your control listener is really - dangerous. (Default: 127.0.0.1) This directive can be specified multiple - times to bind to multiple addresses/ports. + dangerous. This directive can be specified multiple + times to bind to multiple addresses/ports. (Default: 127.0.0.1) **ControlSocket** __Path__:: Like ControlPort, but listens on a Unix domain socket, rather than a TCP @@ -224,7 +224,7 @@ Other options can be specified either on the command-line (--option If this option is set to 0, don't allow the filesystem group to read the cookie file. If the option is set to 1, make the cookie file readable by the default GID. [Making the file readable by other groups is not yet - implemented; let us know if you need this for some reason.] (Default: 0). + implemented; let us know if you need this for some reason.] (Default: 0) **ControlPortWriteToFile** __Path__:: If set, Tor writes the address and port of any control port it opens to @@ -234,7 +234,7 @@ Other options can be specified either on the command-line (--option **ControlPortFileGroupReadable** **0**|**1**:: If this option is set to 0, don't allow the filesystem group to read the control port file. If the option is set to 1, make the control port - file readable by the default GID. (Default: 0). + file readable by the default GID. (Default: 0) **DataDirectory** __DIR__:: Store working data in DIR (Default: @LOCALSTATEDIR@/lib/tor) @@ -266,7 +266,7 @@ Other options can be specified either on the command-line (--option If this option is set to 1, when running as a server, generate our own Diffie-Hellman group instead of using the one from Apache's mod_ssl. This option may help circumvent censorship based on static - Diffie-Hellman parameters. (Default: 1). + Diffie-Hellman parameters. (Default: 1) **AlternateDirAuthority** [__nickname__] [**flags**] __address__:__port__ __fingerprint__ + @@ -497,7 +497,7 @@ Other options can be specified either on the command-line (--option CircuitPriorityHalflife value (in seconds). If this option is not set at all, we use the behavior recommended in the current consensus networkstatus. This is an advanced option; you generally shouldn't have - to mess with it. (Default: not set.) + to mess with it. (Default: not set) **DisableIOCP** **0**|**1**:: If Tor was built to use the Libevent's "bufferevents" networking code @@ -568,7 +568,7 @@ The following options are useful only for clients (that is, if open in that time, give up on it. If LearnCircuitBuildTimeout is 1, this value serves as the initial value to use before a timeout is learned. If LearnCircuitBuildTimeout is 0, this value is the only value used. - (Default: 60 seconds.) + (Default: 60 seconds) **CircuitIdleTimeout** __NUM__:: If we have kept a clean (never used) circuit around for NUM seconds, then @@ -576,7 +576,7 @@ The following options are useful only for clients (that is, if of its circuits, and then expire its TLS connections. Also, if we end up making a circuit that is not useful for exiting any of the requests we're receiving, it won't forever take up a slot in the circuit list. (Default: 1 - hour.) + hour) **CircuitStreamTimeout** __NUM__:: If non-zero, this option overrides our internal timeout schedule for how @@ -864,14 +864,14 @@ The following options are useful only for clients (that is, if **SocksTimeout** __NUM__:: Let a socks connection wait NUM seconds handshaking, and NUM seconds unattached waiting for an appropriate circuit, before we fail it. (Default: - 2 minutes.) + 2 minutes) **TokenBucketRefillInterval** __NUM__ [**msec**|**second**]:: Set the refill interval of Tor's token bucket to NUM milliseconds. NUM must be between 1 and 1000, inclusive. Note that the configured bandwidth limits are still expressed in bytes per second: this option only affects the frequency with which Tor checks to see whether - previously exhausted connections may read again. (Default: 100 msec.) + previously exhausted connections may read again. (Default: 100 msec) **TrackHostExits** __host__,__.domain__,__...__:: For each value in the comma separated list, Tor will track recent @@ -904,18 +904,18 @@ The following options are useful only for clients (that is, if If this option is set to 1, we pick a few long-term entry servers, and try to stick with them. This is desirable because constantly changing servers increases the odds that an adversary who owns some servers will observe a - fraction of your paths. (Defaults to 1.) + fraction of your paths. (Default: 1) **NumEntryGuards** __NUM__:: If UseEntryGuards is set to 1, we will try to pick a total of NUM routers - as long-term entries for our circuits. (Defaults to 3.) + as long-term entries for our circuits. (Default: 3) **SafeSocks** **0**|**1**:: When this option is enabled, Tor will reject application connections that use unsafe variants of the socks protocol -- ones that only provide an IP address, meaning the application is doing a DNS resolve first. Specifically, these are socks4 and socks5 when not doing remote DNS. - (Defaults to 0.) + (Default: 0) **TestSocks** **0**|**1**:: When this option is enabled, Tor will make a notice-level log entry for @@ -975,7 +975,7 @@ The following options are useful only for clients (that is, if Linux's IPTables. If you're planning to use Tor as a transparent proxy for a network, you'll want to examine and change VirtualAddrNetwork from the default setting. You'll also want to set the TransListenAddress option for - the network you'd like to proxy. (Default: 0). + the network you'd like to proxy. (Default: 0) **TransListenAddress** __IP__[:__PORT__]:: Bind to this address to listen for transparent proxy connections. (Default: @@ -1008,7 +1008,7 @@ The following options are useful only for clients (that is, if that ends with one of the suffixes in **AutomapHostsSuffixes**, we map an unused virtual address to that address, and return the new virtual address. This is handy for making ".onion" addresses work with applications that - resolve an address and then connect to it. (Default: 0). + resolve an address and then connect to it. (Default: 0) **AutomapHostsSuffixes** __SUFFIX__,__SUFFIX__,__...__:: A comma-separated list of suffixes to use with **AutomapHostsOnResolve**. @@ -1019,7 +1019,7 @@ The following options are useful only for clients (that is, if them anonymously. Set the port to "auto" to have Tor pick a port for you. This directive can be specified multiple times to bind to multiple addresses/ports. See SOCKSPort for an explanation of isolation - flags. (Default: 0). + flags. (Default: 0) **DNSListenAddress** __IP__[:__PORT__]:: Bind to this address to listen for DNS connections. (DEPRECATED: As of @@ -1032,35 +1032,35 @@ The following options are useful only for clients (that is, if If true, Tor does not believe any anonymously retrieved DNS answer that tells it that an address resolves to an internal address (like 127.0.0.1 or 192.168.0.1). This option prevents certain browser-based attacks; don't - turn it off unless you know what you're doing. (Default: 1). + turn it off unless you know what you're doing. (Default: 1) **ClientRejectInternalAddresses** **0**|**1**:: If true, Tor does not try to fulfill requests to connect to an internal address (like 127.0.0.1 or 192.168.0.1) __unless a exit node is specifically requested__ (for example, via a .exit hostname, or a - controller request). (Default: 1). + controller request). (Default: 1) **DownloadExtraInfo** **0**|**1**:: If true, Tor downloads and caches "extra-info" documents. These documents contain information about servers other than the information in their regular router descriptors. Tor does not use this information for anything - itself; to save bandwidth, leave this option turned off. (Default: 0). + itself; to save bandwidth, leave this option turned off. (Default: 0) **FallbackNetworkstatusFile** __FILENAME__:: If Tor doesn't have a cached networkstatus file, it starts out using this one instead. Even if this file is out of date, Tor can still use it to learn about directory mirrors, so it doesn't need to put load on the - authorities. (Default: None). + authorities. (Default: None) **WarnPlaintextPorts** __port__,__port__,__...__:: Tells Tor to issue a warnings whenever the user tries to make an anonymous connection to one of these ports. This option is designed to alert users to services that risk sending passwords in the clear. (Default: - 23,109,110,143). + 23,109,110,143) **RejectPlaintextPorts** __port__,__port__,__...__:: Like WarnPlaintextPorts, but instead of warning about risky port uses, Tor - will instead refuse to make the connection. (Default: None). + will instead refuse to make the connection. (Default: None) **AllowSingleHopCircuits** **0**|**1**:: When this option is set, the attached Tor controller can use relays @@ -1300,14 +1300,14 @@ is non-zero): of the __dayth__ day of one week to the same day and time of the next week, with Monday as day 1 and Sunday as day 7. If **day** is given, each accounting period runs from the time __HH:MM__ each day to the same time on - the next day. All times are local, and given in 24-hour time. (Defaults to - "month 1 0:00".) + the next day. All times are local, and given in 24-hour time. (Default: + "month 1 0:00") **RefuseUnknownExits** **0**|**1**|**auto**:: Prevent nodes that don't appear in the consensus from exiting using this relay. If the option is 1, we always block exit attempts from such nodes; if it's 0, we never do, and if the option is "auto", then we do - whatever the authorities suggest in the consensus. (Defaults to auto.) + whatever the authorities suggest in the consensus. (Default: auto) **ServerDNSResolvConfFile** __filename__:: Overrides the default DNS configuration with the configuration in @@ -1320,28 +1320,28 @@ is non-zero): If this option is false, Tor exits immediately if there are problems parsing the system DNS configuration or connecting to nameservers. Otherwise, Tor continues to periodically retry the system nameservers until - it eventually succeeds. (Defaults to "1".) + it eventually succeeds. (Default: 1) **ServerDNSSearchDomains** **0**|**1**:: If set to 1, then we will search for addresses in the local search domain. For example, if this system is configured to believe it is in "example.com", and a client tries to connect to "www", the client will be connected to "www.example.com". This option only affects name lookups that - your server does on behalf of clients. (Defaults to "0".) + your server does on behalf of clients. (Default: 0) **ServerDNSDetectHijacking** **0**|**1**:: When this option is set to 1, we will test periodically to determine whether our local nameservers have been configured to hijack failing DNS requests (usually to an advertising site). If they are, we will attempt to correct this. This option only affects name lookups that your server does - on behalf of clients. (Defaults to "1".) + on behalf of clients. (Default: 1) **ServerDNSTestAddresses** __address__,__address__,__...__:: When we're detecting DNS hijacking, make sure that these __valid__ addresses aren't getting redirected. If they are, then our DNS is completely useless, and we'll reset our exit policy to "reject *:*". This option only affects - name lookups that your server does on behalf of clients. (Defaults to - "www.google.com, www.mit.edu, www.yahoo.com, www.slashdot.org".) + name lookups that your server does on behalf of clients. (Default: + "www.google.com, www.mit.edu, www.yahoo.com, www.slashdot.org") **ServerDNSAllowNonRFC953Hostnames** **0**|**1**:: When this option is disabled, Tor does not try to resolve hostnames @@ -1374,7 +1374,7 @@ is non-zero): **DirReqStatistics** **0**|**1**:: When this option is enabled, a Tor directory writes statistics on the number and response time of network status requests to disk every 24 - hours. (Default: 1). + hours. (Default: 1) **EntryStatistics** **0**|**1**:: When this option is enabled, Tor writes statistics on the number of @@ -1488,7 +1488,7 @@ if DirPort is non-zero): **FetchV2Networkstatus** **0**|**1**:: If set, we try to fetch the (obsolete, unused) version 2 network status consensus documents from the directory authorities. No currently - supported Tor version uses them. (Default: 0.) + supported Tor version uses them. (Default: 0) DIRECTORY AUTHORITY SERVER OPTIONS @@ -1522,7 +1522,7 @@ DIRECTORY AUTHORITY SERVER OPTIONS **DirAllowPrivateAddresses** **0**|**1**:: If set to 1, Tor will accept router descriptors with arbitrary "Address" elements. Otherwise, if the address is not an IP address or is a private IP - address, it will reject the router descriptor. Defaults to 0. + address, it will reject the router descriptor. (Default: 0) **AuthDirBadDir** __AddressPattern...__:: Authoritative directories only. A set of address patterns for servers that @@ -1601,7 +1601,7 @@ DIRECTORY AUTHORITY SERVER OPTIONS implemented) "bridge community" design, where a community of bridge relay operators all use an alternate bridge directory authority, and their target user audience can periodically fetch the list of - available community bridges to stay up-to-date. (Default: not set.) + available community bridges to stay up-to-date. (Default: not set) **V3AuthVotingInterval** __N__ **minutes**|**hours**:: V3 authoritative directories only. Configures the server's preferred voting @@ -1613,14 +1613,14 @@ DIRECTORY AUTHORITY SERVER OPTIONS V3 authoritative directories only. Configures the server's preferred delay between publishing its vote and assuming it has all the votes from all the other authorities. Note that the actual time used is not the server's - preferred time, but the consensus of all preferences. (Default: 5 minutes.) + preferred time, but the consensus of all preferences. (Default: 5 minutes) **V3AuthDistDelay** __N__ **minutes**|**hours**:: V3 authoritative directories only. Configures the server's preferred delay between publishing its consensus and signature and assuming it has all the signatures from all the other authorities. Note that the actual time used is not the server's preferred time, but the consensus of all preferences. - (Default: 5 minutes.) + (Default: 5 minutes) **V3AuthNIntervalsValid** __NUM__:: V3 authoritative directories only. Configures the number of VotingIntervals @@ -1628,18 +1628,18 @@ DIRECTORY AUTHORITY SERVER OPTIONS increases network partitioning risks; choosing low numbers increases directory traffic. Note that the actual number of intervals used is not the server's preferred number, but the consensus of all preferences. Must be at - least 2. (Default: 3.) + least 2. (Default: 3) **V3BandwidthsFile** __FILENAME__:: V3 authoritative directories only. Configures the location of the bandiwdth-authority generated file storing information on relays' measured - bandwidth capacities. (Default: unset.) + bandwidth capacities. (Default: unset) **V3AuthUseLegacyKey** **0**|**1**:: If set, the directory authority will sign consensuses not only with its own signing key, but also with a "legacy" key and certificate with a different identity. This feature is used to migrate directory authority - keys in the event of a compromise. (Default: 0.) + keys in the event of a compromise. (Default: 0) **RephistTrackTime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: Tells an authority, or other node tracking node reliability and history,

1 0

[stem/master] Converting test.* contents to reStructuredText
by atagar＠torproject.org 10 Jun '12

10 Jun '12

commit 65351e9eea2a30e81632e045c0b2825d0573719c Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Jun 10 15:16:57 2012 -0700 Converting test.* contents to reStructuredText The test contents aren't currently included in the stem documentation, since they aren't generally of interest to users. However, might as well do its documentation as reStructuredText for consistency's sake. I'll probably include just the framework utilities with our documenntation later to help people hacking on stem. --- test/check_whitespace.py | 13 +-- test/integ/connection/authentication.py | 26 +--- test/mocking.py | 76 +++++------ test/output.py | 11 +- test/runner.py | 184 ++++++++++--------------- test/unit/control/__init__.py | 6 - test/unit/descriptor/extrainfo_descriptor.py | 8 +- test/unit/descriptor/server_descriptor.py | 10 +- 8 files changed, 132 insertions(+), 202 deletions(-) diff --git a/test/check_whitespace.py b/test/check_whitespace.py index e0419a5..db97130 100644 --- a/test/check_whitespace.py +++ b/test/check_whitespace.py @@ -18,12 +18,9 @@ def get_issues(base_path = DEFAULT_TARGET): """ Checks python source code in the given directory for whitespace issues. - Arguments: - base_path (str) - directory to be iterated over + :param str base_path: directory to be iterated over - Returns: - dict of the form... - path => [(line_number, message)...] + :returns: dict of the form ``path => [(line_number, message)...]`` """ # TODO: This does not check that block indentations are two spaces because @@ -80,11 +77,9 @@ def _get_python_files(base_path): """ Iterates over all of the python files within a directory. - Arguments: - base_path (str) - directory to be iterated over + :param str base_path: directory to be iterated over - Returns: - iterator that yields the absolute path for python source code + :returns: iterator that yields the absolute path for python source code """ for root, _, files in os.walk(base_path, followlinks = True): diff --git a/test/integ/connection/authentication.py b/test/integ/connection/authentication.py index ee7bb32..4f1d504 100644 --- a/test/integ/connection/authentication.py +++ b/test/integ/connection/authentication.py @@ -32,11 +32,9 @@ def _can_authenticate(auth_type): Checks if a given authentication method can authenticate to our control socket. - Arguments: - auth_type (stem.connection.AuthMethod) - authentication method to check + :param stem.connection.AuthMethod auth_type: authentication method to check - Returns: - bool that's True if we should be able to authenticate and False otherwise + :returns: bool that's True if we should be able to authenticate and False otherwise """ runner = test.runner.get_runner() @@ -59,11 +57,9 @@ def _get_auth_failure_message(auth_type): authentication fails. Note that this test will need to be updated if tor changes its rejection reponse. - Arguments: - auth_type (stem.connection.AuthMethod) - authentication method to check + :param stem.connection.AuthMethod auth_type: authentication method to check - Returns: - string with the rejection message that tor would provide + :returns: string with the rejection message that tor would provide """ tor_options = test.runner.get_runner().get_options() @@ -200,9 +196,6 @@ class TestAuthenticate(unittest.TestCase): individually. """ - - - runner = test.runner.get_runner() tor_options = runner.get_options() is_cookie_only = test.runner.Torrc.COOKIE in tor_options and not test.runner.Torrc.PASSWORD in tor_options @@ -349,14 +342,11 @@ class TestAuthenticate(unittest.TestCase): not then we check that this gives a message that we'd expect then raises the exception. - Arguments: - auth_type (stem.connection.AuthMethod) - method by which we should - authentiate to the control socket - auth_arg (str) - argument to be passed to the authentication function - check_message (bool) - checks that failure messages are what we'd expect + :param stem.connection.AuthMethod auth_type: method by which we should authentiate to the control socket + :param str auth_arg: argument to be passed to the authentication function + :param bool check_message: checks that failure messages are what we'd expect - Raises: - stem.connection.AuthenticationFailure if the authentication fails + :raises: :class:`stem.connection.AuthenticationFailure` if the authentication fails """ with test.runner.get_runner().get_tor_socket(False) as control_socket: diff --git a/test/mocking.py b/test/mocking.py index f17dcc9..290393e 100644 --- a/test/mocking.py +++ b/test/mocking.py @@ -2,23 +2,25 @@ Helper functions for creating mock objects and monkey patching to help with testing. With python's builtin unit testing framework the setUp and test functions set up mocking, which is then reverted in the tearDown method by -calling 'revert_mocking'. - -mock - replaces a function with an alternative implementation -revert_mocking - reverts any changes made by the mock function -get_real_function - provides the non-mocked version of a function - -Mocking Functions - no_op - does nothing - return_value - returns a given value - return_true - returns True - return_false - returns False - return_none - returns None - raise_exception - raises an exception when called - -Instance Constructors - get_message - stem.socket.ControlMessage - get_protocolinfo_response - stem.response.protocolinfo.ProtocolInfoResponse +calling :func:`test.mocking.revert_mocking`. + +:: + + mock - replaces a function with an alternative implementation + revert_mocking - reverts any changes made by the mock function + get_real_function - provides the non-mocked version of a function + + Mocking Functions + no_op - does nothing + return_value - returns a given value + return_true - returns True + return_false - returns False + return_none - returns None + raise_exception - raises an exception when called + + Instance Constructors + get_message - stem.socket.ControlMessage + get_protocolinfo_response - stem.response.protocolinfo.ProtocolInfoResponse """ import inspect @@ -63,8 +65,7 @@ def support_with(obj): methods to the object. The __enter__ provides the object itself and __exit__ does nothing. - Arguments: - obj (object) - object to support the 'with' keyword + :param object obj: object to support the 'with' keyword """ obj.__dict__["__enter__"] = return_value(obj) @@ -75,9 +76,8 @@ def mock(target, mock_call): Mocks the given function, saving the initial implementation so it can be reverted later. - Arguments: - target (function) - function to be mocked - mock_call (functor) - mocking to replace the function with + :param function target: function to be mocked + :param functor mock_call: mocking to replace the function with """ # Builtin functions need special care because the builtin_function_or_method @@ -120,10 +120,9 @@ def mock_method(target_class, method_name, mock_call): Mocks the given class method in a similar fasion as what mock() does for functions. - Arguments: - target_class (class) - class with the method we want to mock - method_name (str) - name of the method to be mocked - mock_call (functor) - mocking to replace the method with + :param class target_class: class with the method we want to mock + :param str method_name: name of the method to be mocked + :param functor mock_call: mocking to replace the method with """ # Ideally callers could call us with just the method, for instance like... @@ -179,11 +178,9 @@ def get_real_function(function): Provides the original, non-mocked implementation for a function or method. This simply returns the current implementation if it isn't being mocked. - Arguments: - function (function) - function to look up the original implementation of + :param function function: function to look up the original implementation of - Returns: - original implementation of the function + :returns: original implementation of the function """ if "mock_id" in function.__dict__: @@ -196,15 +193,14 @@ def get_message(content, reformat = True): """ Provides a ControlMessage with content modified to be parsable. This makes the following changes unless 'reformat' is false... - - ensures the content ends with a newline - - newlines are replaced with a carrage return and newline pair - Arguments: - content (str) - base content for the controller message - reformat (str) - modifies content to be more accomidateing to being parsed + * ensures the content ends with a newline + * newlines are replaced with a carrage return and newline pair + + :param str content: base content for the controller message + :param str reformat: modifies content to be more accomidateing to being parsed - Returns: - stem.socket.ControlMessage instance + :returns: stem.socket.ControlMessage instance """ if reformat: @@ -219,11 +215,9 @@ def get_protocolinfo_response(**attributes): base instance is minimal, with its version set to one and everything else left with the default. - Arguments: - attributes (dict) - attributes to customize the response with + :param dict attributes: attributes to customize the response with - Returns: - stem.response.protocolinfo.ProtocolInfoResponse instance + :returns: stem.response.protocolinfo.ProtocolInfoResponse instance """ protocolinfo_response = get_message("250-PROTOCOLINFO 1\n250 OK") diff --git a/test/output.py b/test/output.py index db692af..bf7de7e 100644 --- a/test/output.py +++ b/test/output.py @@ -79,12 +79,10 @@ def apply_filters(testing_output, *filters): output is either a string with the new content or None if the line should be omitted. - Arguments: - testing_output (str) - output from the unit testing - filters (list) - functors to be applied to each line of the results + :param str testing_output: output from the unit testing + :param list filters: functors to be applied to each line of the results - Returns: - str with the processed test results + :returns: str with the processed test results """ results = [] @@ -176,8 +174,7 @@ class ErrorTracker: in which the user needs to look for failures. In practice this is mostly used to specify the integ target we're running under. - Arguments: - category (str) - category to label errors as being under + :param str category: category to label errors as being under """ self._category = category diff --git a/test/runner.py b/test/runner.py index ebbd55b..8c01c3e 100644 --- a/test/runner.py +++ b/test/runner.py @@ -3,32 +3,34 @@ Runtime context for the integration tests. This is used both by the test runner to start and stop tor, and by the integration tests themselves for information about the tor test instance they're running against. -RunnerStopped - Runner doesn't have an active tor instance -TorInaccessable - Tor can't be queried for the information +:: -require_control - skips the test unless tor provides a controller endpoint -require_version - skips the test unless we meet a tor version requirement -exercise_controller - basic sanity check that a controller connection can be used - -get_runner - Singleton for fetching our runtime context. -Runner - Runtime context for our integration tests. - |- start - prepares and starts a tor instance for our tests to run against - |- stop - stops our tor instance and cleans up any temporary files - |- is_running - checks if our tor test instance is running - |- is_accessible - checks if our tor instance can be connected to - |- is_ptraceable - checks if DisableDebuggerAttachment is set - |- get_options - custom torrc options used for our test instance - |- get_test_dir - testing directory path - |- get_torrc_path - path to our tor instance's torrc - |- get_torrc_contents - contents of our tor instance's torrc - |- get_auth_cookie_path - path for our authentication cookie if we have one - |- get_tor_cwd - current working directory of our tor process - |- get_chroot - provides the path of our emulated chroot if we have one - |- get_pid - process id of our tor process - |- get_tor_socket - provides a socket to our test instance - |- get_tor_controller - provides a controller for our test instance - |- get_tor_version - provides the version of tor we're running against - +- get_tor_command - provides the command used to start tor + RunnerStopped - Runner doesn't have an active tor instance + TorInaccessable - Tor can't be queried for the information + + require_control - skips the test unless tor provides a controller endpoint + require_version - skips the test unless we meet a tor version requirement + exercise_controller - basic sanity check that a controller connection can be used + + get_runner - Singleton for fetching our runtime context. + Runner - Runtime context for our integration tests. + |- start - prepares and starts a tor instance for our tests to run against + |- stop - stops our tor instance and cleans up any temporary files + |- is_running - checks if our tor test instance is running + |- is_accessible - checks if our tor instance can be connected to + |- is_ptraceable - checks if DisableDebuggerAttachment is set + |- get_options - custom torrc options used for our test instance + |- get_test_dir - testing directory path + |- get_torrc_path - path to our tor instance's torrc + |- get_torrc_contents - contents of our tor instance's torrc + |- get_auth_cookie_path - path for our authentication cookie if we have one + |- get_tor_cwd - current working directory of our tor process + |- get_chroot - provides the path of our emulated chroot if we have one + |- get_pid - process id of our tor process + |- get_tor_socket - provides a socket to our test instance + |- get_tor_controller - provides a controller for our test instance + |- get_tor_version - provides the version of tor we're running against + +- get_tor_command - provides the command used to start tor """ import os @@ -91,18 +93,15 @@ RAN_TESTS = [] class RunnerStopped(Exception): "Raised when we try to use a Runner that doesn't have an active tor instance" - pass class TorInaccessable(Exception): "Raised when information is needed from tor but the instance we have is inaccessable" - pass def require_control(test_case): """ Skips the test unless tor provides an endpoint for controllers to attach to. - Arguments: - test_case (unittest.TestCase) - test being ran + :param unittest.TestCase test_case: test being ran """ if not test.runner.get_runner().is_accessible(): @@ -112,9 +111,8 @@ def require_version(test_case, req_version): """ Skips the test unless we meet the required version. - Arguments: - test_case (unittest.TestCase) - test being ran - req_version (stem.version.Version) - required tor version for the test + :param unittest.TestCase test_case: test being ran + :param stem.version.Version req_version: required tor version for the test """ if get_runner().get_tor_version() < req_version: @@ -124,11 +122,10 @@ def only_run_once(test_case, test_name): """ Skips the test if it has ran before. If it hasn't then flags it as being ran. This is useful to prevent lengthy tests that are independent of integ targets - from being run repeatedly with RUN_ALL. + from being run repeatedly with ``RUN_ALL``. - Arguments: - test_case (unittest.TestCase) - test being ran - test_name (str) - name of the test being ran + :param unittest.TestCase test_case: test being ran + :param str test_name: name of the test being ran """ if (test_case, test_name) in RAN_TESTS: @@ -139,12 +136,11 @@ def only_run_once(test_case, test_name): def exercise_controller(test_case, controller): """ Checks that we can now use the socket by issuing a 'GETINFO config-file' - query. + query. Controller can be either a :class:`stem.socket.ControlSocket` or + :class:`stem.control.BaseController`. - Arguments: - test_case (unittest.TestCase) - test being ran - controller (stem.socket.ControlSocket or stem.control.BaseController) - - tor controller connection to be authenticated + :param unittest.TestCase test_case: test being ran + :param controller: tor controller connection to be authenticated """ runner = get_runner() @@ -161,6 +157,8 @@ def exercise_controller(test_case, controller): def get_runner(): """ Singleton for the runtime context of integration tests. + + :returns: :class:`test.runner.Runner` with context for our integration tests """ global INTEG_RUNNER @@ -203,12 +201,10 @@ class Runner: Makes temporary testing resources and starts tor, blocking until it completes. - Arguments: - tor_cmd (str) - command to start tor with - extra_torrc_opts (list) - additional torrc options for our test instance + :param str tor_cmd: command to start tor with + :param list extra_torrc_opts: additional torrc options for our test instance - Raises: - OSError if unable to run test preparations or start tor + :raises: OSError if unable to run test preparations or start tor """ with self._runner_lock: @@ -310,8 +306,7 @@ class Runner: """ Checks if we're running a tor test instance and that it's alive. - Returns: - True if we have a running tor test instance, False otherwise + :returns: True if we have a running tor test instance, False otherwise """ with self._runner_lock: @@ -329,8 +324,7 @@ class Runner: """ Checks if our tor instance has a method of being connected to or not. - Returns: - True if tor has a control socket or port, False otherwise + :returns: True if tor has a control socket or port, False otherwise """ return Torrc.PORT in self._custom_opts or Torrc.SOCKET in self._custom_opts @@ -338,11 +332,10 @@ class Runner: def is_ptraceable(self): """ Checks if tor's 'DisableDebuggerAttachment' option is set. This feature has - a lot of adverse side effects as per... - https://trac.torproject.org/projects/tor/ticket/3313 + a lot of adverse side effects + (`ticket <https://trac.torproject.org/projects/tor/ticket/3313>`_). - Returns: - True if debugger attachment is disallowd, False otherwise + :returns: True if debugger attachment is disallowd, False otherwise """ # If we're running a tor version where ptrace is disabled and we didn't @@ -356,8 +349,7 @@ class Runner: """ Provides the custom torrc options our tor instance is running with. - Returns: - list of Torrc enumerations being used by our test instance + :returns: list of Torrc enumerations being used by our test instance """ return self._custom_opts @@ -366,14 +358,11 @@ class Runner: """ Provides the absolute path for our testing directory or a file within it. - Arguments: - resource (str) - file within our test directory to provide the path for + :param str resource: file within our test directory to provide the path for - Returns: - str with our test direcectory's absolute path or that of a file within it + :returns: str with our test direcectory's absolute path or that of a file within it - Raises: - RunnerStopped if we aren't running + :raises: :class:`test.runner.RunnerStopped` if we aren't running """ if resource: @@ -385,15 +374,11 @@ class Runner: """ Provides the absolute path for where our testing torrc resides. - Arguments: - ignore_chroot (bool) - provides the real path, rather than the one that - tor expects if True + :param bool ignore_chroot: provides the real path, rather than the one that tor expects if True - Returns: - str with our torrc path + :returns: str with our torrc path - Raises: - RunnerStopped if we aren't running + :raises: RunnerStopped if we aren't running """ test_dir = self._get("_test_dir") @@ -408,11 +393,9 @@ class Runner: """ Provides the contents of our torrc. - Returns: - str with the contents of our torrc, lines are newline separated + :returns: str with the contents of our torrc, lines are newline separated - Raises: - RunnerStopped if we aren't running + :raises: :class:`test.runner.RunnerStopped` if we aren't running """ return self._get("_torrc_contents") @@ -423,11 +406,9 @@ class Runner: If running with an emulated chroot this is uneffected, still providing the real path. - Returns: - str with our auth cookie path + :returns: str with our auth cookie path - Raises: - RunnerStopped if we aren't running + :raises: :class:`test.runner.RunnerStopped` if we aren't running """ test_dir = self._get("_test_dir") @@ -445,8 +426,7 @@ class Runner: Provides the path we're using to emulate a chroot environment. This is None if we aren't emulating a chroot setup. - Returns: - str with the path of our emulated chroot + :returns: str with the path of our emulated chroot """ return self._chroot_path @@ -455,11 +435,9 @@ class Runner: """ Provides the process id of the tor process. - Returns: - int pid for the tor process + :returns: int pid for the tor process - Raises: - RunnerStopped if we aren't running + :raises: :class:`test.runner.RunnerStopped` if we aren't running """ tor_process = self._get("_tor_process") @@ -469,14 +447,11 @@ class Runner: """ Provides a socket connected to our tor test instance. - Arguments: - authenticate (bool) - if True then the socket is authenticated + :param bool authenticate: if True then the socket is authenticated - Returns: - stem.socket.ControlSocket connected with our testing instance + :returns: :class:`stem.socket.ControlSocket` connected with our testing instance - Raises: - TorInaccessable if tor can't be connected to + :raises: :class:`test.runner.TorInaccessable` if tor can't be connected to """ if Torrc.PORT in self._custom_opts: @@ -494,14 +469,11 @@ class Runner: """ Provides a controller connected to our tor test instance. - Arguments: - authenticate (bool) - if True then the socket is authenticated + :param bool authenticate: if True then the socket is authenticated - Returns: - stem.socket.Controller connected with our testing instance + :returns: :class:`stem.socket.Controller` connected with our testing instance - Raises: - TorInaccessable if tor can't be connected to + :raises: :class: `test.runner.TorInaccessable` if tor can't be connected to """ control_socket = self.get_tor_socket(authenticate) @@ -511,8 +483,7 @@ class Runner: """ Queries our test instance for tor's version. - Returns: - stem.version.Version for our test instance + :returns: :class:`stem.version.Version` for our test instance """ try: @@ -544,14 +515,11 @@ class Runner: Fetches one of our attributes in a thread safe manner, raising if we aren't running. - Arguments: - attr (str) - class variable that we want to fetch + :param str attr: class variable that we want to fetch - Returns: - value of the fetched variable + :returns: value of the fetched variable - Raises: - RunnerStopped if we aren't running + :returns: :class:`test.runner.RunnerStopped` if we aren't running """ with self._runner_lock: @@ -563,8 +531,7 @@ class Runner: """ Makes a temporary runtime resources of our integration test instance. - Raises: - OSError if unsuccessful + :raises: OSError if unsuccessful """ # makes a temporary data directory if needed @@ -648,12 +615,9 @@ class Runner: Initializes a tor process. This blocks until initialization completes or we error out. - Arguments: - tor_cmd (str) - command to start tor with + :param str tor_cmd: command to start tor with - Raises: - OSError if we either fail to create the tor process or reached a timeout - without success + :raises: OSError if we either fail to create the tor process or reached a timeout without success """ test.output.print_line("Starting tor...\n", *STATUS_ATTR) diff --git a/test/unit/control/__init__.py b/test/unit/control/__init__.py deleted file mode 100644 index 448a597..0000000 --- a/test/unit/control/__init__.py +++ /dev/null @@ -1,6 +0,0 @@ -""" -Unit tests for stem.control. -""" - -__all__ = ["controller"] - diff --git a/test/unit/descriptor/extrainfo_descriptor.py b/test/unit/descriptor/extrainfo_descriptor.py index 3bfff70..888180c 100644 --- a/test/unit/descriptor/extrainfo_descriptor.py +++ b/test/unit/descriptor/extrainfo_descriptor.py @@ -22,12 +22,10 @@ def _make_descriptor(attr = None, exclude = None): """ Constructs a minimal extrainfo descriptor with the given attributes. - Arguments: - attr (dict) - keyword/value mappings to be included in the descriptor - exclude (list) - mandatory keywords to exclude from the descriptor + :param dict attr: keyword/value mappings to be included in the descriptor + :param list exclude: mandatory keywords to exclude from the descriptor - Returns: - str with customized descriptor content + :returns: str with customized descriptor content """ descriptor_lines = [] diff --git a/test/unit/descriptor/server_descriptor.py b/test/unit/descriptor/server_descriptor.py index 6ad92b2..3bb2c7a 100644 --- a/test/unit/descriptor/server_descriptor.py +++ b/test/unit/descriptor/server_descriptor.py @@ -37,13 +37,11 @@ def _make_descriptor(attr = None, exclude = None, is_bridge = False): """ Constructs a minimal server descriptor with the given attributes. - Arguments: - attr (dict) - keyword/value mappings to be included in the descriptor - exclude (list) - mandatory keywords to exclude from the descriptor - is_bridge (bool) - minimal descriptor is for a bridge if True, relay otherwise + :param dict attr: keyword/value mappings to be included in the descriptor + :param list exclude: mandatory keywords to exclude from the descriptor + :param bool is_bridge: minimal descriptor is for a bridge if True, relay otherwise - Returns: - str with customized descriptor content + :returns: str with customized descriptor content """ descriptor_lines = []

1 0

[stem/master] Separating relay and bridge extra-info descriptors
by atagar＠torproject.org 10 Jun '12

10 Jun '12

commit 7947d69d4e20ca402e9d1d35fe6e62012d5e61fe Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Jun 10 12:31:14 2012 -0700 Separating relay and bridge extra-info descriptors Creating separate classes for relay and bridge extra-info descriptors. At present they're identical to their common parent (ExtraInfoDescriptor), adding their differences next. --- stem/descriptor/__init__.py | 6 ++++-- stem/descriptor/extrainfo_descriptor.py | 25 ++++++++++++++++++------- 2 files changed, 22 insertions(+), 9 deletions(-) diff --git a/stem/descriptor/__init__.py b/stem/descriptor/__init__.py index 37f9ec7..e4f23e5 100644 --- a/stem/descriptor/__init__.py +++ b/stem/descriptor/__init__.py @@ -70,8 +70,10 @@ def parse_file(path, descriptor_file): desc = stem.descriptor.server_descriptor.RelayDescriptor(descriptor_file.read()) elif first_line == "@type bridge-server-descriptor 1.0": desc = stem.descriptor.server_descriptor.BridgeDescriptor(descriptor_file.read()) - elif first_line in ("@type extra-info 1.0", "@type bridge-extra-info 1.0"): - desc = stem.descriptor.extrainfo_descriptor.ExtraInfoDescriptor(descriptor_file.read()) + elif first_line in ("@type bridge-extra-info 1.0"): + desc = stem.descriptor.extrainfo_descriptor.RelayExtraInfoDescriptor(descriptor_file.read()) + elif first_line in ("@type extra-info 1.0"): + desc = stem.descriptor.extrainfo_descriptor.BridgeExtraInfoDescriptor(descriptor_file.read()) if desc: desc._set_path(path) diff --git a/stem/descriptor/extrainfo_descriptor.py b/stem/descriptor/extrainfo_descriptor.py index 9fbdd1d..03c7a37 100644 --- a/stem/descriptor/extrainfo_descriptor.py +++ b/stem/descriptor/extrainfo_descriptor.py @@ -42,6 +42,9 @@ Extra-info descriptors are available from a few sources... parse_file - Iterates over the extra-info descriptors in a file. ExtraInfoDescriptor - Tor extra-info descriptor. + | |- RelayExtraInfoDescriptor - Extra-info descriptor for a relay. + | +- BridgeExtraInfoDescriptor - Extra-info descriptor for a bridge. + | +- get_unrecognized_lines - lines with unrecognized content """ @@ -270,13 +273,9 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor): def __init__(self, raw_contents, validate = True): """ - Extra-info descriptor constructor, created from a relay's extra-info - content (as provided by "GETINFO extra-info/digest/*", cached contents, and - metrics). - - By default this validates the descriptor's content as it's parsed. This - validation can be disables to either improve performance or be accepting of - malformed data. + Extra-info descriptor constructor. By default this validates the + descriptor's content as it's parsed. This validation can be disables to + either improve performance or be accepting of malformed data. :param str raw_contents: extra-info content provided by the relay :param bool validate: checks the validity of the extra-info descriptor if True, skips these checks otherwise @@ -683,3 +682,15 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor): else: self._unrecognized_lines.append(line) +class RelayExtraInfoDescriptor(ExtraInfoDescriptor): + """ + Relay extra-info descriptor, constructed from data such as that provided by + "GETINFO extra-info/digest/*", cached descriptors, and metrics + (`specification <https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt>`_). + """ + +class BridgeExtraInfoDescriptor(ExtraInfoDescriptor): + """ + Bridge extra-info descriptor (`specification <https://metrics.torproject.org/formats.html#bridgedesc>`_) + """ +

1 0