When using ASP.NET Core SignalR, we can perform invocations which don't return anything, invocations which return a result, and invocations which results in a stream of results. Unfortunately, invocations which return a result or a stream of results are available only when invoking server from a client. If a server wants to invoke a client, the only option is invocation which doesn't return anything. ASP.NET Core SignalR is supposed to bring streaming from client to server but again only as part of an invocation from client to a server. Sometimes there are scenarios where we would like a client to be able to respond to invocation - a server-to-client remote procedure call (RPC) with a result.

What We Want

ASP.NET Core has a concept of strongly typed hubs which allows for representing client methods as an interface. For a server-to-client RPC with a result scenario, such an interface should look like below.

public interface IRpc
{
    Task<MethodResponse> MethodCall(MethodParams methodParams);
}

With the following, corresponding, strongly typed hub.

public class RpcHub : Hub
{
    ...
}

The hub doesn't need to have any methods. Of course, we want to handle connection events to maintain a list of currently connected users, but if a trigger is something from our infrastructure (message from a queue, change from a database, etc.) that's all we need. Let's assume that's exactly the case, that clients methods are being invoked from a BackgroundService which is listening for that trigger. Below is a code of such BackgroundService limited to SignalR aspects.

public class RpcCallerBackgroundService : BackgroundService
{
    private readonly IHubContext<RpcHub, IRpc> _rpcHubContext;

    public RpcCallerBackgroundService(IHubContext<RpcHub, IRpc> rpcHubContext)
    {
        _rpcHubContext = rpcHubContext;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (...)
        {
            ...

            MethodResponse response = await _rpcHubContext.Clients.User(userId).MethodCall(new MethodParams
            {
                ...
            });
        }
    }
}

All the code so far we can write right now. It will even compile. Sadly it won't work. If you would put this code into your application, you would get a System.InvalidOperationException upon startup with a message more or less like this:

Cannot generate proxy implementation for 'IRpc.MethodCall'. All client proxy methods must return 'System.Threading.Tasks.Task'.

So, on the server side, we can write the code we want but it will result in an exception. How about the client side?

Imagine that a client is a generic host based worker service, which is using a BackgroundService to maintain a SignalR connection with a server. Implementation of such BackgroundService for our IRpc interface could be something like this.

public class RpcClientBackgroundService : BackgroundService
{
    private readonly HubConnection _rpcResponseHubConnection;

    public RpcClientBackgroundService()
    {
        _rpcResponseHubConnection = new HubConnectionBuilder()
            .WithUrl("...")
            .Build();
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        IDisposable _methodCallHandler = _rpcResponseHubConnection.On(nameof(IRpc.MethodCall), new[] { typeof(MethodParams) },
            async (methodParamsArray) =>
            {
                ...
            });

        await _rpcResponseHubConnection.StartAsync();

        await WaitForCancellationAsync(stoppingToken);

        _methodCallHandler.Dispose();

        await _rpcResponseHubConnection.DisposeAsync();
    }

    ...
}

Here we can't even implement what we want. The only overload of On method which takes a Func, forces return type to be a Task. Other overloads take an Action.

I've spent a lot of lines on proving that we can't have what we want. Is there something we can have?

What We Can Have

The only way for a client to return something to a server is to invoke it back. So the only possible approach, from SignalR perspective, is to have two invocations, which we can represent by two interfaces.

public interface IRpcCalls
{
    Task MethodCall(MethodParams methodParams);
}

public interface IRpcResponseHandlers
{
    Task MethodResponseHandler(MethodResponse response);
}

Another consequence is that we will have to correlate those invocations. We need something in payloads that will allow us to do that.

public class MethodParams
{
    public Guid MethodCallId { get; set; }

    ...
}

public class MethodResponse
{
    public Guid MethodCallId { get; set; }

    ...
}

Now we can change the client BackgroundService to perform an invocation of MethodResponseHandler when the processing of MethodCall is finished.

public class RpcBackgroundService : BackgroundService
{
    ...

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        IDisposable _methodCallHandler = _rpcResponseHubConnection.On<MethodParams>(nameof(IRpcCalls.MethodCall),
            methodParams =>
            {
                ...

                _rpcResponseHubConnection.InvokeAsync(nameof(IRpcResponseHandlers.MethodResponseHandler), new MethodResponse
                {
                    MethodCallId = methodParams.MethodCallId,
                    ...
                });
            });

        ...
    }

    ...
}

That was the easy part. Changing the server part is a little bit harder. The BackgroundService on the server side will not be able to use IHubContext directly, we need to introduce something that will hide the split into two invocations. We want that something to be similar to IHubContext in a way that it's a generic, where the type of hub is used as a type parameter. This way we can enforce that hub to implement IRpcResponseHandlers interface and to be a strongly typed one with client methods represented by IRpcCalls interface.

public interface IRpcCaller<THub> : IRpc, IRpcResponseHandlers
    where THub : Hub<IRpcCalls>, IRpcResponseHandlers
{ }

