Merge branch 'main' into docs/rust-reconnection-support

Author: thechandanbhagat

.gitignore

@@ -348,3 +348,5 @@ MigrationBackup/
 
 # Ionide (cross platform F# VS Code tools) working folder
 .ionide/
+
+*.lscache

.vscode/settings.json

@@ -3,4 +3,7 @@
         "ts"
     ],
     "rust-analyzer.cargo.features": ["connections", "vendored-openssl"],
+	"rust-analyzer.linkedProjects": [
+		"rs/Cargo.toml"
+	],
 }

cs/build/build.props

@@ -41,7 +41,7 @@
     <NerdbankStreamsVersion>2.13.16</NerdbankStreamsVersion>
     <ReportGeneratorVersion>5.5.4</ReportGeneratorVersion>
     <VisualStudioValidationVersion>17.13.22</VisualStudioValidationVersion>
-    <DevTunnelsSshPackageVersion>3.12.24</DevTunnelsSshPackageVersion>
+    <DevTunnelsSshPackageVersion>3.12.36</DevTunnelsSshPackageVersion>
     <XunitRunnerVisualStudioVersion>3.1.5</XunitRunnerVisualStudioVersion>
     <XunitV3Version>3.2.2</XunitV3Version>
     <XunitV3ExtensibilityCoreVersion>3.2.2</XunitV3ExtensibilityCoreVersion>

cs/src/Contracts/ClusterAvailability.cs

@@ -0,0 +1,27 @@
+// <copyright file="ClusterAvailability.cs" company="Microsoft">
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license.
+// </copyright>
+
+namespace Microsoft.DevTunnels.Contracts;
+
+/// <summary>
+/// Availability status of a tunneling service cluster.
+/// </summary>
+public enum ClusterAvailability
+{
+    /// <summary>
+    /// Cluster has sufficient capacity and is fully available.
+    /// </summary>
+    Available,
+
+    /// <summary>
+    /// Cluster is approaching capacity limits and may experience delays.
+    /// </summary>
+    Degraded,
+
+    /// <summary>
+    /// Cluster is at or beyond capacity and should not be used for new tunnels.
+    /// </summary>
+    Unavailable,
+}

cs/src/Contracts/ClusterRecommendation.cs

@@ -0,0 +1,47 @@
+// <copyright file="ClusterRecommendation.cs" company="Microsoft">
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license.
+// </copyright>
+
+namespace Microsoft.DevTunnels.Contracts;
+
+/// <summary>
+/// A single cluster recommendation with availability and capacity details.
+/// </summary>
+public class ClusterRecommendation
+{
+    /// <summary>
+    /// Gets or sets the cluster ID, e.g. "usw2".
+    /// </summary>
+    public string ClusterId { get; set; } = null!;
+
+    /// <summary>
+    /// Gets or sets the Azure location name, e.g. "WestUs2".
+    /// </summary>
+    public string AzureLocation { get; set; } = null!;
+
+    /// <summary>
+    /// Gets or sets the Azure geography name for data residency, e.g. "United States".
+    /// </summary>
+    public string AzureGeo { get; set; } = null!;
+
+    /// <summary>
+    /// Gets or sets the cluster URI for API requests.
+    /// </summary>
+    public string ClusterUri { get; set; } = null!;
+
+    /// <summary>
+    /// Gets or sets the availability status of the cluster.
+    /// </summary>
+    public ClusterAvailability Availability { get; set; }
+
+    /// <summary>
+    /// Gets or sets the utilization percentage of the cluster.
+    /// </summary>
+    public double UtilizationPercent { get; set; }
+
+    /// <summary>
+    /// Gets or sets a human-readable reason for this recommendation's ranking.
+    /// </summary>
+    public string Reason { get; set; } = null!;
+}

cs/src/Contracts/ClusterRecommendationResponse.cs

