Skip to content

Add ADB reverse port forwarding support #305

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rmarinho wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add ADB reverse port forwarding support #305

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions src/Xamarin.Android.Tools.AndroidSdk/PublicAPI/net10.0/PublicAPI.Unshipped.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,3 +145,13 @@ Xamarin.Android.Tools.AvdManagerRunner.AvdManagerRunner(string! avdManagerPath,
Xamarin.Android.Tools.AvdManagerRunner.GetOrCreateAvdAsync(string! name, string! systemImage, string? deviceProfile = null, bool force = false, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<Xamarin.Android.Tools.AvdInfo!>!
Xamarin.Android.Tools.AvdManagerRunner.DeleteAvdAsync(string! name, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
Xamarin.Android.Tools.AvdManagerRunner.ListAvdsAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyList<Xamarin.Android.Tools.AvdInfo!>!>!
Xamarin.Android.Tools.AdbReversePortRule
Xamarin.Android.Tools.AdbReversePortRule.AdbReversePortRule() -> void
Xamarin.Android.Tools.AdbReversePortRule.Local.get -> string!
Xamarin.Android.Tools.AdbReversePortRule.Local.init -> void
Xamarin.Android.Tools.AdbReversePortRule.Remote.get -> string!
Xamarin.Android.Tools.AdbReversePortRule.Remote.init -> void
Comment on lines +149 to +153
Copy link
Member

@jonathanpeppers jonathanpeppers Mar 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I question the API design:

public class AdbReversePortRule
{
    public string Remote { get; init; }  // e.g. "tcp:5000"
    public string Local { get; init; }   // e.g. "tcp:5000"
}

C# is strongly typed, we shouldn't be using strings like tcp:5000.

We should have an enum as a separate property to specify if it is tcp (and fill in the other options in the enum).

Then we should have an int property for the port.

Can't you also do adb forward?

So should this be:

public record AdbPortAndProtocol (/* this is the enum*/ AdbProtocol Protocol, int Port);

public record AdbReverseRule (AdbPortAndProtocol Remote, AdbPortAndProtocol Local);

public record AdbForwardingRule (AdbPortAndProtocol Remote, AdbPortAndProtocol Local);

But then I don't know if I like having two records for reverse & forward. Maybe it should be a single record + another enum that says if it is Forward/Reverse.

virtual Xamarin.Android.Tools.AdbRunner.ListReversePortsAsync(string! serial, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyList<Xamarin.Android.Tools.AdbReversePortRule!>!>!
virtual Xamarin.Android.Tools.AdbRunner.RemoveAllReversePortsAsync(string! serial, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
virtual Xamarin.Android.Tools.AdbRunner.RemoveReversePortAsync(string! serial, int remotePort, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
virtual Xamarin.Android.Tools.AdbRunner.ReversePortAsync(string! serial, int remotePort, int localPort, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
10 changes: 10 additions & 0 deletions src/Xamarin.Android.Tools.AndroidSdk/PublicAPI/netstandard2.0/PublicAPI.Unshipped.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,3 +145,13 @@ Xamarin.Android.Tools.AvdManagerRunner.AvdManagerRunner(string! avdManagerPath,
Xamarin.Android.Tools.AvdManagerRunner.GetOrCreateAvdAsync(string! name, string! systemImage, string? deviceProfile = null, bool force = false, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<Xamarin.Android.Tools.AvdInfo!>!
Xamarin.Android.Tools.AvdManagerRunner.DeleteAvdAsync(string! name, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
Xamarin.Android.Tools.AvdManagerRunner.ListAvdsAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyList<Xamarin.Android.Tools.AvdInfo!>!>!
Xamarin.Android.Tools.AdbReversePortRule
Xamarin.Android.Tools.AdbReversePortRule.AdbReversePortRule() -> void
Xamarin.Android.Tools.AdbReversePortRule.Local.get -> string!
Xamarin.Android.Tools.AdbReversePortRule.Local.init -> void
Xamarin.Android.Tools.AdbReversePortRule.Remote.get -> string!
Xamarin.Android.Tools.AdbReversePortRule.Remote.init -> void
virtual Xamarin.Android.Tools.AdbRunner.ListReversePortsAsync(string! serial, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyList<Xamarin.Android.Tools.AdbReversePortRule!>!>!
virtual Xamarin.Android.Tools.AdbRunner.RemoveAllReversePortsAsync(string! serial, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
virtual Xamarin.Android.Tools.AdbRunner.RemoveReversePortAsync(string! serial, int remotePort, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
virtual Xamarin.Android.Tools.AdbRunner.ReversePortAsync(string! serial, int remotePort, int localPort, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
20 changes: 20 additions & 0 deletions src/Xamarin.Android.Tools.AndroidSdk/Runners/AdbReversePortRule.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

namespace Xamarin.Android.Tools;

/// <summary>
/// Represents a single ADB reverse port forwarding rule as reported by 'adb reverse --list'.
/// </summary>
public class AdbReversePortRule
{
/// <summary>
/// The remote (device-side) socket spec, e.g. "tcp:5000".
/// </summary>
public string Remote { get; init; } = string.Empty;

/// <summary>
/// The local (host-side) socket spec, e.g. "tcp:5000".
/// </summary>
public string Local { get; init; } = string.Empty;
}
102 changes: 102 additions & 0 deletions src/Xamarin.Android.Tools.AndroidSdk/Runners/AdbRunner.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,108 @@ public async Task StopEmulatorAsync (string serial, CancellationToken cancellati
ProcessUtils.ThrowIfFailed (exitCode, $"adb -s {serial} emu kill", stderr);
}

/// <summary>
/// Sets up reverse port forwarding from the device to the host via
/// 'adb -s &lt;serial&gt; reverse tcp:&lt;remotePort&gt; tcp:&lt;localPort&gt;'.
/// This allows the device to connect to a service on the host machine through the specified port.
/// </summary>
public virtual async Task ReversePortAsync (string serial, int remotePort, int localPort, CancellationToken cancellationToken = default)
{
if (string.IsNullOrWhiteSpace (serial))
throw new ArgumentException ("Serial must not be empty.", nameof (serial));
if (remotePort <= 0 || remotePort > 65535)
throw new ArgumentOutOfRangeException (nameof (remotePort), remotePort, "Port must be between 1 and 65535.");
if (localPort <= 0 || localPort > 65535)
throw new ArgumentOutOfRangeException (nameof (localPort), localPort, "Port must be between 1 and 65535.");

var remoteSpec = $"tcp:{remotePort}";
var localSpec = $"tcp:{localPort}";
var psi = ProcessUtils.CreateProcessStartInfo (adbPath, "-s", serial, "reverse", remoteSpec, localSpec);
using var stderr = new StringWriter ();
var exitCode = await ProcessUtils.StartProcess (psi, null, stderr, cancellationToken, environmentVariables).ConfigureAwait (false);
ProcessUtils.ThrowIfFailed (exitCode, $"adb -s {serial} reverse {remoteSpec} {localSpec}", stderr);
}

/// <summary>
/// Removes a specific reverse port forwarding rule via
/// 'adb -s &lt;serial&gt; reverse --remove tcp:&lt;remotePort&gt;'.
/// </summary>
public virtual async Task RemoveReversePortAsync (string serial, int remotePort, CancellationToken cancellationToken = default)
{
if (string.IsNullOrWhiteSpace (serial))
throw new ArgumentException ("Serial must not be empty.", nameof (serial));
if (remotePort <= 0 || remotePort > 65535)
throw new ArgumentOutOfRangeException (nameof (remotePort), remotePort, "Port must be between 1 and 65535.");

var remoteSpec = $"tcp:{remotePort}";
var psi = ProcessUtils.CreateProcessStartInfo (adbPath, "-s", serial, "reverse", "--remove", remoteSpec);
using var stderr = new StringWriter ();
var exitCode = await ProcessUtils.StartProcess (psi, null, stderr, cancellationToken, environmentVariables).ConfigureAwait (false);
ProcessUtils.ThrowIfFailed (exitCode, $"adb -s {serial} reverse --remove {remoteSpec}", stderr);
}

/// <summary>
/// Removes all reverse port forwarding rules via
/// 'adb -s &lt;serial&gt; reverse --remove-all'.
/// </summary>
public virtual async Task RemoveAllReversePortsAsync (string serial, CancellationToken cancellationToken = default)
{
if (string.IsNullOrWhiteSpace (serial))
throw new ArgumentException ("Serial must not be empty.", nameof (serial));

var psi = ProcessUtils.CreateProcessStartInfo (adbPath, "-s", serial, "reverse", "--remove-all");
using var stderr = new StringWriter ();
var exitCode = await ProcessUtils.StartProcess (psi, null, stderr, cancellationToken, environmentVariables).ConfigureAwait (false);
ProcessUtils.ThrowIfFailed (exitCode, $"adb -s {serial} reverse --remove-all", stderr);
}

/// <summary>
/// Lists all active reverse port forwarding rules via
/// 'adb -s &lt;serial&gt; reverse --list'.
/// </summary>
public virtual async Task<IReadOnlyList<AdbReversePortRule>> ListReversePortsAsync (string serial, CancellationToken cancellationToken = default)
{
if (string.IsNullOrWhiteSpace (serial))
throw new ArgumentException ("Serial must not be empty.", nameof (serial));

using var stdout = new StringWriter ();
using var stderr = new StringWriter ();
var psi = ProcessUtils.CreateProcessStartInfo (adbPath, "-s", serial, "reverse", "--list");
var exitCode = await ProcessUtils.StartProcess (psi, stdout, stderr, cancellationToken, environmentVariables).ConfigureAwait (false);
ProcessUtils.ThrowIfFailed (exitCode, $"adb -s {serial} reverse --list", stderr);

return ParseReverseListOutput (stdout.ToString ().Split ('\n'));
}

/// <summary>
/// Parses the output of 'adb reverse --list'.
/// Each line is "(reverse) &lt;remote&gt; &lt;local&gt;", e.g. "(reverse) tcp:5000 tcp:5000".
/// </summary>
internal static IReadOnlyList<AdbReversePortRule> ParseReverseListOutput (IEnumerable<string> lines)
{
var rules = new List<AdbReversePortRule> ();

foreach (var line in lines) {
var trimmed = line.Trim ();
if (string.IsNullOrEmpty (trimmed))
continue;

// Expected format: "(reverse) tcp:5000 tcp:5000"
if (!trimmed.StartsWith ("(reverse)", StringComparison.Ordinal))
continue;

var parts = trimmed.Substring ("(reverse)".Length).Trim ().Split (new [] { ' ' }, StringSplitOptions.RemoveEmptyEntries);
if (parts.Length >= 2) {
rules.Add (new AdbReversePortRule {
Remote = parts [0],
Local = parts [1],
});
}
}

return rules;
}

/// <summary>
/// Parses the output lines from 'adb devices -l'.
/// Accepts an <see cref="IEnumerable{T}"/> to avoid allocating a joined string.
Expand Down
167 changes: 167 additions & 0 deletions tests/Xamarin.Android.Tools.AndroidSdk-Tests/AdbRunnerTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -655,4 +655,171 @@ public void WaitForDeviceAsync_ZeroTimeout_ThrowsArgumentOutOfRange ()
Assert.ThrowsAsync<System.ArgumentOutOfRangeException> (
async () => await runner.WaitForDeviceAsync (timeout: System.TimeSpan.Zero));
}

// --- ParseReverseListOutput tests ---
// Consumer: MAUI DevTools (via ListReversePortsAsync), vscode-maui ServiceHub replacement

[Test]
public void ParseReverseListOutput_SingleRule ()
{
var output = new [] {
"(reverse) tcp:5000 tcp:5000",
};

var rules = AdbRunner.ParseReverseListOutput (output);

Assert.AreEqual (1, rules.Count);
Assert.AreEqual ("tcp:5000", rules [0].Remote);
Assert.AreEqual ("tcp:5000", rules [0].Local);
}

[Test]
public void ParseReverseListOutput_MultipleRules ()
{
var output = new [] {
"(reverse) tcp:5000 tcp:5000",
"(reverse) tcp:8081 tcp:8081",
"(reverse) tcp:19000 tcp:19001",
};

var rules = AdbRunner.ParseReverseListOutput (output);

Assert.AreEqual (3, rules.Count);
Assert.AreEqual ("tcp:5000", rules [0].Remote);
Assert.AreEqual ("tcp:5000", rules [0].Local);
Assert.AreEqual ("tcp:8081", rules [1].Remote);
Assert.AreEqual ("tcp:8081", rules [1].Local);
Assert.AreEqual ("tcp:19000", rules [2].Remote);
Assert.AreEqual ("tcp:19001", rules [2].Local);
}

[Test]
public void ParseReverseListOutput_EmptyOutput ()
{
var output = new [] { "", " " };
var rules = AdbRunner.ParseReverseListOutput (output);
Assert.AreEqual (0, rules.Count);
}

[Test]
public void ParseReverseListOutput_NoLines ()
{
var rules = AdbRunner.ParseReverseListOutput (Array.Empty<string> ());
Assert.AreEqual (0, rules.Count);
}

[Test]
public void ParseReverseListOutput_IgnoresNonReverseLines ()
{
var output = new [] {
"some random header",
"(reverse) tcp:5000 tcp:5000",
"* daemon started successfully",
"(reverse) tcp:8081 tcp:8081",
"",
};

var rules = AdbRunner.ParseReverseListOutput (output);

Assert.AreEqual (2, rules.Count);
Assert.AreEqual ("tcp:5000", rules [0].Remote);
Assert.AreEqual ("tcp:8081", rules [1].Remote);
}

[Test]
public void ParseReverseListOutput_MalformedLine_InsufficientParts ()
{
var output = new [] {
"(reverse) tcp:5000", // missing local spec
};

var rules = AdbRunner.ParseReverseListOutput (output);
Assert.AreEqual (0, rules.Count);
}

[Test]
public void ParseReverseListOutput_DifferentRemoteAndLocalPorts ()
{
var output = new [] {
"(reverse) tcp:8080 tcp:3000",
};

var rules = AdbRunner.ParseReverseListOutput (output);

Assert.AreEqual (1, rules.Count);
Assert.AreEqual ("tcp:8080", rules [0].Remote);
Assert.AreEqual ("tcp:3000", rules [0].Local);
}

// --- ReversePortAsync parameter validation tests ---

[Test]
public void ReversePortAsync_EmptySerial_ThrowsArgumentException ()
{
var runner = new AdbRunner ("/fake/sdk/platform-tools/adb");
Assert.ThrowsAsync<System.ArgumentException> (
async () => await runner.ReversePortAsync ("", 5000, 5000));
}

[Test]
public void ReversePortAsync_ZeroRemotePort_ThrowsArgumentOutOfRange ()
{
var runner = new AdbRunner ("/fake/sdk/platform-tools/adb");
Assert.ThrowsAsync<System.ArgumentOutOfRangeException> (
async () => await runner.ReversePortAsync ("emulator-5554", 0, 5000));
}

[Test]
public void ReversePortAsync_NegativeLocalPort_ThrowsArgumentOutOfRange ()
{
var runner = new AdbRunner ("/fake/sdk/platform-tools/adb");
Assert.ThrowsAsync<System.ArgumentOutOfRangeException> (
async () => await runner.ReversePortAsync ("emulator-5554", 5000, -1));
}

[Test]
public void ReversePortAsync_PortAbove65535_ThrowsArgumentOutOfRange ()
{
var runner = new AdbRunner ("/fake/sdk/platform-tools/adb");
Assert.ThrowsAsync<System.ArgumentOutOfRangeException> (
async () => await runner.ReversePortAsync ("emulator-5554", 70000, 5000));
}
Comment on lines +780 to +786

// --- RemoveReversePortAsync parameter validation tests ---

[Test]
public void RemoveReversePortAsync_EmptySerial_ThrowsArgumentException ()
{
var runner = new AdbRunner ("/fake/sdk/platform-tools/adb");
Assert.ThrowsAsync<System.ArgumentException> (
async () => await runner.RemoveReversePortAsync ("", 5000));
}

[Test]
public void RemoveReversePortAsync_ZeroPort_ThrowsArgumentOutOfRange ()
{
var runner = new AdbRunner ("/fake/sdk/platform-tools/adb");
Assert.ThrowsAsync<System.ArgumentOutOfRangeException> (
async () => await runner.RemoveReversePortAsync ("emulator-5554", 0));
}

// --- RemoveAllReversePortsAsync parameter validation tests ---

[Test]
public void RemoveAllReversePortsAsync_EmptySerial_ThrowsArgumentException ()
{
var runner = new AdbRunner ("/fake/sdk/platform-tools/adb");
Assert.ThrowsAsync<System.ArgumentException> (
async () => await runner.RemoveAllReversePortsAsync (""));
}

// --- ListReversePortsAsync parameter validation tests ---

[Test]
public void ListReversePortsAsync_EmptySerial_ThrowsArgumentException ()
{
var runner = new AdbRunner ("/fake/sdk/platform-tools/adb");
Assert.ThrowsAsync<System.ArgumentException> (
async () => await runner.ListReversePortsAsync (""));
}
}
Loading