public class RpcCaller<THub> : IRpcCaller
    where THub : Hub<IRpcCalls>, IRpcResponseHandlers
{
    private readonly IHubContext<THub, IRpcCalls> _hubContext;

    public RpcCaller(IHubContext<THub, IRpcCalls> hubContext)
    {
        _hubContext = hubContext;
    }

    ...
}

Why IRpcCaller is composed of IRpc and IRpcResponseHandler? The IRpc will be needed by the BackgroundService, but we also need a way for the hub to pass the invocation response to IRpcCaller.

Before we can start implementation, we also need to make a change to IRpc interface. As the implementation will hide IHubContext, the user identifier needs to be passed as a parameter.

public interface IRpc
{
    Task<MethodResponse> MethodCall(string userId, MethodParams methodParams);
}

So, how do we synchronize those two invocations and make the method wait until the response is available? One wait to implement TAP (Task-based Asynchronous Pattern) is to do it manually with the help of TaskCompletionSource. As we can have a number of simultaneous calls, we will need a ConcurrentDictionary of those. Whenever a new call is made we will create a TaskCompletionSource, add it to the dictionary, and use its Task.

public class RpcCaller<THub> : IRpcCaller
    where THub : Hub<IRpcCalls>, IRpcResponseHandlers
{
    ...
    private readonly ConcurrentDictionary<Guid, TaskCompletionSource<MethodResponse>> _pendingMethodCalls =
        new ConcurrentDictionary<Guid, TaskCompletionSource<MethodResponse>>();

    ...

    public async Task<MethodResponse> MethodCall(string userId, MethodParams methodParams)
    {
        methodParams.MethodCallId = Guid.NewGuid();

        TaskCompletionSource<MethodResponse> methodCallCompletionSource = new TaskCompletionSource<MethodResponse>();
        if (_pendingMethodCalls.TryAdd(methodParams.MethodCallId, methodCallCompletionSource))
        {
            await _hubContext.Clients.User(userId).MethodCall(methodParams);

            return await methodCallCompletionSource.Task;
        }

        throw new Exception("Couldn't call the method.");
    }

    ...
}

Here comes the IRpcResponseHandler part. Calling the MethodResponseHandler will remove the TaskCompletionSource from the dictionary and will set its result.

public class RpcCaller<THub> : IRpcCaller
    where THub : Hub<IRpcCalls>, IRpcResponseHandlers
{
    ...

    public Task MethodResponseHandler(MethodResponse response)
    {
        if (_pendingMethodCalls.TryRemove(response.MethodCallId, out TaskCompletionSource<MethodResponse> methodCallCompletionSource))
        {
            methodCallCompletionSource.SetResult(response);
        }

        return Task.CompletedTask;
    }
}

One very important thing is to remember that we must be sure that the user with the specified identifier is connected. SignalR does nothing when User(userId).MethodCall is called for user which is not connected. It will not return any error or throw an exception. In this scenario, this might be a source of potential issue. In such a case, the TaskCompletionSource will be created and its Task used, but that Task will never complete.

With IRpcCaller ready, the hub can be changed to comply with requirements.

public class RpcHub : Hub<IRpcCalls>, IRpcResponseHandlers
{
    private readonly IRpcCaller<RpcHub> _rpcCaller;

    public RpcHub(IRpcCaller<RpcHub> rpcCaller)
    {
        _rpcCaller = rpcCaller;
    }

    public Task MethodResponseHandler(MethodResponse response)
    {
        return _rpcCaller.MethodResponseHandler(response);
    }

    ...
}

What's remaining is changes in server BackgroundService, which essentially means replacing IHubContext with IRpcCaller.

public class RpcCallerBackgroundService : BackgroundService
{
    private readonly IRpcCaller<RpcHub> _rpcCaller;

    public RpcCallerBackgroundService(IRpcCaller<RpcHub> rpcCaller)
    {
        _rpcCaller = rpcCaller;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (...)
        {
            ...

            MethodResponse response = await _rpcCaller.MethodCall(userId, new MethodParams
            {
                ...
            });
        }
    }
}

This is what we can have.

We Can't Have Nice Things

Is this a nice thing? Well not really. In order to enforce as much as possible, it's more complicated than it should be. And it still leaves room for human errors. But it gets the job done and in scenarios where enforcing interfaces implementation is not that important (for example interfaces are highly unlikely to change), it can be simplified.

It's been a while since I've written my last post in Push Notifications and ASP.NET Core series. Since that time I've received a number of questions about more uncommon aspects of Push Notifications, so I've decided I need to write another one.

In this post, I'm going to focus on special cases which a production-ready application using push notifications should be able to handle.

Handling Out-Of-Control Subscription Changes on the Client Side

There are several things which can happen to a push subscription outside of the application's control. For example, it can be refreshed, lost, expired or permissions can be revoked. When something like this happens, the browser should fire a pushsubscriptionchange event on service worker registration, to inform it about the change. Service worker should use information provided by this event to update the server.

