Add missing cancellation token + some docs.
MODIFY
WalletWasabi/Tor/Socks5/TorSocks5Client.cs
WalletWasabi/Tor/Socks5/TorSocks5Client.cs
@@ -48,6 +48,9 @@ namespace WalletWasabi.Tor.Socks5
#region Initializers
+ /// <summary>
+ /// Establishes TCP connection with Tor's SOCKS5 server.
+ /// </summary>
public async Task ConnectAsync()
{
using (await AsyncLock.LockAsync().ConfigureAwait(false))
@@ -94,10 +97,13 @@ namespace WalletWasabi.Tor.Socks5
}
/// <summary>
- /// IsolateSOCKSAuth must be on (on by default)
- /// https://www.torproject.org/docs/tor-manual.html.en
- /// https://gitweb.torproject.org/torspec.git/tree/socks-extensions.txt#n35
+ /// Do the authentication part of Tor's SOCKS5 protocol.
/// </summary>
+ /// <param name="isolateStream">Whether random username/password should be used for authentication and thus effectively create a new Tor circuit.</param>
+ /// <remarks>Tor process must be started with enabled <c>IsolateSOCKSAuth</c> option. It's ON by default.</remarks>
+ /// <seealso href="https://www.torproject.org/docs/tor-manual.html.en"/>
+ /// <seealso href="https://linux.die.net/man/1/tor">For <c>IsolateSOCKSAuth</c> option explanation.</seealso>
+ /// <seealso href="https://gitweb.torproject.org/torspec.git/tree/socks-extensions.txt#n35"/>
public async Task HandshakeAsync(bool isolateStream = false, CancellationToken cancellationToken = default)
{
Logger.LogDebug($"> {nameof(isolateStream)}={isolateStream}");
@@ -181,10 +187,16 @@ namespace WalletWasabi.Tor.Socks5
await ConnectToDestinationAsync(host, port.Value, cancellationToken).ConfigureAwait(false);
}
- /// <param name="host">IPv4 or domain</param>
+ /// <summary>
+ /// Sends <see cref="CmdField.Connect"/> command to SOCKS5 server to instruct it to connect to
+ /// <paramref name="host"/>:<paramref name="port"/> on behalf of this client.
+ /// </summary>
+ /// <param name="host">IPv4 or domain of the destination.</param>
+ /// <param name="port">Port number of the destination.</param>
+ /// <seealso href="https://tools.ietf.org/html/rfc1928">Section 3. Procedure for TCP-based clients</seealso>
public async Task ConnectToDestinationAsync(string host, int port, CancellationToken cancellationToken = default)
{
- Logger.LogDebug($"> {nameof(host)}={host}, {nameof(port)}={port}");
+ Logger.LogDebug($"> {nameof(host)}='{host}', {nameof(port)}={port}");
host = Guard.NotNullOrEmptyOrWhitespace(nameof(host), host, true);
Guard.MinimumAndNotNull(nameof(port), port, 0);
@@ -206,7 +218,7 @@ namespace WalletWasabi.Tor.Socks5
// the reply. This must be no more than 10 seconds after detecting the
// condition that caused a failure.
DisposeTcpClient();
- Logger.LogWarning($"Connection response indicates a failure. Actual response is: '{connectionResponse.Rep}'. Request: {host}:{port}.");
+ Logger.LogWarning($"Connection response indicates a failure. Actual response is: '{connectionResponse.Rep}'. Request: '{host}:{port}'.");
throw new TorSocks5FailureResponseException(connectionResponse.Rep);
}
@@ -224,12 +236,12 @@ namespace WalletWasabi.Tor.Socks5
}
catch (OperationCanceledException)
{
- Logger.LogTrace($"Connecting to destination {host}:{port} was canceled.");
+ Logger.LogTrace($"Connecting to destination '{host}:{port}' was canceled.");
throw;
}
catch (Exception e)
{
- Logger.LogError($"Exception was thrown when connecting to destination ({host}:{port})", e);
+ Logger.LogError($"Exception was thrown when connecting to destination '{host}:{port}'.", e);
throw;
}
finally
@@ -238,22 +250,22 @@ namespace WalletWasabi.Tor.Socks5
}
}
- private async Task AssertConnectedAsync()
+ private async Task AssertConnectedAsync(CancellationToken token = default)
{
if (!IsConnected)
{
// try reconnect, maybe the server came online already
try
{
- await ConnectToDestinationAsync(RemoteEndPoint).ConfigureAwait(false);
+ await ConnectToDestinationAsync(RemoteEndPoint, token).ConfigureAwait(false);
}
catch (Exception ex) when (IsConnectionRefused(ex))
{
- throw new ConnectionException($"{nameof(TorSocks5Client)} is not connected to {RemoteEndPoint}.", ex);
+ throw new ConnectionException($"{nameof(TorSocks5Client)} is not connected to '{RemoteEndPoint}'.", ex);
}
if (!IsConnected)
{
- throw new ConnectionException($"{nameof(TorSocks5Client)} is not connected to {RemoteEndPoint}.");
+ throw new ConnectionException($"{nameof(TorSocks5Client)} is not connected to '{RemoteEndPoint}'.");
}
}
}
@@ -312,7 +324,7 @@ namespace WalletWasabi.Tor.Socks5
try
{
- await AssertConnectedAsync().ConfigureAwait(false);
+ await AssertConnectedAsync(cancellationToken).ConfigureAwait(false);
using (await AsyncLock.LockAsync().ConfigureAwait(false))
{

Add missing cancellation token + some docs.