Support for disconnecting clients. Resolves #39

Author: tpeczek

Benchmark.AspNetCore.ServerSentEvents/Benchmarks/ServerSentEventsServiceBenchmarks.cs

@@ -33,12 +33,12 @@ public class ServerSentEventsServiceBenchmarks
         #region Constructor
         public ServerSentEventsServiceBenchmarks()
         {
-            _serverSentEventsClient = new ServerSentEventsClient(Guid.NewGuid(), new ClaimsPrincipal(), new NoOpHttpResponse());
+            _serverSentEventsClient = new ServerSentEventsClient(Guid.NewGuid(), new ClaimsPrincipal(), new NoOpHttpResponse(), false);
 
             _serverSentEventsService = new ServerSentEventsService(Options.Create<ServerSentEventsServiceOptions<ServerSentEventsService>>(null));
             for (int i = 0; i < MULTIPLE_CLIENTS_COUNT; i++)
             {
-                _serverSentEventsService.AddClient(new ServerSentEventsClient(Guid.NewGuid(), new ClaimsPrincipal(), new NoOpHttpResponse()));
+                _serverSentEventsService.AddClient(new ServerSentEventsClient(Guid.NewGuid(), new ClaimsPrincipal(), new NoOpHttpResponse(), false));
             }
         }
         #endregion

DocFx.AspNetCore.ServerSentEvents/DocFx.AspNetCore.ServerSentEvents.csproj

@@ -1,6 +1,6 @@
 <Project Sdk="Microsoft.NET.Sdk.Web">
   <PropertyGroup>
-    <TargetFramework>netcoreapp3.1</TargetFramework>
+    <TargetFramework>net5.0</TargetFramework>
   </PropertyGroup>
   <ItemGroup>
     <None Remove="log.txt" />
@@ -9,7 +9,7 @@
     <Folder Include="wwwroot\" />
   </ItemGroup>
   <ItemGroup>
-    <PackageReference Include="docfx.console" Version="2.48.0">
+    <PackageReference Include="docfx.console" Version="2.58.8">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>

DocFx.AspNetCore.ServerSentEvents/articles/disconneting-clients.md

@@ -0,0 +1,91 @@
+# Disconneting Clients
+
+There is an option to disconnect a client from server. The flow is based on responding with *204 No Content* status code to reconnect attempt.
+
+<center>![Server-Sent Events Client Disconnect Flow Diagram](../resources/disconneting-client-flow.png)</center>
+
+## Prerequisites
+
+The client disconnect functionality requires registering two services, which are not registered by default.
+
+### Client Identifier Provider
+
+First is implementation of [`IServerSentEventsClientIdProvider`](../api/Lib.AspNetCore.ServerSentEvents.IServerSentEventsClientIdProvider.html), which responsibility is to provide an identifier for a client. This identifier should remain the same if client performs reconnect(s). There is no ready to use implementation of this provider, as the approach to this should strongly depend on context. Below is a sample cookie based implementation (which is certainly not sophisticated enough for production scenarios).
+
+```cs
+internal class CookieBasedServerSentEventsClientIdProvider : IServerSentEventsClientIdProvider
+{
+    private const string COOKIE_NAME = ".ServerSentEvents.Guid";
+
+    public Guid AcquireClientId(HttpContext context)
+    {
+        Guid clientId;
+
+        string cookieValue = context.Request.Cookies[COOKIE_NAME];
+        if (String.IsNullOrWhiteSpace(cookieValue) || !Guid.TryParse(cookieValue, out clientId))
+        {
+            clientId = Guid.NewGuid();
+
+            context.Response.Cookies.Append(COOKIE_NAME, clientId.ToString());
+        }
+
+        return clientId;
+    }
+
+    public void ReleaseClientId(Guid clientId, HttpContext context)
+    {
+        context.Response.Cookies.Delete(COOKIE_NAME);
+    }
+}
+```
+
+There is a helper method which simplifies registering an implementation.
+
+```cs
+public class Startup
+{
+    ...
+
+    public void ConfigureServices(IServiceCollection services)
+    {
+        services.AddServerSentEvents();
+
+        // Register cookie based clients identifier provider for Server Sent Events
+        services.AddServerSentEventsClientIdProvider<CookieBasedServerSentEventsClientIdProvider>();
+
+        ...
+    }
+
+    ...
+}
+```
+
+### "No Reconnect" Identifiers Store
+
+Second is implementation of [`IServerSentEventsNoReconnectClientsIdsStore`](../api/Lib.AspNetCore.ServerSentEvents.IServerSentEventsNoReconnectClientsIdsStore.html), which responsibility is to store identifiers which should not be allowed to reconnect. There are two ready to use implementations. First stores the identifiers in memory, while the second is backed by distributed cache. Both have ready to use methods to register them.
+
+```cs
+public class Startup
+{
+    ...
+
+    public void ConfigureServices(IServiceCollection services)
+    {
+        services.AddServerSentEvents();
+
+        // Register cookie based clients identifier provider for Server Sent Events
+        services.AddServerSentEventsClientIdProvider<CookieBasedServerSentEventsClientIdProvider>();
+
+        // Register IServerSentEventsNoReconnectClientsIdsStore backed by memory store.
+        services.AddInMemoryServerSentEventsNoReconnectClientsIdsStore();
+
+        ...
+    }
+
+    ...
+}
+```
+
+## Disconnecting a Client
+
+Disconnecting a client is as simple as calling `Disconnect()` on a [`IServerSentEventsClient`](../api/Lib.AspNetCore.ServerSentEvents.IServerSentEventsClient.html).

DocFx.AspNetCore.ServerSentEvents/docfx.json

@@ -26,6 +26,7 @@
           "articles/getting-started.md",
           "articles/authorization.md",
           "articles/groups.md",