The pushsubscriptionchange event is often misused. This is because its definition has changed. In the beginning, the event was defined to fire when a subscription has expired. Because of that, many sample implementations available on the web are limited to resubscribe attempt. Currently, this is not the correct approach. The event has two properties: newSubscription and oldSubscription. Depending on those properties values, different actions should be taken.

self.addEventListener('pushsubscriptionchange', function (event) {
    const handlePushSubscriptionChangePromise = Promise.resolve();

    if (event.oldSubscription) { }

    if (event.newSubscription) { }

    if (!event.newSubscription) { }

    event.waitUntil(handlePushSubscriptionChangePromise);
});

The value of oldSubscription represents a push subscription that is no longer valid. The subscription should be removed from the server. This is not a bulletproof mechanism, the value may be null if the browser was not able to provide the full set of details.

self.addEventListener('pushsubscriptionchange', function (event) {
    const handlePushSubscriptionChangePromise = Promise.resolve();

    if (event.oldSubscription) {
        handlePushSubscriptionChangePromise = handlePushSubscriptionChangePromise.then(function () {
            return fetch('push-notifications-api/subscriptions?endpoint=' + encodeURIComponent(event.oldSubscriptio.endpoint), {
                method: 'DELETE'
            });
        });
    }

    ...
});

The value of newSubscription represents a new valid push subscription. If the value is there, it should be sent to the server. But, similar to oldSubscription, the value may be null. This means that the browser didn't establish a new subscription. At this point, the code can attempt to resubscribe after retrieving public VAPID key from the server (the key change is often why browser couldn't establish new subscription). The attempt may fail (for example the reason for triggering the event was user revoking the permissions). In such a case, there is nothing more that can be done.

self.addEventListener('pushsubscriptionchange', function (event) {
    const handlePushSubscriptionChangePromise = Promise.resolve();

    ...

    if (event.newSubscription) {
        handlePushSubscriptionChangePromise = handlePushSubscriptionChangePromise.then(function () {
            return fetch('push-notifications-api/subscriptions', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify(pushSubscription)
            });
        });
    }

    if (!event.newSubscription) {
        handlePushSubscriptionChangePromise = handlePushSubscriptionChangePromise.then(function () {
            return fetch('push-notifications-api/public-key').then(function (response) {
                if (response.ok) {
                    return response.text().then(function (applicationServerPublicKeyBase64) {
                        return urlB64ToUint8Array(applicationServerPublicKeyBase64);
                    });
                } else {
                    return Promise.reject(response.status + ' ' + response.statusText);
                }
            }).then(function (applicationServerPublicKey) {
                return pushServiceWorkerRegistration.pushManager.subscribe({
                    userVisibleOnly: true,
                    applicationServerKey: applicationServerPublicKey
                }).then(function (pushSubscription) {
                    return fetch('push-notifications-api/subscriptions', {
                        method: 'POST',
                        headers: { 'Content-Type': 'application/json' },
                        body: JSON.stringify(pushSubscription)
                    });
                });
            });
        });
    }

    event.waitUntil(handlePushSubscriptionChangePromise);
});

Handling Out-Of-Control Subscription Changes on the Server Side

The pushsubscriptionchange event is not a silver bullet to all potential issues. Even if it's triggered, it may not provide the oldSubscription. In general, it may happen that application will send a notification to removed, expired or otherwise invalid subscription. If that happens, Push Service will respond with 410 or 404 status. The application must be prepared for such a response and discard the subscription. In case of Lib.Net.Http.WebPush failed requests end up as PushServiceClientException. It's enough to catch this exception, check StatusCode property and act accordingly.

internal class PushServicePushNotificationService : IPushNotificationService
{
    ...

    public async Task SendNotificationAsync(PushSubscription subscription, PushMessage message, CancellationToken cancellationToken)
    {
        try
        {
            await _pushClient.RequestPushMessageDeliveryAsync(subscription, message, cancellationToken);
        }
        catch (Exception ex)
        {
            await HandlePushMessageDeliveryExceptionAsync(ex, subscription);
        }
    }

    private async Task HandlePushMessageDeliveryExceptionAsync(Exception exception, PushSubscription subscription)
    {
        PushServiceClientException pushServiceClientException = exception as PushServiceClientException;

        if (pushServiceClientException is null)
        {
            _logger?.LogError(exception, "Failed requesting push message delivery to {0}.", subscription.Endpoint);
        }
        else
        {
            if ((pushServiceClientException.StatusCode == HttpStatusCode.NotFound)
                || (pushServiceClientException.StatusCode == HttpStatusCode.Gone))
            {
                // Remove subcription from store
                ...

                _logger?.LogInformation("Subscription has expired or is no longer valid and has been removed.");
            }
        }
    }
}

The implementation may get a little bit complicated. Notifications are usually sent outside of request scope, from singleton services, and often with a fire-and-forget approach. If storage service is a scoped one (which is typical when Entity Framework is being used), this will enforce additional code to manage scope and storage service instance. This strongly depends on the particular project approach, but usually can be solved without too much trouble.

Dealing with Rate Limiting