@@ -0,0 +1,37 @@
+// <copyright file="ClusterRecommendationResponse.cs" company="Microsoft">
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license.
+// </copyright>
+
+using System;
+
+namespace Microsoft.DevTunnels.Contracts;
+
+/// <summary>
+/// Response from the cluster recommendation API containing ranked cluster recommendations.
+/// </summary>
+public class ClusterRecommendationResponse
+{
+    /// <summary>
+    /// Gets or sets the preferred cluster ID that was requested, if any.
+    /// </summary>
+    public string? PreferredClusterId { get; set; }
+
+    /// <summary>
+    /// Gets or sets the recommended cluster ID — the best available cluster.
+    /// Null if no clusters are available.
+    /// </summary>
+    public string? RecommendedClusterId { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the recommendation differs
+    /// from the preferred cluster.
+    /// </summary>
+    public bool IsFallback { get; set; }
+
+    /// <summary>
+    /// Gets or sets the ordered list of cluster recommendations, ranked by preference.
+    /// </summary>
+    public ClusterRecommendation[] Recommendations { get; set; }
+        = Array.Empty<ClusterRecommendation>();
+}

cs/src/Contracts/DevTunnels.Contracts.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <RootNamespace>Microsoft.DevTunnels.Contracts</RootNamespace>

cs/src/Contracts/TunnelServiceProperties.cs

@@ -27,6 +27,11 @@ public class TunnelServiceProperties
     /// </summary>
     internal const string DevDnsName = "global.ci.tunnels.dev.api.visualstudio.com";
 
+    /// <summary>
+    /// Default host name for the local tunnel service.
+    /// </summary>
+    internal const string LocalDnsName = "global.tunnels.local.api.visualstudio.com";
+
     /// <summary>
     /// First-party app ID: `Visual Studio Tunnel Service`
     /// </summary>
@@ -46,14 +51,14 @@ public class TunnelServiceProperties
     internal const string PpeFirstPartyAppId = "54c45752-bacd-424a-b928-652f3eca2b18";
 
     /// <summary>
-    /// Third-party app ID: `DEV-VSTunnelService-3P`
+    /// Third-party app ID for the DEV service environment.
     /// </summary>
     /// <remarks>
-    /// Used for authenticating AAD/MSA users, and service principals outside the AME tenant,
-    /// in the DEV service environment.
-    /// This is a 3P app registration in the Microsoft corp tenant, replacing the former 1P FPA.
+    /// A 3PA registered in the test tenant, used for authenticating AAD/MSA users
+    /// and service principals outside the AME tenant. Replaces the former 1P FPA
+    /// (9c63851a) which was disabled.
     /// </remarks>
-    internal const string DevFirstPartyAppId = "906ce216-6f2e-40be-875d-7fe1a9bc288a";
+    internal const string DevServiceAppId = "686ab1c6-3cd9-4a62-b228-4f71eaaaf53e";
 
     /// <summary>
     /// Third-party app ID: `tunnels-prod-app-sp`
@@ -95,10 +100,28 @@ public class TunnelServiceProperties
     /// GitHub App Client ID for 'Visual Studio Tunnel Service - Test'
     /// </summary>
     /// <remarks>
-    /// Used by client apps that authenticate tunnel users with GitHub, in the PPE and DEV
-    /// service environments.
+    /// Used by client apps that authenticate tunnel users with GitHub, in the PPE
+    /// service environment.
+    /// </remarks>
+    internal const string PpeGitHubAppClientId = "Iv1.b231c327f1eaa229";
+
+    /// <summary>
+    /// GitHub App Client ID for 'Dev Tunnels Service - Dev'
+    /// </summary>
+    /// <remarks>
+    /// Used by client apps that authenticate tunnel users with GitHub, in the DEV
+    /// service environment.
     /// </remarks>
-    internal const string NonProdGitHubAppClientId = "Iv1.b231c327f1eaa229";
+    internal const string DevGitHubAppClientId = "Iv23ctTiak9wLCiTcEbr";
+
+    /// <summary>
+    /// GitHub App Client ID for 'Dev Tunnels Service - Local'
+    /// </summary>
+    /// <remarks>
+    /// Used by client apps that authenticate tunnel users with GitHub, when running
+    /// the service locally.
+    /// </remarks>
+    internal const string LocalGitHubAppClientId = "Iv23cttBYzKThF88PiPR";
 
     private TunnelServiceProperties(
         string serviceUri,
@@ -128,16 +151,29 @@ private TunnelServiceProperties(
         $"https://{PpeDnsName}/",
         PpeFirstPartyAppId,
         PpeThirdPartyAppId,
-        NonProdGitHubAppClientId);
+        PpeGitHubAppClientId);
 
     /// <summary>
     /// Gets properties for the service in the development environment.
     /// </summary>
     public static TunnelServiceProperties Development { get; } = new TunnelServiceProperties(
         $"https://{DevDnsName}/",
-        DevFirstPartyAppId,
+        DevServiceAppId,
+        DevThirdPartyAppId,
+        DevGitHubAppClientId);
+
+    /// <summary>
+    /// Gets properties for the service when running locally.
+    /// </summary>
+    /// <remarks>
+    /// Uses the same service app IDs as the development environment, but a different
+    /// GitHub app with localhost callback URLs.
+    /// </remarks>
+    public static TunnelServiceProperties Local { get; } = new TunnelServiceProperties(
+        $"https://{LocalDnsName}/",
+        DevServiceAppId,
         DevThirdPartyAppId,
-        NonProdGitHubAppClientId);
+        LocalGitHubAppClientId);
 
     /// <summary>
     /// Gets properties for the service in the specified environment.
@@ -157,6 +193,7 @@ public static TunnelServiceProperties Environment(string environmentName)
             "prod" or "production" => TunnelServiceProperties.Production,
             "ppe" or "preprod" or "staging" => TunnelServiceProperties.Staging,
             "dev" or "development" => TunnelServiceProperties.Development,
