Performance considerations article (#2)

Author: tpeczek

DocFx.Net.Http.WebPush/DocFx.Net.Http.WebPush.csproj

@@ -6,7 +6,6 @@
     <None Remove="log.txt" />
   </ItemGroup>
   <ItemGroup>
-    <Folder Include="articles\" />
     <Folder Include="wwwroot\" />
   </ItemGroup>
   <ItemGroup>

DocFx.Net.Http.WebPush/articles/performance-considerations.md

@@ -0,0 +1,46 @@
+# Performance Considerations
+
+A typical application can be processing a very high number of *Push Messages*. Because of that it's important to consider performance best practices.
+
+## Proper Instantiation
+
+The [`PushServiceClient`](../api/Lib.Net.Http.WebPush.PushServiceClient.html) class is internally holding an instance of `HttpClient` class. As one can read in documentation:
+
+> HttpClient is intended to be instantiated once and re-used throughout the life of an application. Instantiating an HttpClient class for every request will exhaust the number of sockets available under heavy loads.
+
+Because of that (in order to avoid Improper Instantiation antipattern) a shared singleton instance of `PushServiceClient` should be created or a pool of reusable instances should be used.
+
+## VAPID Tokens Caching
+
+Generating *VAPID* tokens requires expensive cryptography. The structure of tokens allows for them to be cached per *Audience* (which means by *Push Service*) and *Application Server Keys* pair (for the token expiration period). This library provides such possibility through [`IVapidTokenCache`](../api/Lib.Net.Http.WebPush.Authentication.IVapidTokenCache.html). If an implementation of this interface will be provided to [`VapidAuthentication`](../api/Lib.Net.Http.WebPush.Authentication.VapidAuthentication.html) instance, it will result in tokens being cached.
+
+Below is a sample implementation which uses [ASP.NET Core in-memory caching](https://docs.microsoft.com/en-us/aspnet/core/performance/caching/memory).
+
+```cs
+public class MemoryVapidTokenCache : IVapidTokenCache
+{
+    private readonly IMemoryCache _memoryCache;
+
+    public MemoryVapidTokenCache(IMemoryCache memoryCache)
+    {
+        _memoryCache = memoryCache;
+    }
+
+    public string Get(string audience)
+    {
+        if (!_memoryCache.TryGetValue(audience, out string token))
+        {
+            token = null;
+        }
+
+        return token;
+    }
+
+    public void Put(string audience, DateTimeOffset expiration, string token)
+    {
+        _memoryCache.Set(audience, token, expiration);
+    }
+}
+```
+
+The usage of *Audience* as cache key means that intended context of this interface is a single *Application Server Keys* pair. If application is handling multiple *Application Server Keys* pairs it should provide a separate implementation for every pair and make sure those doesn't clash.

DocFx.Net.Http.WebPush/docfx.json

@@ -22,7 +22,8 @@
         "files": [
           "api/*.yml",
           "toc.md",
-          "index.md"
+          "index.md",
+          "articles/performance-considerations.md"
         ]
       }
     ],

DocFx.Net.Http.WebPush/index.md

@@ -1,6 +1,6 @@
 # Lib.Net.Http.WebPush
 
-Lib.Net.Http.WebPush is a library which provides a [Web Push Protocol](https://tools.ietf.org/html/rfc8030) based client for Push Service. It provides support for [Voluntary Application Server Identification (VAPID) for Web Push](https://tools.ietf.org/html/rfc8292) and [Message Encryption for Web Push](https://tools.ietf.org/html/rfc8291).
+Lib.Net.Http.WebPush is a library which provides a [*Web Push Protocol*](https://tools.ietf.org/html/rfc8030) based client for *Push Service*. It provides support for [Voluntary Application Server Identification (*VAPID*) for Web Push](https://tools.ietf.org/html/rfc8292) and [Message Encryption for Web Push](https://tools.ietf.org/html/rfc8291).
 
 ## Installation
 
@@ -14,6 +14,14 @@ PM>  Install-Package Lib.Net.Http.WebPush
 
 There is a demo project available [here](https://github.com/tpeczek/Demo.AspNetCore.PushNotifications).
 
+## Additional Resources
+
+There is a "Push Notifications and ASP.NET Core" series which provides a lot of information about *Push API*, *Web Push Protocol* and internals of this library:
+
+- [Push Notifications and ASP.NET Core - Part 1 (Push API)](https://www.tpeczek.com/2017/12/push-notifications-and-aspnet-core-part.html)
+- [Push Notifications and ASP.NET Core - Part 2 (Requesting Delivery)](https://www.tpeczek.com/2018/01/push-notifications-and-aspnet-core-part.html)
+- [Push Notifications and ASP.NET Core - Part 3 (Replacing Messages & Urgency)](https://www.tpeczek.com/2018/01/push-notifications-and-aspnet-core-part_18.html)
+
 ## Donating
 
 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).

DocFx.Net.Http.WebPush/toc.md

@@ -1,3 +1,5 @@
 # [Introduction](index.md)
 
+# [Performance Considerations](articles/performance-considerations.md)
+
 # [API Reference](api/Lib.Net.Http.WebPush.html)