One more common problem when using push notifications is reaching a rate limit with a push service. When this happens push service responds with 429 Too Many Requests which should include a Retry-After header. What application should do is wait given period of time and resend the notification. I believe this kind of functionality should be built into a client. This is why I've added it to Lib.Net.Http.WebPush. Lib.Net.Http.WebPush determines if an attempt to resend should be made based on status code and Retry-After header presence.

private bool ShouldRetryAfter(HttpResponseMessage pushMessageDeliveryRequestResponse, out TimeSpan delay)
{
    delay = TimeSpan.MinValue;

    if ((pushMessageDeliveryRequestResponse.StatusCode != (HttpStatusCode)429) || !AutoRetryAfter)
    {
        return false;
    }

    if ((pushMessageDeliveryRequestResponse.Headers.RetryAfter is null)
        || (!pushMessageDeliveryRequestResponse.Headers.RetryAfter.Date.HasValue && !pushMessageDeliveryRequestResponse.Headers.RetryAfter.Delta.HasValue))
    {
        return false;
    }

    if (pushMessageDeliveryRequestResponse.Headers.RetryAfter.Delta.HasValue)
    {
        delay = pushMessageDeliveryRequestResponse.Headers.RetryAfter.Delta.Value;
    }

    if (pushMessageDeliveryRequestResponse.Headers.RetryAfter.Date.HasValue)
    {
        delay = pushMessageDeliveryRequestResponse.Headers.RetryAfter.Date.Value.Subtract(DateTimeOffset.UtcNow);
    }

    return true;
}

The check is used to create an optional waiting loop while sending a notification.

public async Task RequestPushMessageDeliveryAsync(PushSubscription subscription, PushMessage message, VapidAuthentication authentication,
    VapidAuthenticationScheme authenticationScheme, CancellationToken cancellationToken)
{
    HttpRequestMessage pushMessageDeliveryRequest =
        PreparePushMessageDeliveryRequest(subscription, message, authentication, authenticationScheme);

    HttpResponseMessage pushMessageDeliveryRequestResponse =
        await _httpClient.SendAsync(pushMessageDeliveryRequest, HttpCompletionOption.ResponseHeadersRead, cancellationToken);

    while (ShouldRetryAfter(pushMessageDeliveryRequestResponse, out TimeSpan delay))
    {
        await Task.Delay(delay, cancellationToken);

        pushMessageDeliveryRequest =
            SetAuthentication(pushMessageDeliveryRequest, subscription, authentication ?? DefaultAuthentication, authenticationScheme);

        pushMessageDeliveryRequestResponse =
            await _httpClient.SendAsync(pushMessageDeliveryRequest, HttpCompletionOption.ResponseHeadersRead, cancellationToken);
    }

    HandlePushMessageDeliveryRequestResponse(pushMessageDeliveryRequest, pushMessageDeliveryRequestResponse, cancellationToken);
}

There is one small, important detail here. For every retry, the authentication is set again. This avoids a situation where JWT has expired while waiting for retry.

Footnote

I've updated my demo project with all the above changes, you can grab it here. I hope it will help you to use push notifications in your own applications.

One of my talks is talk about native real-time technologies like WebSockets, Server-Sent Events, and Web Push in ASP.NET Core. In that talk, I briefly go through the subject of scaling applications based on those technologies. For Web Push, I mention that it can be scaled with help of microservices or functions, because it doesn't require an active HTTP request/response. After the talk, I'm frequently asked for some samples of how to do that. This post is me finally putting one together.

Sending Web Push Notifications from Azure Functions

I've written a series of posts about Web Push Notifications. In general, it's good to understand one level deeper than what you're working at (so I encourage you to go through that series), but for this post, it's enough to know that you can grab a client from NuGet. This client is all that is needed to send a notification from Azure Function, so let's quickly create one.

The function will use Azure Cosmos DB as a data source. Whenever an insert or update happens in NotificationsCollection, the function will be triggered.

public static class SendNotificationFunction
{
    [FunctionName("SendNotification")]
    public static void Run(
        [CosmosDBTrigger("PushNotifications", "NotificationsCollection",
        LeaseCollectionName = "NotificationsLeaseCollection", CreateLeaseCollectionIfNotExists = true,
        ConnectionStringSetting = "CosmosDBConnection")]
        IReadOnlyList<PushMessage> notifications)
    {

    }
}

You may notice that it's using an extension for Azure Cosmos DB Trigger described in my previous post, which allows for taking a collection of POCOs as an argument.

The second piece of data kept in Cosmos DB is subscriptions. The function will need to query all subscriptions to send notifications. This is best done by using DocumentClient.

public static class SendNotificationFunction
{
    private static readonly Uri _subscriptionsCollectionUri =
        UriFactory.CreateDocumentCollectionUri("PushNotifications", "SubscriptionsCollection");