+          "articles/disconneting-clients.md",
           "articles/advanced.md"
         ]
       }
@@ -34,7 +35,8 @@
       {
         "files": [
           "resources/svg/logo.svg",
-          "resources/ico/favicon.ico"
+          "resources/ico/favicon.ico",
+          "resources/disconneting-client-flow.png"
         ]
       }
     ],

DocFx.AspNetCore.ServerSentEvents/index.md

@@ -1,4 +1,6 @@
 # Lib.AspNetCore.ServerSentEvents
+[![NuGet Version](https://img.shields.io/nuget/v/Lib.AspNetCore.ServerSentEvents?label=Lib.AspNetCore.ServerSentEvents&logo=nuget)](https://www.nuget.org/packages/Lib.AspNetCore.ServerSentEvents)
+[![NuGet Downloads](https://img.shields.io/nuget/dt/Lib.AspNetCore.ServerSentEvents?label=⭳)](https://www.nuget.org/packages/Lib.AspNetCore.ServerSentEvents)
 
 Lib.AspNetCore.ServerSentEvents is a library which provides Server-Sent Events (SSE) support for ASP.NET Core.
 
@@ -24,8 +26,8 @@ There are some blog posts available which describe implementation details and so
 - [Server-Sent Events (or WebSockets) broadcasting in load balancing scenario with Redis](https://www.tpeczek.com/2017/09/server-sent-events-or-websockets.html)
 - [Server-Sent Events and ASP.NET Core - You may need keep alives](https://www.tpeczek.com/2018/08/server-sent-events-and-aspnet-core-you_9.html)
 
-## Donating
+## Sponsor this project
 
-My blog and open source projects are result of my passion for software development, but they require a fair amount of my personal time. If you got value from any of the content I create, then I would appreciate your support by [buying me a coffee](https://www.buymeacoffee.com/tpeczek).
+My blog and open source projects are result of my passion for software development, but they require a fair amount of my personal time. If you got value from any of the content I create, then I would appreciate your support by sponsoring me.
 
-<a href="https://www.buymeacoffee.com/tpeczek"><img src="https://www.buymeacoffee.com/assets/img/custom_images/black_img.png" style="height: 41px !important;width: 174px !important;box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;-webkit-box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;"  target="_blank"></a>
+<iframe src="https://github.com/sponsors/tpeczek/button" title="Sponsor tpeczek" height="35" width="116" style="border: 0;"></iframe>

DocFx.AspNetCore.ServerSentEvents/resources/disconneting-client-flow.png

@@ -6,6 +6,8 @@
 
 # [Groups](articles/groups.md)
 
+# [Disconneting Clients](articles/disconneting-clients.md)
+
 # [Advanced](articles/advanced.md)
 
 # [API Reference](api/Lib.AspNetCore.ServerSentEvents.html)

DocFx.AspNetCore.ServerSentEvents/toc.md

@@ -0,0 +1,32 @@
+using System;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Caching.Distributed;
+
+namespace Lib.AspNetCore.ServerSentEvents
+{
+    internal class DistributedServerSentEventsNoReconnectClientsIdsStore : IServerSentEventsNoReconnectClientsIdsStore
+    {
+        private readonly IDistributedCache _cache;
+        private readonly byte[] _dummyItem = new byte[0];
+
+        public DistributedServerSentEventsNoReconnectClientsIdsStore(IDistributedCache cache)
+        {
+            _cache = cache ?? throw new ArgumentNullException(nameof(cache));
+        }
+
+        public async Task AddClientIdAsync(Guid clientId)
+        {
+            await _cache.SetAsync(clientId.ToString(), _dummyItem);
+        }
+
+        public async Task<bool> ContainsClientIdAsync(Guid clientId)
+        {
+            return (await _cache.GetAsync(clientId.ToString())) is null;
+        }
+
+        public async Task RemoveClientIdAsync(Guid clientId)
+        {
+            await _cache.RemoveAsync(clientId.ToString());
+        }
+    }
+}

Lib.AspNetCore.ServerSentEvents/DistributedServerSentEventsNoReconnectClientsIdsStore.cs

@@ -28,6 +28,14 @@ public interface IServerSentEventsClient
         #endregion
 
         #region Methods
+        /// <summary>
+        /// Disconnects client.
+        /// </summary>
+        /// <remarks>
+        /// This requires registering implementations of <see cref="IServerSentEventsClientIdProvider"/> and <see cref="IServerSentEventsNoReconnectClientsIdsStore"/>.
+        /// </remarks>
+        void Disconnect();
+
         /// <summary>
         /// Sends event to client.
         /// </summary>

Lib.AspNetCore.ServerSentEvents/IServerSentEventsClient.cs

@@ -0,0 +1,25 @@
+using System;
+using Microsoft.AspNetCore.Http;
+
+namespace Lib.AspNetCore.ServerSentEvents
+{
+    /// <summary>
+    /// Contract for provider of identifiers for <see cref="IServerSentEventsClient"/> instances based on <see cref="HttpContext"/>.
+    /// </summary>
+    public interface IServerSentEventsClientIdProvider
+    {
+        /// <summary>
+        /// Acquires an identifier which will be used by <see cref="IServerSentEventsClient"/>.
+        /// </summary>
+        /// <param name="context">The context.</param>
+        /// <returns>The identifier.</returns>
+        Guid AcquireClientId(HttpContext context);
+
+        /// <summary>
+        /// Releases an identifier so it no longer represents any active <see cref="IServerSentEventsClient"/>.
+        /// </summary>
+        /// <param name="clientId">The identifier.</param>
+        /// <param name="context">The context.</param>
+        void ReleaseClientId(Guid clientId, HttpContext context);
+    }
+}