+            "local" => TunnelServiceProperties.Local,
             _ => throw new ArgumentException($"Invalid service environment: {environmentName}"),
         };
     }

cs/src/Management/ITunnelManagementClient.cs

@@ -395,6 +395,25 @@ Task<TunnelAccessSubject[]> ResolveSubjectsAsync(
         /// <returns>Array of <see cref="ClusterDetails"/></returns>
         Task<ClusterDetails[]> ListClustersAsync(CancellationToken cancellation = default);
 
+        /// <summary>
+        /// Gets cluster recommendations for tunnel creation based on capacity and
+        /// availability.
+        /// </summary>
+        /// <param name="preferredClusterId">
+        /// Optional preferred cluster ID. When omitted, defaults to the cluster
+        /// serving the request.
+        /// </param>
+        /// <param name="requiredGeo">
+        /// Optional Azure geography filter. When specified, only clusters in
+        /// this geo are eligible for recommendation.
+        /// </param>
+        /// <param name="cancellation">Cancellation token.</param>
+        /// <returns>Cluster recommendation response with ranked clusters.</returns>
+        Task<ClusterRecommendationResponse> GetClusterRecommendationsAsync(
+            string? preferredClusterId = null,
+            string? requiredGeo = null,
+            CancellationToken cancellation = default);
+
         /// <summary>
         /// Checks for tunnel name availability.
         /// </summary>

cs/src/Management/TunnelManagementClient.cs

@@ -42,6 +42,7 @@ public class TunnelManagementClient : ITunnelManagementClient
         private const string EventsApiSubPath = "/events";
         private const string ClustersApiPath = "/clusters";
         private const string ClustersV1ApiPath = ApiV1Path + "/clusters";
+        private const string RecommendationsSubPath = "/recommendations";
         private const string TunnelAuthenticationScheme = "Tunnel";
         private const string RequestIdHeaderName = "VsSaaS-Request-Id";
         private const string CheckAvailableSubPath = ":checkNameAvailability";
@@ -1084,6 +1085,29 @@ public async Task<Tunnel> CreateTunnelAsync(
         {
             Requires.NotNull(tunnel, nameof(tunnel));
             options ??= new TunnelRequestOptions();
+
+            // If the caller didn't specify a cluster, auto-select one via the
+            // recommendations API. Failures fall back to global routing.
+            if (string.IsNullOrEmpty(tunnel.ClusterId))
+            {
+                try
+                {
+                    var recommendations = await GetClusterRecommendationsAsync(
+                        preferredClusterId: null,
+                        requiredGeo: options.RequiredGeo,
+                        cancellation);
+                    if (!string.IsNullOrEmpty(recommendations?.RecommendedClusterId))
+                    {
+                        tunnel.ClusterId = recommendations!.RecommendedClusterId;
+                    }
+                }
+                catch (Exception) when (!cancellation.IsCancellationRequested)
+                {
+                    // Fall through to global (Traffic Manager) routing if the
+                    // recommendations request fails for any reason.
+                }
+            }
+
             options.AdditionalHeaders ??= new List<KeyValuePair<string, string>>();
             options.AdditionalHeaders = options.AdditionalHeaders.Append(
                 new KeyValuePair<string, string>("If-None-Match", "*"));
@@ -1595,6 +1619,46 @@ public async Task<ClusterDetails[]> ListClustersAsync(CancellationToken cancella
             return clusterDetails!;
         }
 
+        /// <inheritdoc/>
+        public async Task<ClusterRecommendationResponse> GetClusterRecommendationsAsync(
+            string? preferredClusterId = null,
+            string? requiredGeo = null,
+            CancellationToken cancellation = default)
+        {
+            var baseAddress = this.httpClient.BaseAddress!;
+            var builder = new UriBuilder(baseAddress);
+            builder.Path = ClustersPath + RecommendationsSubPath;
+
+            var queryParts = new List<string>();
+            var apiQuery = GetApiQuery();
+            if (!string.IsNullOrEmpty(apiQuery))
+            {
+                queryParts.Add(apiQuery!);
+            }
+
+            if (!string.IsNullOrEmpty(preferredClusterId))
+            {
+                queryParts.Add(
+                    $"preferredClusterId={Uri.EscapeDataString(preferredClusterId!)}");
+            }
+
+            if (!string.IsNullOrEmpty(requiredGeo))
+            {
+                queryParts.Add($"requiredGeo={Uri.EscapeDataString(requiredGeo!)}");
+            }
+
+            builder.Query = string.Join("&", queryParts);
+
+            var response = await SendRequestAsync<object, ClusterRecommendationResponse>(
+                HttpMethod.Get,
+                builder.Uri,
+                options: null,
+                authHeader: null,
+                body: null,
+                cancellation);
+            return response!;
+        }
+
         /// <inheritdoc/>
         public async Task<bool> CheckNameAvailabilityAsync(
             string name,