    [FunctionName("SendNotification")]
    public static void Run(
        ...,
        [CosmosDB("PushNotifications", "SubscriptionsCollection", ConnectionStringSetting = "CosmosDBConnection")]
        DocumentClient client)
    {
        if (notifications != null)
        {
            IDocumentQuery<PushSubscription> subscriptionQuery =
                client.CreateDocumentQuery<PushSubscription>(_subscriptionsCollectionUri, new FeedOptions
                {
                    EnableCrossPartitionQuery = true,
                    MaxItemCount = -1
                }).AsDocumentQuery();
        }
    }
}

Now the function is almost ready to send notifications. Last missing part is PushServiceClient. An instance of PushServiceClient is internally holding an instance of HttpClient. This means that improper instantiation antipattern must be taken into consideration. The simplest approach is to create a static instance.

public static class SendNotificationFunction
{
    ...
    private static readonly PushServiceClient _pushClient = new PushServiceClient
    {
        DefaultAuthentication = new VapidAuthentication(
            "<Application Server Public Key>",
            "<Application Server Private Key>")
        {
            Subject = "<Subject>"
        }
    };

    [FunctionName("SendNotification")]
    public static void Run(...)
    {
        ...
    }
}

Sending notifications is now nothing more than calling RequestPushMessageDeliveryAsync for every combination of subscription and notification.

public static class SendNotificationFunction
{
    ...

    [FunctionName("SendNotification")]
    public static async Task Run(...)
    {
        if (notifications != null)
        {
            ...

            while (subscriptionQuery.HasMoreResults)
            {
                foreach (PushSubscription subscription in await subscriptionQuery.ExecuteNextAsync())
                {
                    foreach (PushMessage notification in notifications)
                    {
                        // Fire-and-forget
                        _pushClient.RequestPushMessageDeliveryAsync(subscription, notification);
                    }
                }
            }
        }
    }
}

And that's it. A very simple Azure Function taking care of broadcast notifications.

Improvements, Improvements ...

The code above can be better. I'm not thinking about the Cosmos DB part (although there are ways to better utilize partitioning or implement fan-out approach with help of durable functions). The usage of PushServiceClient is far from perfect. Static instance makes configuration awkward and may cause issues due to static HttpClient not respecting DNS changes. In the past, I've written about using HttpClientFactory and making HttpClient injectable in Azure Functions. The exact same approach can be used here. I will skip the boilerplate code, it's described in that post. I'll focus only on things specific to PushServiceClient.

First thing is an attribute. It will allow taking PushServiceClient instance as a function parameter. It will also help solve the configuration problem, by providing properties for names of settings with needed values.

[Binding]
[AttributeUsage(AttributeTargets.Parameter)]
public sealed class PushServiceAttribute : Attribute
{
    [AppSetting]
    public string PublicKeySetting { get; set; }

    [AppSetting]
    public string PrivateKeySetting { get; set; }

    [AppSetting]
    public string SubjectSetting { get; set; }
}

The second thing is a converter which will use HttpClientFactory and instance of PushServiceAttribute to create a properly initialized PushServiceClient. Luckily PushServiceClient has a constructor which takes HttpClient instance as a parameter, so it's quite simple.

internal class PushServiceClientConverter : IConverter<PushServiceAttribute, PushServiceClient>
{
    private readonly IHttpClientFactory _httpClientFactory;

    public PushServiceClientConverter(IHttpClientFactory httpClientFactory)
    {
        _httpClientFactory = httpClientFactory ?? throw new ArgumentNullException(nameof(httpClientFactory));
    }

    public PushServiceClient Convert(PushServiceAttribute attribute)
    {
        return new PushServiceClient(_httpClientFactory.CreateClient())
        {
            DefaultAuthentication = new VapidAuthentication(attribute.PublicKeySetting, attribute.PrivateKeySetting)
            {
                Subject = attribute.SubjectSetting
            }
        };
    }
}

The last thing is IExtensionConfigProvider which will add a binding rule for PushServiceAttribute and tell the Azure Functions runtime to use PushServiceClientConverter for providing PushServiceClient instance.

[Extension("PushService")]
internal class PushServiceExtensionConfigProvider : IExtensionConfigProvider
{
    private readonly IHttpClientFactory _httpClientFactory;

    public PushServiceExtensionConfigProvider(IHttpClientFactory httpClientFactory)
    {
        _httpClientFactory = httpClientFactory;
    }

    public void Initialize(ExtensionConfigContext context)
    {
        if (context == null)
        {
            throw new ArgumentNullException(nameof(context));
        }

        //PushServiceClient Bindings
        var bindingAttributeBindingRule = context.AddBindingRule<PushServiceAttribute>();
        bindingAttributeBindingRule.AddValidator(ValidateVapidAuthentication);

        bindingAttributeBindingRule.BindToInput<PushServiceClient>(typeof(PushServiceClientConverter), _httpClientFactory);
    }

    ...
}

I've skipped the code which reads and validates settings. If you're interested you can find it on GitHub.

With the above extension in place, the static instance of PushServiceClient is no longer needed.

public static class SendNotificationFunction
{
    ...

