Move search tags to request options (#98)

Author: jasongin

cs/src/Management/ITunnelManagementClient.cs

@@ -18,7 +18,7 @@ namespace Microsoft.VsSaaS.TunnelService
     public interface ITunnelManagementClient : IDisposable
     {
         /// <summary>
-        /// Lists all tunnels that are owned by the caller.
+        /// Lists tunnels that are owned by the caller.
         /// </summary>
         /// <param name="clusterId">A tunnel cluster ID, or null to list tunnels globally.</param>
         /// <param name="domain">Tunnel domain, or null for the default domain.</param>
@@ -27,6 +27,11 @@ public interface ITunnelManagementClient : IDisposable
         /// <returns>Array of tunnel objects.</returns>
         /// <exception cref="UnauthorizedAccessException">The client access token was missing,
         /// invalid, or unauthorized.</exception>
+        /// <remarks>
+        /// The list can be filtered by setting <see cref="TunnelRequestOptions.Tags"/>.
+        /// Ports will not be included in the returned tunnels unless
+        /// <see cref="TunnelRequestOptions.IncludePorts"/> is set to true.
+        /// </remarks>
         Task<Tunnel[]> ListTunnelsAsync(
             string? clusterId = null,
             string? domain = null,
@@ -45,6 +50,7 @@ Task<Tunnel[]> ListTunnelsAsync(
         /// <returns>Array of tunnel objects.</returns>
         /// <exception cref="UnauthorizedAccessException">The client access token was missing,
         /// invalid, or unauthorized.</exception>
+        [Obsolete("Use ListTunnelsAsync() method with TunnelRequestOptions.Tags instead.")]
         Task<Tunnel[]> SearchTunnelsAsync(
             string[] tags,
             bool requireAllTags,
@@ -63,6 +69,10 @@ Task<Tunnel[]> SearchTunnelsAsync(
         /// <returns>The requested tunnel object, or null if the ID or name was not found.</returns>
         /// <exception cref="UnauthorizedAccessException">The client access token was missing,
         /// invalid, or unauthorized.</exception>
+        /// <remarks>
+        /// Ports will not be included in the returned tunnel unless
+        /// <see cref="TunnelRequestOptions.IncludePorts"/> is set to true.
+        /// </remarks>
         Task<Tunnel?> GetTunnelAsync(
             Tunnel tunnel,
             TunnelRequestOptions? options = null,
@@ -180,7 +190,7 @@ Task<bool> DeleteTunnelEndpointsAsync(
             CancellationToken cancellation = default);
 
         /// <summary>
-        /// Lists all ports on a tunnel.
+        /// Lists ports on a tunnel.
         /// </summary>
         /// <param name="tunnel">Tunnel object including at least either a tunnel name
         /// (globally unique, if configured) or tunnel ID and cluster ID.</param>
@@ -191,6 +201,9 @@ Task<bool> DeleteTunnelEndpointsAsync(
         /// invalid, or unauthorized.</exception>
         /// <exception cref="InvalidOperationException">The tunnel ID or name was not found.
         /// </exception>
+        /// <remarks>
+        /// The list can be filtered by setting <see cref="TunnelRequestOptions.Tags"/>.
+        /// </remarks>
         Task<TunnelPort[]> ListTunnelPortsAsync(
             Tunnel tunnel,
             TunnelRequestOptions? options = null,

cs/src/Management/TunnelManagementClient.cs

@@ -599,6 +599,7 @@ public async Task<Tunnel[]> ListTunnelsAsync(
         }
 
         /// <inheritdoc />
+        [Obsolete("Use ListTunnelsAsync() method with TunnelRequestOptions.Tags instead.")]
         public async Task<Tunnel[]> SearchTunnelsAsync(
             string[] tags,
             bool requireAllTags,

cs/src/Management/TunnelRequestOptions.cs

@@ -22,6 +22,8 @@ namespace Microsoft.VsSaaS.TunnelService
     /// </remarks>
     public class TunnelRequestOptions
     {
+        private static readonly string[] TrueOption = new[] { "true" };
+
         /// <summary>
         /// Gets or sets a tunnel access token for the request.
         /// </summary>
@@ -55,10 +57,29 @@ public class TunnelRequestOptions
         public bool FollowRedirects { get; set; } = true;
 
         /// <summary>
-        /// Gets or sets a flag that requests tunnel ports when retrieving a tunnel object.
+        /// Gets or sets a flag that requests tunnel ports when retrieving tunnels.
         /// </summary>
         public bool IncludePorts { get; set; }
 
+        /// <summary>
+        /// Gets or sets an optional list of tags to filter the requested tunnels or ports.
+        /// </summary>
+        /// <remarks>
+        /// Requested tags are compared to the <see cref="Tunnel.Tags"/> or
+        /// <see cref="TunnelPort.Tags"/> when calling
+        /// <see cref="ITunnelManagementClient.ListTunnelsAsync"/> or
+        /// <see cref="ITunnelManagementClient.ListTunnelPortsAsync"/> respectively. By default, an
+        /// item is included if ANY tag matches; set <see cref="RequireAllTags" /> to match ALL
+        /// tags instead.
+        /// </remarks>
+        public string[]? Tags { get; set; }
+
+        /// <summary>
+        /// Gets or sets a flag that indicates whether listed items must match all tags
+        /// specified in <see cref="Tags"/>. If false, an item is included if any tag matches.
+        /// </summary>
+        public bool RequireAllTags { get; set; }
+
         /// <summary>
         /// Gets or sets an optional list of scopes that should be authorized when retrieving a
         /// tunnel or tunnel port object.
@@ -89,32 +110,42 @@ public class TunnelRequestOptions
         /// </summary>
         protected internal virtual string ToQueryString()
         {
-            var queryOptions = new Dictionary<string, string>();
+            var queryOptions = new Dictionary<string, string[]>();
 
             if (IncludePorts)
             {
-                queryOptions["includePorts"] = "true";
+                queryOptions["includePorts"] = TrueOption;
             }
 
             if (Scopes != null)
             {
                 TunnelAccessControl.ValidateScopes(Scopes);
-                queryOptions["scopes"] = string.Join(",", Scopes);
+                queryOptions["scopes"] = Scopes;
             }
 
             if (TokenScopes != null)
             {
                 TunnelAccessControl.ValidateScopes(TokenScopes);
-                queryOptions["tokenScopes"] = string.Join(",", TokenScopes);
+                queryOptions["tokenScopes"] = TokenScopes;
             }
 
             if (ForceRename)
             {
-                queryOptions["forceRename"] = "true";
+                queryOptions["forceRename"] = TrueOption;
+            }
+
+            if (Tags != null && Tags.Length > 0)
+            {
+                queryOptions["tags"] = Tags;
+                if (RequireAllTags)
+                {
+                    queryOptions["allTags"] = TrueOption;
+                }
             }
 
+            // Note the comma separator for multi-valued options is NOT URL-encoded.
             return string.Join('&', queryOptions.Select(
-                (o) => $"{o.Key}={HttpUtility.UrlEncode(o.Value)}"));
+                (o) => $"{o.Key}={string.Join(",", o.Value.Select(HttpUtility.UrlEncode))}"));
         }
     }
 }

go/tunnels/manager.go

@@ -13,7 +13,6 @@ import (
 	"net/http"
 	"net/url"
 	"reflect"
-	"strconv"
 	"strings"
 )
 
@@ -112,7 +111,7 @@ func NewManager(userAgents []UserAgent, tp tokenProviderfn, tunnelServiceUrl *ur
 	return &Manager{tokenProvider: tp, httpClient: client, uri: tunnelServiceUrl, userAgents: userAgents}, nil
 }
 
-// Lists all tunnels owned by the authenticated user.
+// Lists tunnels owned by the authenticated user.
 // Returns a list of tunnels or an error if the search fails.
 func (m *Manager) ListTunnels(
 	ctx context.Context, clusterID string, domain string, options *TunnelRequestOptions,
@@ -138,37 +137,6 @@ func (m *Manager) ListTunnels(
 	return ts, nil
 }
 
-// Search tunnels that the authenticated user has access to based on tags.
-// If requireAllTags is true then tunnels returned must contain all tags in the tags slice.
-// Returns a slice of the found tunnels or an error if the search fails.
-func (m *Manager) SearchTunnels(
-	ctx context.Context, tags []string, requireAllTags bool, clusterID string, domain string, options *TunnelRequestOptions,
-) (ts []*Tunnel, err error) {
-	queryParams := url.Values{}
-	if clusterID == "" {
-		queryParams.Add("global", "true")
-	}
-	if domain != "" {
-		queryParams.Add("domain", domain)
-	}
-	queryParams.Add("allTags", strconv.FormatBool(requireAllTags))
-	tagString := strings.Join(tags, ",")
-	queryParams.Add("tags", tagString)
-
-	url := m.buildUri(clusterID, tunnelsApiPath, options, queryParams.Encode())
-	response, err := m.sendTunnelRequest(ctx, nil, options, http.MethodGet, url, nil, nil, readAccessTokenScope, false)
-	if err != nil {
-		return nil, fmt.Errorf("error sending search tunnel request: %w", err)
-	}
-
-	err = json.Unmarshal(response, &ts)
-	if err != nil {
-		return nil, fmt.Errorf("error parsing response json to tunnel: %w", err)
-	}
-
-	return ts, nil
-}
-
 // Gets a tunnel by id or name.
 // If getting a tunnel by name the domain must be provided if the tunnel is not in the default domain.
 // Returns the requested tunnel or an error if the tunnel is not found.
@@ -338,7 +306,7 @@ func (m *Manager) DeleteTunnelEndpoints(
 	return err
 }
 
-// Lists all ports on the tunnel.
+// Lists ports on the tunnel.
 func (m *Manager) ListTunnelPorts(
 	ctx context.Context, tunnel *Tunnel, options *TunnelRequestOptions,
 ) (tp []*TunnelPort, err error) {

go/tunnels/request_options.go

@@ -21,6 +21,15 @@ type TunnelRequestOptions struct {
 	// Flag that requests tunnel ports when retrieving a tunnel object.
 	IncludePorts bool
 
+	// Optional list of tags to filter the requested tunnels or ports.
+	// By default, an item is included if ANY tag matches; set `requireAllTags` to match
+	// ALL tags instead.
+	Tags []string
+
+	// Flag that indicates whether listed items must match all tags specified in `tags`.
+	// If false, an item is included if any tag matches.
+	RequireAllTags bool
+
 	// List of scopes that are needed for the current request.
 	Scopes TunnelAccessScopes
 
@@ -54,6 +63,15 @@ func (options *TunnelRequestOptions) queryString() string {
 	if options.ForceRename {
 		queryOptions.Set("forceRename", "true")
 	}
+	if options.Tags != nil {
+		for _, tag := range options.Tags {
+			queryOptions.Add("tags", string(tag))
+		}
+
+		if options.RequireAllTags {
+			queryOptions.Set("allTags", "true")
+		}
+	}
 
 	return queryOptions.Encode()
 }

java/src/main/java/com/microsoft/tunnels/management/ITunnelManagementClient.java

@@ -17,29 +17,14 @@
  */
 public interface ITunnelManagementClient {
   /**
-   * Lists all tunnels that are owned by the caller.
+   * Lists tunnels that are owned by the caller.
    *
    * @param clusterId A tunnel cluster ID, or null to list tunnels globally.
+   * @param domain    Tunnel domain, or null for the default domain.
    * @param options   Request options.
    * @return Array of tunnel objects.
    */
   public CompletableFuture<Collection<Tunnel>> listTunnelsAsync(
-      String clusterId,
-      TunnelRequestOptions options);
-
-  /**
-   * Search for all tunnels with matching tags.
-   *
-   * @param tags           The tags to search for.
-   * @param requireAllTags requires a tunnel to have all specified tags.
-   * @param clusterId      A tunnel cluster ID, or null to list tunnels globally.
-   * @param domain         Tunnel domain, or null for the default domain.
-   * @param options        Request options.
-   * @return Array of tunnel objects.
-   */
-  public CompletableFuture<Collection<Tunnel>> searchTunnelsAsync(
-      String[] tags,
-      boolean requireAllTags,
       String clusterId,
       String domain,
       TunnelRequestOptions options);

java/src/main/java/com/microsoft/tunnels/management/TunnelManagementClient.java

@@ -6,19 +6,16 @@
 import com.google.gson.Gson;
 import com.google.gson.reflect.TypeToken;
 import com.microsoft.tunnels.contracts.Tunnel;
-import com.microsoft.tunnels.contracts.TunnelAccessControl;
 import com.microsoft.tunnels.contracts.TunnelAccessControlEntry;
 import com.microsoft.tunnels.contracts.TunnelAccessScopes;
 import com.microsoft.tunnels.contracts.TunnelConnectionMode;
 import com.microsoft.tunnels.contracts.TunnelContracts;
 import com.microsoft.tunnels.contracts.TunnelEndpoint;
 import com.microsoft.tunnels.contracts.TunnelPort;
 
-import java.io.UnsupportedEncodingException;
 import java.lang.reflect.Type;
 import java.net.URI;
 import java.net.URISyntaxException;
-import java.net.URLEncoder;
 import java.net.http.HttpClient;
 import java.net.http.HttpRequest;
 import java.net.http.HttpRequest.BodyPublishers;
@@ -242,7 +239,7 @@ private URI buildUri(String clusterId,
 
     String queryString = "";
     if (options != null) {
-      queryString = toQueryString(options);
+      queryString = options.toQueryString();
     }
     if (query != null) {
       queryString += StringUtils.isBlank(queryString) ? query : "&" + query;
@@ -263,38 +260,10 @@ private URI buildUri(String clusterId,
     }
   }
 
-  private String toQueryString(TunnelRequestOptions options) {
-    final String encoding = "UTF-8";
-    var queryOptions = new ArrayList<String>();
-    if (options.includePorts) {
-      queryOptions.add("includePorts=true");
-    }
-
-    if (options.scopes != null) {
-      TunnelAccessControl.validateScopes(options.scopes, null);
-      try {
-        queryOptions.add("scopes=" + URLEncoder.encode(String.join(",", options.scopes), encoding));
-      } catch (UnsupportedEncodingException e) {
-        throw new IllegalArgumentException("Bad encoding: " + encoding);
-      }
-    }
-
-    if (options.tokenScopes != null) {
-      TunnelAccessControl.validateScopes(options.tokenScopes, null);
-      try {
-        queryOptions.add(
-            "tokenScopes=" + URLEncoder.encode(String.join(",", options.tokenScopes), encoding));
-      } catch (UnsupportedEncodingException e) {
-        throw new IllegalArgumentException("Bad encoding: " + encoding);
-      }
-    }
-    return String.join("&", queryOptions);
-  }
-
   public CompletableFuture<Collection<Tunnel>> listTunnelsAsync(
       String clusterId,
+      String domain,
       TunnelRequestOptions options) {
-    // TODO - add domain parameter
     var query = StringUtils.isBlank(clusterId) ? "global=true" : null;
     var requestUri = this.buildUri(clusterId, tunnelsApiPath, options, query);
     final Type responseType = new TypeToken<Collection<Tunnel>>() {
@@ -309,17 +278,6 @@ public CompletableFuture<Collection<Tunnel>> listTunnelsAsync(
         responseType);
   }
 
-  @Override
-  public CompletableFuture<Collection<Tunnel>> searchTunnelsAsync(
-      String[] tags,
-      boolean requireAllTags,
-      String clusterId,
-      String domain,
-      TunnelRequestOptions options) {
-    // TODO Auto-generated method stub
-    return null;
-  }
-
   @Override
   public CompletableFuture<Tunnel> getTunnelAsync(Tunnel tunnel, TunnelRequestOptions options) {
     var requestUri = buildUri(tunnel, options, null, null);