[WebPubSub] Adding feature support (Azure#32462)

Author: vicancy

sdk/webpubsub/Azure.Messaging.WebPubSub/CHANGELOG.md

@@ -1,14 +1,13 @@
 # Release History
 
-## 1.3.0-beta.1 (Unreleased)
+## 1.3.0 (2022-11-20)
 
 ### Features Added
 
-### Breaking Changes
-
-### Bugs Fixed
-
-### Other Changes
+- Added method `serviceClient.RemoveConnectionFromAllGroups` to remove the connection from all the groups it is in.
+- Added a `groups` option in `serviceClient.GetClientAccessUri`, to enable connections join initial groups once it is connected.
+- Added a `filter` parameter when sending messages to connections in a hub/group/user to filter out the connections recieving message, details about `filter` syntax please see [OData filter syntax for Azure Web PubSub](https://aka.ms/awps/filter-syntax).
+- Provided a utility class `ClientConnectionFilter` to generate the `filter` parameter, e.g. `ClientConnectionFilter.Create($"{group1} in groups and not({group2} in groups)"))`
 
 ## 1.2.0 (2022-11-04)
 

sdk/webpubsub/Azure.Messaging.WebPubSub/README.md

@@ -70,15 +70,27 @@ When a client is connected, it can send messages to the upstream application, or
 
 ## Examples
 
-### Broadcast a text message to all clients
+### Generate the full URI containing access token for the connection to use when connects the Azure Web PubSub
+
+```C# Snippet:GetClientAccessUri
+// Generate client access URI for userA
+serviceClient.GetClientAccessUri(userId: "userA");
+// Generate client access URI with initial permissions
+serviceClient.GetClientAccessUri(roles: new string[] { "webpubsub.joinLeaveGroup.group1", "webpubsub.sendToGroup.group1" });
+// Generate client access URI with initial groups to join when the connection connects
+serviceClient.GetClientAccessUri(groups: new string[] { "group1", "group2" });
+```
+
+### Send messages to the connections
+#### Broadcast a text message to all clients
 
 ```C# Snippet:WebPubSubHelloWorld
 var serviceClient = new WebPubSubServiceClient(connectionString, "some_hub");
 
 serviceClient.SendToAll("Hello World!");
 ```
 
-### Broadcast a JSON message to all clients
+#### Broadcast a JSON message to all clients
 
 ```C# Snippet:WebPubSubSendJson
 var serviceClient = new WebPubSubServiceClient(connectionString, "some_hub");
@@ -92,7 +104,7 @@ serviceClient.SendToAll(RequestContent.Create(
         ContentType.ApplicationJson);
 ```
 
-### Broadcast a binary message to all clients
+#### Broadcast a binary message to all clients
 
 ```C# Snippet:WebPubSubSendBinary
 var serviceClient = new WebPubSubServiceClient(connectionString, "some_hub");
@@ -101,6 +113,54 @@ Stream stream = BinaryData.FromString("Hello World!").ToStream();
 serviceClient.SendToAll(RequestContent.Create(stream), ContentType.ApplicationOctetStream);
 ```
 
+#### Broadcast messages to clients using filter
+Azure Web PubSub supports OData filter syntax to filter out the connections to send messages to.
+
+Details about `filter` syntax please see [OData filter syntax for Azure Web PubSub](https://aka.ms/awps/filter-syntax).
+
+```C# Snippet:WebPubSubSendWithFilter
+var serviceClient = new WebPubSubServiceClient(connectionString, "some_hub");
+
+// Use filter to send text message to anonymous connections
+serviceClient.SendToAll(
+        RequestContent.Create("Hello World!"),
+        ContentType.TextPlain,
+        filter: ClientConnectionFilter.Create($"userId eq {null}"));
+
+// Use filter to send JSON message to connections in groupA but not in groupB
+var group1 = "GroupA";
+var group2 = "GroupB";
+serviceClient.SendToAll(RequestContent.Create(
+        new
+        {
+            Foo = "Hello World!",
+            Bar = 42
+        }),
+        ContentType.ApplicationJson,
+        filter: ClientConnectionFilter.Create($"{group1} in groups and not({group2} in groups)"));
+```
+
+### Connection management
+
+#### Add connections for some user to some group:
+```C# Snippet:WebPubSubAddUserToGroup
+client.AddUserToGroup("some_group", "some_user");
+
+// Avoid sending messages to users who do not exist.
+if (client.UserExists("some_user").Value)
+{
+    client.SendToUser("some_user", "Hi, I am glad you exist!");
+}
+
+client.RemoveUserFromGroup("some_group", "some_user");
+```
+
+#### Remove connection from all groups
+```C# Snippet:WebPubSubRemoveConnectionFromAllGroups
+var client = new WebPubSubServiceClient(connectionString, "some_hub");
+client.RemoveConnectionFromAllGroups("some_connection");
+```
+
 ## Troubleshooting
 
 ### Setting up console logging

sdk/webpubsub/Azure.Messaging.WebPubSub/api/Azure.Messaging.WebPubSub.netstandard2.0.cs

@@ -1,5 +1,10 @@
 namespace Azure.Messaging.WebPubSub
 {
+    public static partial class ClientConnectionFilter
+    {
+        public static string Create(System.FormattableString filter) { throw null; }
+        public static string Create(System.FormattableString filter, System.IFormatProvider formatProvider) { throw null; }
+    }
     public enum WebPubSubPermission
     {
         SendToGroup = 1,
@@ -33,10 +38,14 @@ public WebPubSubServiceClient(System.Uri endpoint, string hub, Azure.Core.TokenC
         public virtual System.Threading.Tasks.Task<Azure.Response> CloseUserConnectionsAsync(string userId, System.Collections.Generic.IEnumerable<string> excluded = null, string reason = null, Azure.RequestContext context = null) { throw null; }
         public virtual Azure.Response<bool> ConnectionExists(string connectionId, Azure.RequestContext context = null) { throw null; }
         public virtual System.Threading.Tasks.Task<Azure.Response<bool>> ConnectionExistsAsync(string connectionId, Azure.RequestContext context = null) { throw null; }
-        public virtual System.Uri GetClientAccessUri(System.DateTimeOffset expiresAt, string userId = null, System.Collections.Generic.IEnumerable<string> roles = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
-        public virtual System.Uri GetClientAccessUri(System.TimeSpan expiresAfter = default(System.TimeSpan), string userId = null, System.Collections.Generic.IEnumerable<string> roles = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
-        public virtual System.Threading.Tasks.Task<System.Uri> GetClientAccessUriAsync(System.DateTimeOffset expiresAt, string userId = null, System.Collections.Generic.IEnumerable<string> roles = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
-        public virtual System.Threading.Tasks.Task<System.Uri> GetClientAccessUriAsync(System.TimeSpan expiresAfter = default(System.TimeSpan), string userId = null, System.Collections.Generic.IEnumerable<string> roles = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        public virtual System.Uri GetClientAccessUri(System.DateTimeOffset expiresAt, string userId = null, System.Collections.Generic.IEnumerable<string> roles = null, System.Collections.Generic.IEnumerable<string> groups = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        public virtual System.Uri GetClientAccessUri(System.DateTimeOffset expiresAt, string userId, System.Collections.Generic.IEnumerable<string> roles, System.Threading.CancellationToken cancellationToken) { throw null; }
+        public virtual System.Uri GetClientAccessUri(System.TimeSpan expiresAfter = default(System.TimeSpan), string userId = null, System.Collections.Generic.IEnumerable<string> roles = null, System.Collections.Generic.IEnumerable<string> groups = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        public virtual System.Uri GetClientAccessUri(System.TimeSpan expiresAfter, string userId, System.Collections.Generic.IEnumerable<string> roles, System.Threading.CancellationToken cancellationToken) { throw null; }
+        public virtual System.Threading.Tasks.Task<System.Uri> GetClientAccessUriAsync(System.DateTimeOffset expiresAt, string userId = null, System.Collections.Generic.IEnumerable<string> roles = null, System.Collections.Generic.IEnumerable<string> groups = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        public virtual System.Threading.Tasks.Task<System.Uri> GetClientAccessUriAsync(System.DateTimeOffset expiresAt, string userId, System.Collections.Generic.IEnumerable<string> roles, System.Threading.CancellationToken cancellationToken) { throw null; }
+        public virtual System.Threading.Tasks.Task<System.Uri> GetClientAccessUriAsync(System.TimeSpan expiresAfter = default(System.TimeSpan), string userId = null, System.Collections.Generic.IEnumerable<string> roles = null, System.Collections.Generic.IEnumerable<string> groups = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        public virtual System.Threading.Tasks.Task<System.Uri> GetClientAccessUriAsync(System.TimeSpan expiresAfter, string userId, System.Collections.Generic.IEnumerable<string> roles, System.Threading.CancellationToken cancellationToken) { throw null; }
         public virtual Azure.Response GrantPermission(Azure.Messaging.WebPubSub.WebPubSubPermission permission, string connectionId, string targetName = null, Azure.RequestContext context = null) { throw null; }
         public virtual System.Threading.Tasks.Task<Azure.Response> GrantPermissionAsync(Azure.Messaging.WebPubSub.WebPubSubPermission permission, string connectionId, string targetName = null, Azure.RequestContext context = null) { throw null; }
         public virtual Azure.Response<bool> GroupExists(string group, Azure.RequestContext context = null) { throw null; }

sdk/webpubsub/Azure.Messaging.WebPubSub/src/Azure.Messaging.WebPubSub.csproj

@@ -2,7 +2,7 @@
   <PropertyGroup>
     <Description>Azure SDK client library for the WebPubSub service</Description>
     <AssemblyTitle>Azure SDK for WebPubSub</AssemblyTitle>
-    <Version>1.3.0-beta.1</Version>
+    <Version>1.3.0</Version>
     <!--The ApiCompatVersion is managed automatically and should not generally be modified manually.-->
     <ApiCompatVersion>1.2.0</ApiCompatVersion>
     <PackageTags>Azure, WebPubSub, SignalR</PackageTags>

sdk/webpubsub/Azure.Messaging.WebPubSub/src/ClientConnectionFilter.cs

@@ -0,0 +1,106 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using Azure.Core.GeoJson;
+using Azure.Core;
+using System.Globalization;
+using System.IO;
+using System.Text;
+using System;
+
+namespace Azure.Messaging.WebPubSub
+{
+    /// <summary>
+    /// The ClientConnectionFilter class is used to help construct valid OData filter
+    /// parameter to be used by Send* APIs by automatically replacing, quoting, and escaping interpolated
+    /// parameters.
+    /// For more information, see <see href="https://aka.ms/awps/filter-syntax">Filters in Azure Web PubSub</see>.
+    /// </summary>
+    public static class ClientConnectionFilter
+    {
+        /// <summary>
+        /// Create an OData filter expression from an interpolated string.  The
+        /// interpolated values will be quoted and escaped as necessary.
+        /// </summary>
+        /// <param name="filter">An interpolated filter string.</param>
+        /// <returns>A valid OData filter expression.</returns>
+        public static string Create(FormattableString filter) =>
+            Create(filter, null);
+
+        /// <summary>
+        /// Create an OData filter expression from an interpolated string.  The
+        /// interpolated values will be quoted and escaped as necessary.
+        /// </summary>
+        /// <param name="filter">An interpolated filter string.</param>
+        /// <param name="formatProvider">
+        /// Format provider used to convert values to strings.
+        /// <see cref="CultureInfo.InvariantCulture"/> is used as a default.
+        /// </param>
+        /// <returns>A valid OData filter expression.</returns>
+        public static string Create(FormattableString filter, IFormatProvider formatProvider)
+        {
+            if (filter == null)
+            { return null; }
+            formatProvider ??= CultureInfo.InvariantCulture;
+
+            string[] args = new string[filter.ArgumentCount];
+            for (int i = 0; i < filter.ArgumentCount; i++)
+            {
+                args[i] = filter.GetArgument(i) switch
+                {
+                    // Null
+                    null => "null",
+
+                    // Boolean
+                    bool x => x.ToString(formatProvider).ToLowerInvariant(),
+
+                    // Numeric
+                    sbyte x => x.ToString(formatProvider),
+                    byte x => x.ToString(formatProvider),
+                    short x => x.ToString(formatProvider),
+                    ushort x => x.ToString(formatProvider),
+                    int x => x.ToString(formatProvider),
+                    uint x => x.ToString(formatProvider),
+                    long x => x.ToString(formatProvider),
+                    ulong x => x.ToString(formatProvider),
+
+                    // Text
+                    string x => Quote(x),
+                    char x => Quote(x.ToString(formatProvider)),
+                    StringBuilder x => Quote(x.ToString()),
+
+                    // Everything else
+                    object x => throw new ArgumentException(
+                        $"Unable to convert argument {i} from type {x.GetType()} to a suppported OData filter string.")
+                };
+            }
+            string text = string.Format(formatProvider, filter.Format, args);
+            return text;
+        }
+
+        /// <summary>
+        /// Quote and escape OData strings.
+        /// </summary>
+        /// <param name="text">The text to quote.</param>
+        /// <returns>The quoted text.</returns>
+        private static string Quote(string text)
+        {
+            if (text == null)
+            { return "null"; }
+
+            // Optimistically allocate an extra 5% for escapes
+            StringBuilder builder = new StringBuilder(2 + (int)(text.Length * 1.05));
+            builder.Append('\'');
+            foreach (char ch in text)
+            {
+                builder.Append(ch);
+                if (ch == '\'')
+                {
+                    builder.Append(ch);
+                }
+            }
+            builder.Append('\'');
+            return builder.ToString();
+        }
+    }
+}