    [FunctionName("SendNotification")]
    public static async Task Run(
        ...,
        [PushService(PublicKeySetting = "ApplicationServerPublicKey",
        PrivateKeySetting = "ApplicationServerPrivateKey", SubjectSetting = "ApplicationServerSubject")]
        PushServiceClient pushServiceClient)
    {
        if (notifications != null)
        {
            ...

            while (subscriptionQuery.HasMoreResults)
            {
                foreach (PushSubscription subscription in await subscriptionQuery.ExecuteNextAsync())
                {
                    foreach (PushMessage notification in notifications)
                    {
                        // Fire-and-forget
                        pushServiceClient.RequestPushMessageDeliveryAsync(subscription, notification);
                    }
                }
            }
        }
    }
}

You Don't Have to Reimplement This by Yourself

The PushServiceClient binding extension is available on NuGet. I have also pushed the demo project to GitHub. Hopefully it will help you to get the best out of Web Push Notifications.

This is my fourth post about Azure Functions extensibility. So far I've written about triggers, inputs, and outputs (maybe I should devote some more time to outputs, but that's something for another time). In this post, I want to focus on something I haven't mentioned yet - extending existing extensions. As usual, I intend to do it in a practical context.

Common problem with the Azure Cosmos DB Trigger

There is a common problem with the Azure Cosmos DB Trigger for Azure Functions. Let's consider the sample from the documentation.

public class ToDoItem
{
    public string Id { get; set; }
    public string Description { get; set; }
}
public static class CosmosTrigger
{
    [FunctionName("CosmosTrigger")]
    public static void Run([CosmosDBTrigger(
        databaseName: "ToDoItems",
        collectionName: "Items",
        ConnectionStringSetting = "CosmosDBConnection",
        LeaseCollectionName = "leases",
        CreateLeaseCollectionIfNotExists = true)]IReadOnlyList<Document> documents, 
        ILogger log)
    {
        if (documents != null && documents.Count > 0)
        {
            log.LogInformation($"Documents modified: {documents.Count}");
            log.LogInformation($"First document Id: {documents[0].Id}");
        }
    }
}

It looks ok, but it avoids the problem by not being interested in the content of the documents. The trigger has a limitation, it works only with IReadOnlyList. This means that accessing values may not be as easy as one could expect. There is GetPropertyValue method, which helps with retrieving a single property value.

public static class CosmosTrigger
{
    [FunctionName("CosmosTrigger")]
    public static void Run([CosmosDBTrigger(
        ...)]IReadOnlyList<Document> documents, 
        ILogger log)
    {
        foreach(Document document in documents)
        {
            log.LogInformation($"ToDo: {document.GetPropertyValue<string>("Description")}");
        }
    }
}

This is not perfect. What if there is a lot of properties? If what is truly needed is the entire POCO, then a conversion from Document to POCO must be added. One way is to cast through dynamic.

public static class CosmosTrigger
{
    [FunctionName("CosmosTrigger")]
    public static void Run([CosmosDBTrigger(
        ...)]IReadOnlyList<Document> documents, 
        ILogger log)
    {
        foreach(Document document in documents)
        {
            ToDoItem item = (dynamic)document;
            log.LogInformation($"ToDo: {item.Description}");
            ...
        }
    }
}

Another way is to use JSON deserialization.

public static class CosmosTrigger
{
    [FunctionName("CosmosTrigger")]
    public static void Run([CosmosDBTrigger(
        ...)]IReadOnlyList<Document> documents, 
        ILogger log)
    {
        foreach(Document document in documents)
        {
            ToDoItem item = JsonConvert.DeserializeObject(document.ToString());
            log.LogInformation($"ToDo: {item.Description}");
            ...
        }
    }
}

All this is still not perfect, especially if there are many functions like this in a project. What would be perfect is being able to take a collection of POCOs as an argument.

public static class CosmosTrigger
{
    [FunctionName("CosmosTrigger")]
    public static void Run([CosmosDBTrigger(
        ...)]IReadOnlyList<ToDoItem> items, 
        ILogger log)
    {
        foreach(ToDoItem item in items)
        {
            log.LogInformation($"ToDo: {item.Description}");
            ...
        }
    }
}

Can this be achieved?

Extending the Azure Cosmos DB Trigger

As you may already know, the heart of Azure Functions extensibility is ExtensionConfigContext. It allows registering bindings by adding binding rules, but it also allows adding converters. Typically converters are added as part of the binding rule in the original extension, but this is not the only way. The truth is that the converter manager is centralized and shared across extensions. That means it's possible to add a converter for a type which is supported by different extension. The problem with the Azure Cosmos DB Trigger can be solved by a converter from IReadOnlyList to IReadOnlyList. But first, some standard boilerplate code is needed.

[assembly: WebJobsStartup(typeof(CosmosDBExtensionsWebJobsStartup))]

public class CosmosDBExtensionsWebJobsStartup : IWebJobsStartup
{
    public void Configure(IWebJobsBuilder builder)
    {
        builder.AddExtension<CosmosDBExtensionExtensionsConfigProvider>();
    }
}
[Extension("CosmosDBExtensions")]
internal class CosmosDBExtensionExtensionsConfigProvider : IExtensionConfigProvider
{
    public void Initialize(ExtensionConfigContext context)
    {
        if (context == null)
        {
            throw new ArgumentNullException("context");
        }


    }
}

Now it's time to add the converter. There are two methods for adding converters: AddConverter<TSource, TDestination> and AddOpenConverter<TSource, TDestination>. The AddConverter<TSource, TDestination> can be used to add a converter from one concrete type to another, while AddOpenConverter<TSource, TDestination> can be used to add a converter with support for generics. But how to define TDestination when Initialize method is not generic? For this purpose, the SDK provides a sentinel type OpenType which serves as a placeholder for a generic type.

[Extension("CosmosDBExtensions")]
internal class CosmosDBExtensionExtensionsConfigProvider : IExtensionConfigProvider
{
    public void Initialize(ExtensionConfigContext context)
    {
        ...

        context.AddOpenConverter<IReadOnlyList<Document>, IReadOnlyList<OpenType>>(typeof(GenericDocumentConverter<>));
    }
}

The converter itself is just an implementation of IConverter<TInput, TOutput>.

internal class GenericDocumentConverter<T> : IConverter<IReadOnlyList<Document>, IReadOnlyList<T>>
{
    public IReadOnlyList<T> Convert(IReadOnlyList<Document> input)
    {
        List<T> output = new List<T>(input.Count);

        foreach(Document item in input)
        {
            output.Add(Convert(item));
        }

        return output.AsReadOnly();
    }

    private static T Convert(Document document)
    {
        return JsonConvert.DeserializeObject<T>(document.ToString());
    }
}

That's it. This extension will allow the Azure Cosmos DB Trigger to be used with POCO collections.

This pattern can be reused with any other extension.

I was prompted to write this post by this question. In general, the question is about using ASP.NET Core built-in authorization to restrict access to a middleware. In ASP.NET Core the authorization mechanism is well exposed for MVC (through AuthorizeAttribute), but for middleware it's a manual job (at least for now). The reason for that might be the fact that there is no too many terminal middleware.

This was not the first time I've received this question, so I've quickly responded with typical code to achieve the task. But, after some thinking, I've decided I will put a detailed answer here.

Policy-based authorization

At its core, the authorization in ASP.NET Core is based on policies. Other available ways of specifying requirements (roles, claims) are in the end evaluated to policies. This means that it is enough to be able to validate a policy for the current user. This can be easily done with help of IAuthorizationService. All one needs is a policy name and HttpContext. Following authorization middleware gets the job done.

public class AuthorizationMiddleware
{
    private readonly RequestDelegate _next;
    private readonly string _policyName;

    public AuthorizationMiddleware(RequestDelegate next, string policyName)
    {
        _next = next;
        _policyName = policyName;
    }

    public async Task Invoke(HttpContext httpContext, IAuthorizationService authorizationService)
    {
        AuthorizationResult authorizationResult =
            await authorizationService.AuthorizeAsync(httpContext.User, null, _policyName);

        if (!authorizationResult.Succeeded)
        {
            await httpContext.ChallengeAsync();
            return;
        }

        await _next(httpContext);
    }
}

Of course, middleware registration can be encapsulated in an extensions method for easier use.

public static class AuthorizationApplicationBuilderExtensions
{
    public static IApplicationBuilder UseAuthorization(this IApplicationBuilder app, string policyName)
    {
        // Null checks removed for brevity
        ...

        return app.UseMiddleware(policyName);
    }
}

The only thing left is to put this middleware in front of middleware which should have restricted access (it can be placed multiple times if multiple policies need to be validated).

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        ...

        services.AddAuthorization(options =>
        {
            options.AddPolicy("PolicyName", ...);
        });
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        ...

        app.UseAuthentication();

        app.Map("/policy-based-authorization", branchedApp =>
        {
            branchedApp.UseAuthorization("PolicyName");

            ...
        });

        ...
    }
}

Simple and effective. Goal achieved, right?

Simple authorization, roles and schemes

Despite being my go-to solution, the above approach is far from perfect. It doesn't expose full capabilities and is not user-friendly. Something more similar to AuthorizeAttribute would be a lot better. This means making full use of policies, roles, and schemes. At first, this might sound like some serious work, but the truth is that all the hard work is done for us, we just need to go beyond Microsoft.AspNetCore.Authorization and use some services from Microsoft.AspNetCore.Authorization.Policy package. But before that can be done, a user-friendly way of defining restrictions is needed. This is no challenge, as ASP.NET Core has an interface for that.

internal class AuthorizationOptions : IAuthorizeData
{
    public string Policy { get; set; }

    public string Roles { get; set; }

    public string AuthenticationSchemes { get; set; }
}

This options class is very similar to AuthorizeAttribute. This isn't a surprise as AuthorizeAttribute also implements IAuthorizeData.

Implementing IAuthorizeData allows class to be transformed into AuthorizationPolicy with help of IAuthorizationPolicyProvider.

public class AuthorizationMiddleware
{
    private readonly RequestDelegate _next;
    private readonly IAuthorizeData[] _authorizeData;
    private readonly IAuthorizationPolicyProvider _policyProvider;
    private AuthorizationPolicy _authorizationPolicy;

    public AuthorizationMiddleware(RequestDelegate next,
        IAuthorizationPolicyProvider policyProvider,
        IOptions authorizationOptions)
    {
        // Null checks removed for brevity
        _next = next;
        _authorizeData = new[] { authorizationOptions.Value };
        _policyProvider = policyProvider;
    }

    public async Task Invoke(HttpContext httpContext, IPolicyEvaluator policyEvaluator)
    {
        if (_authorizationPolicy is null)
        {
            _authorizationPolicy =
                await AuthorizationPolicy.CombineAsync(_policyProvider, _authorizeData);
        }

        ...

        await _next(httpContext);
    }

    ...
}

The policy needs to be evaluated. This requires two calls to IPolicyEvaluator, one for authentication and one for authorization.

public class AuthorizationMiddleware
{
    ...

    public async Task Invoke(HttpContext httpContext, IPolicyEvaluator policyEvaluator)
    {
        ...

        AuthenticateResult authenticateResult =
            await policyEvaluator.AuthenticateAsync(_authorizationPolicy, httpContext);
        PolicyAuthorizationResult authorizeResult =
            await policyEvaluator.AuthorizeAsync(_authorizationPolicy, authenticateResult, httpContext, null);

        if (authorizeResult.Challenged)
        {
            await ChallengeAsync(httpContext);
            return;
        }
        else if (authorizeResult.Forbidden)
        {
            await ForbidAsync(httpContext);
            return;
        }

        await _next(httpContext);
    }

    ...
}

The last thing is handling Challenged and Forbidden scenarios. There are ready to use HttpContext extension methods which do that, but it's important to remember to make use of schemes if they have been provided.

public class AuthorizationMiddleware
{
    ...

    private async Task ChallengeAsync(HttpContext httpContext)
    {
        if (_authorizationPolicy.AuthenticationSchemes.Count > 0)
        {
            foreach (string authenticationScheme in _authorizationPolicy.AuthenticationSchemes)
            {
                await httpContext.ChallengeAsync(authenticationScheme);
            }
        }
        else
        {
            await httpContext.ChallengeAsync();
        }
    }

    private async Task ForbidAsync(HttpContext httpContext)
    {
        if (_authorizationPolicy.AuthenticationSchemes.Count > 0)
        {
            foreach (string authenticationScheme in _authorizationPolicy.AuthenticationSchemes)
            {
                await httpContext.ForbidAsync(authenticationScheme);
            }
        }
        else
        {
            await httpContext.ForbidAsync();
        }
    }
}

Now the registration method can be modified. An important thing to note here is that not setting any of the AuthorizationOptions properties will result in using default policy (same as decorating action or controller with [Authorize]). This case might be worth an overload.

public static class AuthorizationApplicationBuilderExtensions
{
    public static IApplicationBuilder UseAuthorization(this IApplicationBuilder app)
    {
        return app.UseAuthorization(new AuthorizationOptions());
    }

    public static IApplicationBuilder UseAuthorization(this IApplicationBuilder app,
        AuthorizationOptions authorizationOptions)
    {
        if (app == null)
        {
            throw new ArgumentNullException(nameof(app));
        }

        if (authorizationOptions == null)
        {
            throw new ArgumentNullException(nameof(authorizationOptions));
        }

        return app.UseMiddleware(Options.Create(authorizationOptions));
    }
}

This makes all capabilities provided by AuthorizeAttribute available to middleware pipeline. If the application is not using MVC it's important to remember about adding policy services.

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        ...

        services.AddAuthorization(options =>
        {
            options.AddPolicy("PolicyName", ...);
        })
        .AddAuthorizationPolicyEvaluator();
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        ...

        app.UseAuthentication();

        app.Map("/simple-authorization", branchedApp =>
        {
            branchedApp.UseAuthorization();

            ...
        });

        app.Map("/role-based-authorization", branchedApp =>
        {
            branchedApp.UseAuthorization(new AuthorizationOptions { Roles = "Employee" });

            ...
        });

        app.Map("/policy-based-authorization", branchedApp =>
        {
            branchedApp.UseAuthorization(new AuthorizationOptions { Policy = "EmployeeOnly" });

            ...
        });

        ...
    }
}

All the code above is a copy-paste solution when one wants to restrict middleware from outside, but it can also be easily adapted to put inside a middleware (which in the end I decided to do in case of my Server-Sent Events middleware).

Small note about the future

The state of authorization in the middleware pipeline should be expected to change. ASP.NET Core 3.0 is supposed to make Endpoint Routing available outside of MVC and it comes with support for authorization. In ASP.NET Core 2.2 there is already an authorization middleware (quite similar to the one above) which restricts endpoints based on IAuthorizeData from metadata. This means that in 3.0 it may be possible to define a restricted endpoint pointing to a middleware.

Older Posts