DEV Community: Marc Duiker

Join the Diagrid Catalyst AWS Hackathon!

Marc Duiker — Mon, 29 Apr 2024 08:13:50 +0000

We are excited to invite you to the Diagrid Catalyst AWS Hackathon—a four-week, virtual event where you can unleash your creativity and showcase your coding skills by building or modernizing a cutting-edge application using the powerful Diagrid Catalyst platform. Get ready to collaborate, compete, and win cash prizes! Register now.

What is Diagrid Catalyst?

Diagrid Catalyst is a Developer API platform providing a brand-new approach to distributed application development. Using the Catalyst APIs, powered by the Dapr open source project, developers can overcome the complexity of rewriting common software patterns and achieve higher productivity by offloading infrastructure concerns from their code to Catalyst.

Say hello to making API calls from any platform, in any language to build modern, cloud-applications with ease. This hackathon is your chance to explore the potential of Diagrid Catalyst while bringing your solution ideas to life! For more on Catalyst, watch our most recent webinar for a platform overview and API deep dive.

Why Participate?

Join the Diagrid Catalyst Hackathon to:

Innovate with an Emerging Product: Explore the ways Diagrid Catalyst can expedite your development process by building an application to solve real-world challenges.
Collaborate with Peers: Connect with fellow developers, designers, and entrepreneurs. Collaborate, share ideas, and learn from each other's experiences.
Enhance Your Skills: Sharpen your application development and architecture skills using the coding languages of your choice and deploying your solution on Amazon Web Services.
Win Prizes: Compete for impressive cash prizes! We have rewards lined up for the most exceptional projects and for providing product feedback. ‍ All participation is evaluated based on the criteria in the Hackathon Rules, Terms & Conditions.

What to Build?

Build or update an open-source microservice-based software solution utilizing at least two Diagrid Catalyst APIs. The solution should be composed of multiple application services and either be newly written or significantly enhanced to utilize Diagrid Catalyst. The solution should be architected using AWS infrastructure and hosting services. The solution must align with one of the areas below:

Polyglot compute/ Cross-platform service discovery: Application services are deployed to different AWS hosting platforms, which interact via the Catalyst APIs.
Stateful business process orchestration: Application services are instrumented as part of a Dapr Workflow using the Dapr Workflow authoring SDK paired with the Catalyst Workflow API.
Serverless architecture: Application services are optimized to run on AWS PaaS/SaaS services, which abstracts infrastructure concerns and enables high-scalability.

Hackathon Timeline

Registration Open: April 19th 2024
Project Submissions Open: May 10th 2024
Feedback Submissions Open: May 24th 2024
Registration Closes: May 17th 2024
Project Submissions Deadline: June 7th 2024
Feedback Submissions Deadline: June 14th 2024
Location: Virtual Only

Catalyst Reference Apps

Looking for inspiration? See below for a couple of sample projects we’ve built using Diagrid Catalyst. More samples, including an AWS-specific reference, will be available to participants on the Hackathon site.

Tetris Game

The classic “blocks falling from the sky” game! The solution consists of two services:

A Python Flask user service which serves the JavaScript/HTML front-end for the user sign up and leaderboard and handles user state management and leaderboard updates.
A game service written in Go, which serves the JavaScript/HTML frontend for the game itself and manages the game session lifecycle.

These two services need to manage state and communicate to ensure games are started with the appropriate users, and user profiles are updated with the game results. The service interaction and data storage is all implemented using the APIs provided by Catalyst. Read the blog post.

Pizza Store Management System

A distributed pizza store with Catalyst APIs. The solution comprises two .NET microservices, two serverless JavaScript functions and a Vue front-end. The applications depend on Diagrid Catalyst as the serverless API layer to connect to the underlying data and messaging infrastructure. Read the blog.

How to Participate?

Participation is straightforward:

Register: Submit a registration request form for the hackathon. Eligible participants will receive a direct invite to the Hackathon site, hosted on Devpost. Accept your invitation to Devpost and click the blue “Register” button on the Hackathon landing page to register.
Create a project: Create a project to frame out your hackathon solution ideas for others to see and potentially join in to help execute. You have a few options when it comes to projects:
1. Create a closed project to participate as an individual.
2. Create an open project to enable other Hackathon participants to join you in your mission. You can even choose to invite people to participate in your project.
3. Join an existing, open project if one is available and intrigues you.
Learn: Join our ongoing Catalyst webinar series or watch on-demand.
Build: Develop your application using Diagrid Catalyst. Let your creativity shine, and don't forget to integrate innovative features.
Submit: Submit your project with the required deliverables by the deadline, June 7

For more information on resource access, project requirements and judging criteria, view the Hackathon Rules, Terms & Conditions.

Prizes

We have exciting cash prizes up for grabs! Prizes range from a Grand Prize of $2000 to Runner-up Prizes of $1000 each and Bonus Prizes from $250-$500! Get swag for participating & provide valuable product feedback for the chance to win another $100.

If you participate in the hackathon, you are also eligible for a $100 referral bonus for spreading the word! Share the Hackathon details with your friends and encourage them to sign up. The participant with the most referrals wins!

Get Ready to Hack

Don’t miss this unique opportunity to explore Diagrid Catalyst, build innovative apps, and compete for cash prizes. Whether you're a seasoned developer or a curious beginner, the Diagrid Catalyst Hackathon is your time to shine.

Building a distributed pizza store in .NET with serverless Dapr APIs

Marc Duiker — Thu, 01 Feb 2024 10:57:11 +0000

Intro

When developers build distributed systems, they need to think about cross-cutting concerns such as security, observability, and resiliency. Developers also write a lot of glue code to orchestrate services, create long-running and durable workflows, and connect to external resources, such as message brokers and state stores.

Dapr, the Distributed Application Runtime, is ideal for building distributed systems since it has built-in support for cross-cutting concerns, and it offers a suite of APIs for communication, state and workflow, that make developers more efficient. According to the State of Dapr Report, 95% of Dapr developers claim that Dapr saves time, and 55% of the developers surveyed claimed it saved them more than 30% of development time.

The usage of Dapr is also increasing thanks to a growing number of platforms that support the Dapr APIs. Dapr is no longer limited to running as a sidecar in Kubernetes, as is described in Dapr Deployment Models. In this article, Diagrid Catalyst, a suite of serverless Dapr APIs, is used to orchestrate services with Dapr workflow, and interact with message brokers and key-value stores.

Throughout this article, you’ll be using the following to configure a distributed system:

Two Dapr services (.NET)
Two serverless functions (JavaScript)
A front-end (Vue)
A key value state store
A pub/sub message broker
Diagrid Catalyst as the serverless API layer to connect everything

TLDR: Check the code on GitHub and join the Catalyst early access program.

Diagrid Pizza Store

The demo that is used in this article revolves around an online pizza store, where the user selects pizzas, orders them, and follows the progress of the order in realtime. It’s a simplified example where the durable workflow focuses on the inventory of ingredients, and communicating with the kitchen. The source code is on GitHub.

Architecture

The solution includes:

Two Dapr web services written in .NET, PizzaOrderService and KitchenService. In this demo, they’re running locally, but these can be hosted in any cloud that supports ASP.NET services.
The website (based on Vue) and two serverless functions written in JavaScript, getAblyToken and placeOrder. These are hosted on Vercel.
Ably as the realtime communication component between the PizzaOrderService and the website.
A key/value store to manage inventory (managed by Diagrid).
A pub/sub message broker to communicate between the PizzaOrderService and the KitchenService (managed by Diagrid).
Diagrid Catalyst that offers serverless APIs for communication, state, and workflow powered by Dapr.

Workflow

The PizzaOrderService contains a Dapr workflow that orchestrates the activities for checking the inventory and communicating with the KitchenService.

The workflow also contains activities for sending realtime messages to the website, these have been omitted from the workflow diagram to keep it concise.

Running the Pizza Store locally

Prerequisites

The following services, tools, and frameworks are required for this demo:

Diagrid Catalyst account (sign up for early access) and the Diagrid CLI
Vercel account (hobby) and the Vercel CLI
Ably account (free)
.NET 8 SDK
Node 18

All the code for the website, serverless functions, and back-end services is available in the catalyst-pizza-demo GitHub repository. This repository contains a devcontainer configuration that has the following preinstalled: .NET 8, Node LTS, Vercel CLI, Diagrid CLI.

You can use this devcontainer locally in VSCode (requires Docker Desktop) or directly in GitHub Codespaces. The npm install and dotnet build commands described in this article can be skipped if the devcontainer is used.

GitHub

Fork the catalyst-pizza-demo and clone it locally, or use GitHub Codespaces (recommended).

Ably

Ably is used as the serverless realtime messaging component. There is a default Ably app when you sign up for an account that can be used for this demo. Alternatively, you can create a new Ably app.

Log into the Ably portal.
Using the Ably portal: copy the Root API key from the Ably app. This will be copied later as an environment variable for both Vercel and Diagrid.

Vercel

The Vue-based front-end and two JavaScript functions are hosted on Vercel. The Vercel CLI is used to configure and run these resources locally.

Open a terminal in the root of the repository and login with the Vercel CLI:
```
vercel login
```
Go to the front-end folder and run:
```
npm install
```
Go back to the root of the repository and set up the Vercel project by running:
```
vercel
```
Follow the CLI prompts, and select the following options:
- Setup and deploy: Y
- Scope: <account name>
- Link to existing project: N
- What's your project's name? catalyst-pizza-project
- In which directory is your code located? ./front-end
- Want to modify these settings? [y/N] n
- Wait for the deployment to complete.
An environment variable is used in the getAblyToken function to generate a token for the website to communicate with the Ably realtime service. Add the Ably API token variable by running vercel env add:
- Variable name: ABLY_API_KEY
- Variable value: Use the Ably API key obtained from the Ably portal earlier
- Select Development as the environment.
Another environment variable is used in the placeOrder function to send a request to the PizzaOrderService that will start the workflow. Add the WORKFLOW_URL variable by running vercel env add:
- Variable name: WORKFLOW_URL
- Variable value: http://localhost:5064/workflow/orderReceived
- Select Development as the environment.
Run vercel pull to pull the configuration from Vercel to your local environment.
Run vercel build to build the website and the serverless functions to ensure there are no errors.

Diagrid Catalyst

Diagrid Catalyst provides serverless Dapr APIs that enables developers to quickly build distributed applications with workflow, pub/sub messaging, service invocation, and state management capabilities. Diagrid also provides managed infrastructure for storing data in a key/value store, pub/sub messaging, and workflow, which are all used in this solution.

The Diagrid CLI is used to configure the resources and run the .NET services locally.

Open another terminal in the root of the repository and use the Diagrid CLI to log in to Diagrid:
```
diagrid login
```
Create a new Catalyst project named catalyst-pizza-project and use the Diagrid managed pub/sub broker & KV store, and enable the managed workflow API:
```
diagrid project create catalyst-pizza-project --deploy-managed-pubsub --deploy-managed-kv --enable-managed-workflow --wait
```
To set this project as the default in the CLI run:
```
diagrid project use catalyst-pizza-project
```
Create a new App ID for the PizzaOrderService:
```
diagrid appid create pizzaorderservice
```
Create a new App ID for the KitchenService:
```
diagrid appid create kitchenservice
```
Before continuing, check the App ID status to make sure they are ready:
```
diagrid appid list
```

Create a pub/sub subscription for the KitchenService to receive messages from the PizzaOrderService:

diagrid subscription create pizzaorderssub --connection pubsub --topic pizza-orders --route /prepare --scopes kitchenservice

Create a pub/sub subscription for the PizzaOrderService to receive messages from the KitchenService:

diagrid subscription create preparedorderssub --connection pubsub --topic prepared-orders --route /workflow/orderPrepared --scopes pizzaorderservice

Verify that creation of the subscriptions is completed:
```
diagrid subscription list
```

Run diagrid dev scaffold to create a new local dev environment file. This creates a yaml file, named dev-.yaml with the following content:

project: catalyst-pizza-project
apps:
- appId: kitchenservice
appPort: 0
env:
    DAPR_API_TOKEN: diagrid://<dapr_api_token>
    DAPR_APP_ID: kitchenservice
    DAPR_GRPC_ENDPOINT: https://<grpc_endpoint>
    DAPR_HTTP_ENDPOINT: https://<http_endpoint>
workDir: kitchenservice
command: []
- appId: pizzaorderservice
appPort: 0
env:
    DAPR_API_TOKEN: diagrid://<dapr_api_token>
    DAPR_APP_ID: pizzaorderservice
    DAPR_GRPC_ENDPOINT: https://<grpc_endpoint>
    DAPR_HTTP_ENDPOINT: https://<http_endpoint>
workDir: pizzaorderservice
command: []
appLogDestination: ""

This file is gitignored since it contains secrets from Diagrid Catalyst. The appPort, command, and workDir attributes still need to be updated as follows:

Update the appPort for the kitchenservice to 5066.
Update the appPort for the pizzaorderservice to 5064.
Update the command arguments to ["dotnet", "run"] for both apps.
Update the workDir argument to point to back-end/KitchenService and back-end/PizzaOrderService respectively.
Update the appLogDestination to console.
Add an ABLY_API_KEY environment variable for the pizzaorderservice appId and set the value to the Ably API key obtained from the Ably portal.
Save the changes to the file.

Update the key/value store to allow shared state

The two .NET services share the same state in the key/value store to manage inventory and orders. Since this is not the default usage of state stores and services when using Dapr, an attribute needs to be set to enable this. The default behavior is that a key is prefixed with the app ID of the service that is using it. In this case, however, the keyPrefix is set to name to make sure both services use the same keys.

Run the following command to update the managed key/value store:
```
diagrid connection apply -f ./infra/kv.yml
```
This will upload the kv.yml file to Diagrid and update the configuration of the kvstore connection so keyPrefix is set to name.

Inspect the DaprClient configuration

The two .NET services use the Dapr .NET client SDK for workflow, state management and pub/sub messaging. The DaprClient is configured to use the endpoints provided by Diagrid Catalyst in the Program.cs file:

var apiToken = Environment.GetEnvironmentVariable("DAPR_API_TOKEN");
var grpcEndpoint = Environment.GetEnvironmentVariable("DAPR_GRPC_ENDPOINT");
var httpEndpoint = Environment.GetEnvironmentVariable("DAPR_HTTP_ENDPOINT");

builder.Services.AddDaprClient(options => {
    options.UseDaprApiToken(apiToken);
    options.UseGrpcEndpoint(grpcEndpoint);
    options.UseHttpEndpoint(httpEndpoint);
});

To use service invocation with the HTTP API, the HttpClient is configured with the DAPR_APP_ID and DAPR_API_TOKEN environment variables:

var appId = Environment.GetEnvironmentVariable("DAPR_APP_ID");
var apiToken = Environment.GetEnvironmentVariable("DAPR_API_TOKEN");

builder.Services.AddHttpClient(
    "daprEndpoint",
    client => {
        client.BaseAddress = new Uri(httpEndpoint);
        client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
        client.DefaultRequestHeaders.Add("dapr-app-id", appId);
        client.DefaultRequestHeaders.Add("dapr-api-token", apiToken);
    });

Running & testing the solution

Open a terminal in the root of the repository.

To restore and build the .NET projects run:

dotnet build ./back-end/PizzaOrderService
dotnet build ./back-end/KitchenService

Run diagrid dev start to start the PizzaOrderService and the KitchenService.
Using another terminal in the root of the repository, run vercel dev to start the website and the serverless functions locally.
Navigate to the URL provided by the Vercel CLI to view the website.
Select some pizzas, place an order, and watch the progress of the workflow in realtime.

Using the Catalyst API explorer

You can use the API explorer in the Catalyst web UI to interact with the APIs. If you want to retrieve the order item from the key/value store that has just been processed, follow these steps:

Open the developer tools console of the browser that is running the demo (a pizza order must be started or completed).
The order is logged to the console as a JSON object. Copy the OrderId property value.
Navigate to the Catalyst web UI. Ensure you're in the catalyst-pizza-project project.
Select App IDs in and click on the API explorer tab.
- Select the State API.
- Select the pizzaorderservice as the app ID.
- Select GET as the API operation.
- Select kvstore as the state connection.
- Enter Order- as the key, where is substituted with the value copied from the developer tools console.
Click Send. The response should show the state of the order item.

What’s next?

Congratulations! You’ve now used the Diagrid Catalyst serverless Dapr APIs for workflow, pub/sub messaging, service invocation, and state management. The ability to use these APIs from anywhere, without the overhead of managing Kubernetes clusters, brings great flexibility to developers on any platform to build distributed applications. The Dapr applications used in this demo can be hosted on any cloud. The demo uses the Diagrid managed infrastructure for key/value storage and pub/sub messaging, but these can be swapped out for other cloud-based resources, similarly to switching open-source Dapr components. You can extend this demo with an alternative pub/sub broker or state store by configuring other infrastructure connections.

Any questions or comments about this demo? Join the Dapr Discord and drop us a message in the #diagrid channel!

Dapr v1.11 Release Highlights

Marc Duiker — Mon, 19 Jun 2023 12:27:24 +0000

The Dapr maintainers released a new version of Dapr, the distributed application runtime, last week. This post highlights the major new features and changes for the APIs and components in release 1.11.

APIs

Dapr provides a common set of APIs for building microservices quickly and reliably. The new building block APIs, and major upgrades to existing APIs, are described in this section.

Configuration API stable

The Configuration building block allows developers to easily consume application configuration values as key/value pairs. Use this API to retrieve values that are likely to change over time but are coupled to the service. For instance, this API can be used to get App IDs, which are used when invoking other Dapr services. Or to get a component name of a state store when using the State Management API.

Applications can subscribe to changes of these configuration values, so the apps always use the latest value. The Configuration API was introduced in Dapr v1.5, and it’s great to see it now stable in v1.11.

Get a configuration value

GET http://localhost:<daprPort>/v1.0/configuration/<storeName>?key=<keyName>

Subscribe to configuration changes

GET http://localhost:<daprPort>/v1.0/configuration/<storeName>/subscribe

Service Invocation for non-Dapr endpoints 🆕

An exciting new preview feature is the ability to invoke non-Dapr endpoints. This feature enables developers to apply resiliency policies, access control via scoping, header authentication, and middleware to any endpoint. This gives you nearly all the benefits of service invocation when calling any HTTP API. Invoking non-Dapr endpoints can also be very useful when working on existing code bases where Dapr can be introduced incrementally.

Non-Dapr endpoints can be invoked in two ways:

Using an HTTPEndpoint resource type.

GET http://localhost:<daprPort>/v1.0/invoke/<HTTPEndpoint-name>/method/<my-method>

The HTTPEndpoint resource is specified in a yaml file:

apiVersion: dapr.io/v1alpha1
kind: HTTPEndpoint
metadata:
  name: <NAME>  
spec:
  version: v1alpha1
  baseUrl: <REPLACE-WITH-BASEURL> # Required. Use "http://" or "https://" prefix.
  headers: # Optional
  - name: <REPLACE-WITH-A-HEADER-NAME>
    value: <REPLACE-WITH-A-HEADER-VALUE>
  - name: <REPLACE-WITH-A-HEADER-NAME>
    secretKeyRef:
      name: <REPLACE-WITH-SECRET-NAME>
      key: <REPLACE-WITH-SECRET-KEY>
scopes: # Optional
  - <REPLACE-WITH-SCOPED-APPIDS>
auth: # Optional
  secretStore: <REPLACE-WITH-SECRETSTORE>

Using the Fully Qualified Domain Name (FQDN) of the endpoint.

GET http://localhost:<daprPort>/v1.0/invoke/<FQDN_URL>/method/<my-method>

Workflow updates

The Dapr Workflow management API has been updated to allow workflows to be paused, resumed, and purged. Purging workflows means the workflow state will be deleted. Once a workflow has been completed, it’s a good practice to purge the workflow state to keep the storage requirements to a minimum. In addition, workflows can now wait for external events. This is particularly useful for business processes that involve human interaction, such as approval workflows, or waiting for callbacks from other long-running processes.

These are the current Workflow management HTTP API methods:

POST http://localhost:<daprPort>/v1.0-alpha1/workflows/dapr/<instanceID>/start
POST http://localhost:<daprPort>/v1.0-alpha1/workflows/dapr/<instanceID>/terminate
POST http://localhost:<daprPort>/v1.0-alpha1/workflows/dapr/<instanceID>/pause
POST http://localhost:<daprPort>/v1.0-alpha1/workflows/dapr/<instanceID>/resume
POST http://localhost:<daprPort>/v1.0-alpha1/workflows/dapr/<instanceID>/purge
POST http://localhost:<daprPort>/v1.0-alpha1/workflows/dapr/<instanceID>/raiseEvent/<eventName>

Note that the Workflow management API, which is still in preview, has breaking changes compared to v1.10. The changes are outlined in this GitHub issue. Another breaking change is the ability to support multiple workflow apps in a single cluster, as mentioned in this GitHub issue.

The Dapr Python SDK has been upgraded to allow authoring of workflows, so now workflow applications can be written in either C# or Python.

Cryptography API 🆕

The Cryptography API is a new preview building block that enables developers to encrypt/decrypt data in a safe and consistent way. Cryptography can be used within key vaults or the Dapr sidecar without exposing cryptographic keys to the application. With this new API, a set of new Cryptography components is made available that is listed in the New Components section.

These examples show how data can be encrypted and decrypted with the Cryptography API using the Dapr JavaScript SDK:

Encryption

// When passing data (a buffer or string), `encrypt` returns a Buffer with the encrypted message
const ciphertext = await client.crypto.encrypt(plaintext, {
    // Name of the Dapr component (required)
    componentName: "mycryptocomponent",
    // Name of the key stored in the component (required)
    keyName: "mykey",
    // Algorithm used for wrapping the key, which must be supported by the key named above.
    // Options include: "RSA", "AES"
    keyWrapAlgorithm: "RSA",
});

Decryption

// When passing data as a buffer, `decrypt` returns a Buffer with the decrypted message
const plaintext = await client.crypto.decrypt(ciphertext, {
    // Only required option is the component name
    componentName: "mycryptocomponent",
});

For more info on how to use the Cryptography API, see the Dapr docs.

Components

Dapr decouples the functionality of the common set of APIs with their underlying implementations via components. Components of the same type are interchangeable since they implement the same interface. Release 1.11 contains both new components as improvements to existing components.

New components

Bindings

WASM: allows invoking applications compiled to WebAssembly and run in modern browsers.
Kitex: allows invoking Generic Calls in Kitex, a high-performance and strong-extensibility Golang RPC framework.

State Stores

etcd: enables state store functionality using etcd, a distributed, reliable key-value store.

Cryptography

Azure Key Vault: enables cryptography functionality using Azure Key Vault.
Local storage: enables cryptography functionality using local files. Supported file formats are PEM, JSON Web Key, and raw key data for symmetric keys.
JWKS: enables cryptography functionality using JSON Web Key Sets (JWKS).
Kubernetes Secrets: enables cryptography functionality using Kubernetes secrets.

Component improvements

With 1.11 many components have graduated to the Stable certification level, which means these can be used in production confidently. All components have a certification level as mentioned in the Certification Lifecycle. The Stable level means:

The component must have component certification tests validating functionality and resiliency.
The component is maintained by Dapr maintainers and supported by the community.
The component is well documented and tested.
The component has been available as Alpha or Beta for at least 1 minor version release of Dapr runtime prior.
A maintainer will address component security, core functionality and test issues according to the Dapr support policy and issue a patch release that includes the patched stable component.

The following components have progressed to Stable:

Bindings

AWS S3: output binding to store data in AWS S3 buckets.

Middleware

Rate limit: restricts the maximum allowed HTTP requests per second.
OpenID Connect: verifies a bearer token using OpenID Connect.

Pub/Sub

GCP Pub/Sub: enables pub/sub messaging using Google Cloud Platform Pub/Sub.

State stores

GCP Firestore: enables state store functionality using Google Cloud Platform Firestore.
SQLite: enables state store functionality using SQLite 3.

Configuration stores

PostgreSQL: enables configuration store functionality using PostgreSQL.
Redis: enables configuration store functionality using Redis.

If you're using any of these components and have a demo to show, drop a link in the #show-and-tell channel on the Dapr Discord.

*Azure components authentication improvements*

Azure AD authentication has been added to the Azure Storage Queues binding and the SQL Server state store.

All Azure components that support Azure AD now support authentication using:

Azure AD Workload Identity on Kubernetes
Azure CLI credentials.

What is next?

This post is not a complete list of features and changes released in version 1.11. Read the official Dapr release notes for more information. The release notes also contain information on how to upgrade to this latest version.

Excited about these features and want to learn more? I'll cover the new features in more detail in future posts. Until then, join the Dapr Discord to connect with thousands of Dapr users.

Creating a Dapr pluggable component for Supabase

Marc Duiker — Tue, 25 Apr 2023 14:56:41 +0000

In this post, you’ll learn how to use the Dapr pluggable component .NET SDK and the Supabase C# library to build a pluggable state store component that uses Supabase tables.

If you prefer watching a video instead of reading this blog post, head over to YouTube and watch this:

Dapr, the open-source, portable, event-driven runtime for building distributed applications, comes with over 100 built-in components which can be used to integrate resources across many clouds or on-premise systems. If those components are not enough, or you want to create something custom for your specific needs, you can create a pluggable component. The Dapr building block APIs that are pluggable are:

State management
Publish and subscribe
Input and output bindings

Since Dapr release 1.10 there are pluggable component SDKs available that make it easier to create them.

Supabase is a popular, open-source, Firebase alternative that offers Postgres databases, authentication, Edge functions, real-time messaging and file storage. The Supabase community has released a C#/.NET library that developers can use to integrate their .NET apps with the Supabase platform. For managing Postgres databases, the library uses the postgrest-csharp library that allows developers to use strongly typed models and LINQ queries.

This post describes the steps required to make a proof of concept Dapr pluggable component using .NET 7 that combines both the Dapr pluggable component .NET SDK and the Supabase C# library. The result is an ASP.NET application, that is run locally, and tested by making HTTP requests to interact with the state stored in a Supabase table.

1. Prerequisites

.NET 7 SDK
Dapr CLI
A Supabase account, you can sign up for free.
Supported OS: macOS, Linux, WSL on Windows.

2. Creating the DaprPluggableSupabase .NET project

If you’re more interested in using the pluggable component instead of creating it from scratch, continue with section 3. Supabase Setup.

Clone this repo, open a terminal and navigate to the src folder.

The cloned repository already contains an ASP.NET app in the DaprPluggableSupabase folder that is the pluggable component. You can use this as a reference.
Create a new .NET web project, and make sure to use a different name than DaprPluggableSupabase (e.g. MyDaprPluggableSupabase):

dotnet new web --name MyDaprPluggableSupabase
Change to the MyDaprPluggableSupabase folder and add the Dapr.PluggableComponents.AspNetCore and supabase-csharp NuGet packages:

cd MyDaprPluggableSupabase

dotnet add package Dapr.PluggableComponents.AspNetCore

dotnet add package supabase-csharp
Create a new class file in the MyDaprPluggableSupabase folder named KeyValue.cs.
Add the following content to this new class:

using Postgrest.Attributes;
using Postgrest.Models;

namespace DaprPluggableSupabase
{
    [Table("dapr_state_store")]
    public class KeyValue : BaseModel
    {
        [PrimaryKey("id")]
        public int Id { get; set; }

        [Column("created_at")]
        public DateTime CreatedAt { get; set; }

        [Column("key")]
        public string? Key { get; set; }

        [Column("value")]
        public string? Value { get; set; }
    }
}

The KeyValue class defines the data type that will be stored in the Supabase table. It inherits from BaseModel, which is part of the Supabase postgrest-csharp library. This library uses attributes that can be used to decorate the class and properties, which makes it easier for developers to use strongly typed models when interacting with the database table. Dapr state stores are key/value stores and Postgres databases are object-relational data stores. Since this is not a perfect match, the Dapr key/value-based state management API is mapped to this KeyValue model to fit the Postgres schema.

Create a new class file in the MyDaprPluggableSupabase folder named SupabaseStateStore.cs.
Add the following content to this new class:

using System.Text;
using Dapr.PluggableComponents.Components;
using Dapr.PluggableComponents.Components.StateStore;

namespace DaprPluggableSupabase
{
    internal sealed class SupabaseStateStore : IStateStore
    {
#nullable disable
        private Supabase.Client _supabaseClient;
#nullable enable

        private const string PROJECT_APIKEY_KEYWORD = "projectApiKey";
        private const string PROJECT_URL_KEYWORD = "projectUrl";

        public async Task DeleteAsync(StateStoreDeleteRequest request, CancellationToken cancellationToken = default)
        {
            await _supabaseClient.From<KeyValue>()
                .Where(x => x.Key == request.Key)
                .Delete(cancellationToken: cancellationToken);
        }

        public async Task<StateStoreGetResponse?> GetAsync(StateStoreGetRequest request, CancellationToken cancellationToken = default)
        {
            KeyValue? kv = await GetKV(request.Key, cancellationToken);

            if (kv != null && kv.Value != null)
            {
                var valueAsBytes = Encoding.UTF8.GetBytes(kv.Value);
                var response = new StateStoreGetResponse() { Data = valueAsBytes };
                return response;
            }

            return new StateStoreGetResponse();
        }

        public async Task InitAsync(MetadataRequest request, CancellationToken cancellationToken = default)
        {
            if (!request.Properties.TryGetValue(PROJECT_URL_KEYWORD, out string? projectUrl))
            {
                throw new InvalidOperationException($"Missing required property \"{PROJECT_URL_KEYWORD}\" in component file.");
            }

            if (!request.Properties.TryGetValue(PROJECT_APIKEY_KEYWORD, out string? projectApiKey))
            {
                throw new InvalidOperationException($"Missing required property \"{PROJECT_APIKEY_KEYWORD}\" in component file.");
            }

            _supabaseClient = new Supabase.Client(projectUrl, projectApiKey);
            await _supabaseClient.InitializeAsync();
        }

        public async Task SetAsync(StateStoreSetRequest request, CancellationToken cancellationToken = default)
        {
            var newKV = new KeyValue
            {
                Key = request.Key,
                CreatedAt = DateTime.UtcNow,
                Value = Encoding.UTF8.GetString(request.Value.Span)
            };

            KeyValue? existingKV = await GetKV(request.Key, cancellationToken);

            if (existingKV != null)
            {
                newKV.Id = existingKV.Id;
                await _supabaseClient.From<KeyValue>().Update(newKV, cancellationToken: cancellationToken);
                return;
            }
            else
            {
                await _supabaseClient.From<KeyValue>().Insert(newKV, cancellationToken: cancellationToken);
            }
        }

        private async Task<KeyValue?> GetKV(string key, CancellationToken cancellationToken)
        {
            return await _supabaseClient.From<KeyValue>()
#nullable disable
                            .Select(x => new object[] { x.Id, x.Key, x.Value })
#nullable enable
                            .Where(x => x.Key == key)
                            .Single(cancellationToken);
        }
    }
}

Notice that the class inherits from IStateStore, this is the interface that all Dapr state store components implement. The interface contains three methods that require implementing:

DeleteAsync, this will delete a value from the store.
GetAsync, this will retrieve a value from the store.
SetAsync, this will insert/update a value to the store.

All methods use the Supabase C# client to manage the data via the KeyValue model.

The IStateStore interface inherits the IPluggableComponent interface that contains only one method, InitAsync, and this method used to initialize the state store. In this case, it is used to create an instance of the Supabase.Client.

Update the existing Program.cs file with the following content:

using Dapr.PluggableComponents;
using DaprPluggableSupabase;

var builder = WebApplication.CreateBuilder(args);
var app = DaprPluggableComponentsApplication.Create();

app.RegisterService(
    "supabase",
    serviceBuilder =>
    {
        serviceBuilder.RegisterStateStore<SupabaseStateStore>();
    });

app.Run();

This class defines the application as a DaprPluggableComponentApplication and registers the SupabaseStateStore as a new state store that will communicate with Dapr applications via a Unix domain socket named supabase.

Build the application to make sure there are no compilation errors:

dotnet build

3. Supabase Setup

The pluggable component will interact with a Supabase Postgres table. This section describes how to create the table using the Supabase dashboard and where to find the project URL and API key required in the next section.

Create a new database table with the following specifications:

Name: dapr_state_store
Primary Key: id, (int8, not null)
Columns:
- created_at (timestamptz, not null)
- key (text, not null)
- value (text, null)
RLS (Row Level Security) is disabled

Note that for production use, Row Level Security (RLS) should be enabled, and access policies should be added to the table.

Table definition:

create table
        public.dapr_state_store (
            id bigint generated by default as identity not null,
            created_at timestamp with time zone not null default now(),
            key text not null,
            value text null,
            constraint dapr_state_store_pkey primary key (id),
            constraint dapr_state_store_id_key unique (id)
        ) tablespace pg_default;

You'll need the Supabase project URL and public API key to configure the Dapr component file in the next section. This information is found in the Supabase dashboard in the project Settings > API tab.

4. Update the Dapr pluggable Supabase component file

Dapr uses a modular design where functionality is delivered as a component. A component file contains the specification of a component, including the name, the component type, and related metadata that is specific to connecting with the underlying resource. The component file for the Supabase state store looks like this:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: pluggable-supabase
spec:
  type: state.supabase
  version: v1
  metadata:
  - name: projectUrl
    value: ""
  - name: projectApiKey
    value: ""

The value of the spec.type field, state.supabase, consists of two parts: the component type (state), and the socket name (supabase). The socket name needs to match with the socket name argument provided in the RegisterService method in the Program.cs class of section 2. A template of this component file is available in the repository, follow these steps to update the file, so it can be used locally.

Navigate to the resources folder in this repository.
Rename the resources\pluggableSupabase.yml.template file to resources\pluggableSupabase.yml.

The pluggableSupabase.yml file is added to .gitignore, so it won't be accidentally committed to source control for this demo app. For production use, the yaml files should be checked into source control and secret store references should be used, instead of plain text values.
Open the pluggableSupabase.yml file and update the values for projectUrl and projectApiKey obtained in the previous section.
Save the file and copy it to the user's Dapr components folder: ~/.dapr/components.

When the Dapr CLI is run, all the component files in this folder will be loaded, so the pluggable Supabase component should be available.

5. Run the DaprPluggableSupabase application

Regular Dapr components are part of the Dapr runtime and don't require additional processes to run. Pluggable components, however, are not part of the Dapr runtime and need to be run separately, which is done in this section.

The DaprPluggableSupabase project in this repo implements the Dapr state store interface and uses the Supabase C# library to access a Supabase table.

Open a terminal and navigate to the
1. src/DaprPluggableSupabase folder to use the included pluggable component project or
2. src/MyDaprPluggableSupabase folder to use the pluggable component project you’ve just created yourself.
Build the project:

dotnet build
Run the project:

dotnet run

6. Run the Dapr process and test the Supabase state store

Open a new terminal and use the Dapr CLI to run the Dapr process

dapr run --app-id myapp --dapr-http-port 3500

Expected output:

The output should contain an INFO message that the pluggable-supabase component is loaded:

INFO[0000] component loaded. name: pluggable-supabase, type: state.supabase/v1

The log should end with:

ℹ️ Dapr sidecar is up and running. ✅ You're up and running! Dapr logs will appear here.
Set a new state by making a POST request to the state management endpoint:

curl --request POST --url http://localhost:3500/v1.0/state/pluggable-supabase --header 'content-type: application/json' --data '[{"key": "key1","value": "This is stored in Supabase!"}]'

Expected output:

HTTP 204 No Content
Retrieve the new state using a GET request:

curl --request GET --url http://localhost:3500/v1.0/state/pluggable-supabase/key1

Expected output:

HTTP 200 OK

"This is stored in Supabase!"

Or have a look at the Supabase dashboard to see the new state record in the table.

You've now successfully created and used the Dapr pluggable Supabase state store component. 🎉

Next steps

This proof of concept implementation of a pluggable component demonstrates how the Dapr pluggable component .NET SDK makes it easier for developers to create their custom components. You can use this solution as a starting point, and expand it with additional state management API features, such as entity tag (ETag), metadata, and options, as described in the specification. A requirement for using this pluggable component in a real project is to deploy it to a (managed) Kubernetes environment or use it in a self-hosted mode.

The Supabase platform offers a great variety of useful back-end features, and with the set of client libraries it’s very accessible to a diverse group of developers. Take a look at Supabase Launch Week to read about their latest feature announcements.

From my perspective, I’d like to explore further how Dapr can integrate with other Supabase features. It would also be great to see a Supabase state store as a built-in component that’s available in the Dapr runtime without the need of running the pluggable component separately. I also hope the proposed DocumentStore building block will get some traction this year, since this will pair up very nicely with Supabase and other PostgreSQL stores.

Do you have any questions or comments about this blog post or the code? Join the Dapr discord and post a message in the #pluggable-components channel. Have you made something with Dapr? Post a message in the #show-and-tell channel, we love to see your creations!

Create event-driven applications with Cloudflare queues and Dapr

Marc Duiker — Thu, 09 Mar 2023 14:20:59 +0000

In this post, you’ll learn how to build a cloud to edge event-driven application with Dapr and Cloudflare. You’ll learn how to create:

A Cloudflare queue.
A consumer Cloudflare worker (in TypeScript) that reads messages from the queue.
A producer Dapr app (in TypeScript) that uses the Cloudflare Queue binding to publish messages to the queue.

Event-driven applications FTW 🚀

Event-driven applications are becoming increasingly popular. The decoupling of event producers and event consumers makes applications more resilient and flexible, since they allow independent implementation and scaling of the applications.

Cloudflare recently announced Queues, allowing developers to send and receive messages with guaranteed delivery and integrating with Cloudflare Workers, a fast edge computing platform.

Dapr, the open-source distributed application runtime, is often used in event-driven applications. Dapr provides a set of standardized API building blocks that simplify microservice development. By using the Bindings building block, developers can use input, and output bindings, and either trigger their apps or invoke other resources without having to learn resource-specific SDKs for these resources. With Dapr release 1.10, a new binding is provided that allows developers to publish messages to Cloudflare Queues. Because of the common set of APIs that Dapr offers, developers from any background can use the binding to publish messages to Cloudflare Queues without needing to know the Cloudflare SDKs or adding that dependency to their codebase.

Let’s start building an event-driven app and see the binding in action.

Prerequisites

The following is required to run this sample:

Clone this repository to your local machine.
Install Dapr CLI.
- Use the Dapr CLI to install the Dapr runtime locally:
  
  dapr init
Install Node.js.
Install Cloudflare Wrangler.
Ensure you're on a Cloudflare paid plan, since that is required to use Cloudflare queues.
Enable Queues in the Cloudflare dashboard.
- Dashboard > Workers > Queues
- Enable Queues Beta
- You should see a confirmation in the dashboard that queues are enabled.

Create the applications

The solution consists of three parts:

A Cloudflare queue
A consumer Cloudflare worker that reads messages from the queue.
A producer Dapr app that will publish messages to the queue.

1. Create a Cloudflare queue

Open a terminal and use the wrangler CLI to login to Cloudflare:

wrangler login

Follow the instructions in the browser to login to Cloudflare.

The response in the terminal should end with:

Successfully logged in.
Create the Cloudflare queue using the wrangler CLI:

wrangler queues create dapr-messages

The response in the terminal should end with:

Created queue dapr-messages.

2. Create a consumer Cloudflare worker

You can either create a new consumer worker by following steps 1-3, or use the existing consumer worker in this repository and continue from step 4.

In the root folder, create a worker to consume messages:

wrangler init consumer
1. Create package.json: Y
2. Use TypeScript: Y
3. Create worker: Fetch handler
4. Write tests: N
A new folder named consumer will be created which contains the worker.

Update the consumer/src/index.ts file to:

export default {
  async queue(
      batch: MessageBatch<Error>,
      env: Env
  ): Promise<void> {
      let messages = JSON.stringify(batch.messages);
      console.log(messages);
  },
};

Add the following lines to the consumer/wrangler.toml file:

[[queues.consumers]]
queue = "dapr-messages"
max_batch_size = 1

Ensure that you're in the consumer folder and install the dependencies:

cd consumer

npm install

Publish the consumer worker:

wrangler publish

The response in the terminal should end with:

Published consumer (... sec)
  https://consumer.<SUBDOMAIN>.workers.dev
  Consumer for dapr-messages
Current Deployment ID: <DEPLOYMENT_ID>

Start a tail to read the log of the consumer worker:

wrangler tail

3. Configure the producer Dapr app

The Cloudflare Dapr binding uses a Cloudflare worker to publish messages, since only Cloudflare workers can access the queue.

There are two options for this worker:

Dapr provisions the worker.
You use a pre-provisioned Cloudflare worker.

This sample uses option 1. Read the Cloudflare Queues binding spec and choose Manually provision the Worker script if you want to go for option 2.

Create a binding file

Rename the producer/resources/binding.yaml.template to producer/resources/binding.yaml.

Open the binding.yaml file and inspect its content.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: cloudflare-queues
spec:
  type: bindings.cloudflare.queues
  version: v1
# Increase the initTimeout if Dapr is managing the Worker for youinitTimeout: "120s"
  metadata:
# Name of the existing Cloudflare Queue (required)- name: queueName
      value: "dapr-messages"
# Name of the Worker (required)- name: workerName
      value: "dapr-message-worker"
# PEM-encoded private Ed25519 key (required)- name: key
      value: |
        -----BEGIN PRIVATE KEY-----
        MC4CAQ...
        -----END PRIVATE KEY-----
# Cloudflare account ID (required to have Dapr manage the Worker)- name: cfAccountID
      value: ""
# API token for Cloudflare (required to have Dapr manage the Worker)- name: cfAPIToken
      value: ""
# URL of the Worker (required if the Worker has been pre-created outside of Dapr)- name: workerUrl
      value: ""

The metadata.name, spec.metadata.queueName and spec.metadata.workerName values have already been set. Ensure that the queueName matches the queue setting in the consumer worker wrangler.toml file.

Values for spec.metadata.key, spec.metadata.cfAccountID, and spec.metadata.cfAPIToken still need to be provided.

Follow these instructions in the Dapr docs to set the value for spec.metadata.key.
The Cloudflare account ID should go in the spec.metadata.cfAccountID field. You can find the account ID in the Cloudflare dashboard URL: https://dash.cloudflare.com/<ACCOUNT_ID>/workers/overview.
A Cloudflare API token should go in the spec.metadata.cfAPIToken field. It can be generated as follows:
1. In the Cloudflare dashboard, go to the Workers page.
2. Click the API tokens link
3. Click the Create token button
4. Click the Use template button for Edit Cloudflare Workers
5. Update the permissions to only contain:
  - Account | Worker Scripts | Edit
6. Update the Account Resources to only contain:
  - Include | <YOUR ACCOUNT>
7. Set a time to live (TTL) for the token, the shorter, the better, if you're just testing.

Now the binding file is complete. The file is gitignored, so the secrets won't be committed to the repository.

Inspect the Node app

Let's have a look at the Dapr app that will send messages to the Cloudflare queue.

Inspect the producer/index.ts file.

import { DaprClient } from "@dapr/dapr";

// Common settingsconst daprHost = "http://localhost";
const daprPort = process.env.DAPR_HTTP_PORT || "3500";

async function main() {
    console.log("Starting...");

    const bindingName = "cloudflare-queues";
    const bindingOperation = "publish";
    const client = new DaprClient(daprHost, daprPort);
    for(var i = 1; i <= 10; i++) {
        const message =  { data: "Hello World " + i };
        const response = await client.binding.send(bindingName, bindingOperation, message);
        if (response)
        {
            console.log(response);
        }
        await sleep(1000);
    }

    console.log("Completed.");
}

async function sleep(ms: number) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }

main().catch((e) => {
    console.error(e);
    process.exit(1);
})

Note that the bindingName is set to cloudflare-queues and matches the value of the metadata.name in the binding.yaml. The bindingOperation is set to publish (create could be used as an alias).

Run the producer app

Open a new terminal window and navigate to the producer folder.
Install the dependencies:
```
npm install
```

Run the following command to start the producer app:

dapr run --app-id producer --resources-path ./resources -- npm run start

The terminal that logs the tail of the consumer app should show a log statement for each of the ten messages sent:

Unknown Event - Ok @ 17/02/2023, 11:22:50
  (log) [{"body":"{\"data\":\"Hello World 1\"}","timestamp":"2023-02-17T10:22:50.556Z","id":"8f6293d9d04001e3f2a12be5c47acde2"}]
...

Congratulations! You’ve now sent messages from a Dapr app to a Cloudflare Queue (& Worker) via the Cloudflare Queues binding! 🎉 Hungry for more Dapr bindings? Have a look at the long list of supported bindings.

Any questions or comments about this blog post or the code? Join the Dapr discord and post a message in the #components-contrib channel. Have you made something with Cloudflare and Dapr? Post a message in the #show-and-tell channel, we love to see your creations!

How to upgrade your local Dapr runtime and CLI

Marc Duiker — Wed, 22 Feb 2023 08:51:26 +0000

EDIT: updated for the Dapr 1.15 release :)

I've recently upgraded my local Dapr runtime and the Dapr CLI due to the new 1.15 release being available. Since I'll be upgrading to new releases on a regular basis, and use both Mac and a Windows machines, I might as well help my future self and write this down since I forget these things after a week 😅.

Upgrading the self-hosted environment (which I call the runtime) is described in detail in the official docs, but here I'm writing a slimmed down version, useful if you're either running Windows with winget, or macOS with Homebrew.

Uninstall the old Dapr runtime:
```
dapr uninstall
```
If you also want to remove the Redis and Zipkin images run:
```
dapr uninstall --all
```
Install the new Dapr runtime:
```
dapr init
```
Upgrade the Dapr CLI:

Using Windows and winget:
```
winget upgrade Dapr.CLI
```
Using macOS and brew:
```
brew upgrade dapr-cli
```
Verify that everything is upgraded:
```
dapr -v
```
The response should list the new versions:
```
CLI version: 1.15.0
Runtime version: 1.15.2
```
`

🚨 Bleeding edge 🚨

If you need the very latest, (bleeding) edge bits of Dapr, you can:

Pull the runtime images from the Dapr GitHub container registry.
Download the Dapr CLI release candidates from the Dapr CLI GitHub release page.

Enjoy the latest Dapr release!

Dapr 1.10 release highlights

Marc Duiker — Tue, 21 Feb 2023 08:23:41 +0000

The Dapr maintainers released a new version of Dapr, the distributed application runtime 🎉. This post highlights the major new features and changes in release 1.10, the first one in 2023.

Workflows

My favorite new feature is the workflow engine and building block. This feature enables developers to orchestrate business logic for messaging and state management across various microservices. Workflows are suitable for multistep processes such as order processing, HR onboarding, and coordinating software updates across many devices because workflows are stateful and support long-running services. Workflow patterns such as chaining and fan-out/fan-in are written in code to execute tasks reliably. The built-in workflow engine is durable and resilient and can either be used via HTTP/gRPC, as well as the .NET SDK (other languages will follow).

Read more about the Workflow building block in the Dapr docs or try out the Workflow Quickstart.

Pluggable Components SDKs

Dapr provides a long list of built-in components to work with. But if this isn’t enough, Pluggable Components allows developers to create their own components for their specific integration requirements. Pluggable Components can be written in any language that supports the gRPC protocol.

With release 1.10, developers can create components using the Pluggable Components SDKs in .NET, Java, and Go instead of using the gRPC protocol directly. This will enable many developers to create new components, both public and private ones.

Read more about Pluggable Components in the Dapr docs.

Running multiple Dapr apps

Running a microservices system locally can be challenging, since multiple apps need to be up and running. Developers would need to call the dapr run command for each microservice separately, which gets a bit tedious.

With release 1.10, another big developer productivity improvement has been achieved. Developers can now run multiple apps with just one command and a multi-app template file. The dapr run -f <path> command is used to run Dapr locally, where points to a directory that contains a dapr.yaml file, the multi-app template, that contains the properties to run the apps. More information on how to structure the multi-app template can be found in the Dapr docs.

Components

Dapr uses a modular design where functionality is delivered as a component. Release 1.10 contains both new components as improvements to existing components.

New Components

SQLite: Enables state store functionality using SQL Lite 3. SQLite is a small, fast and self-contained SQL database engine, great for local development and running on small devices.
Cloudflare KV: Enables state store functionality using Cloudflare Workers KV. Workers KV is a global, low-latency, key-value data store that is ideal for high read volumes.
Cloudflare Queues binding: Enables publishing message to Cloudflare queues. Cloudflare queues allow developers to send and receive messages with guaranteed delivery. It integrates with Cloudflare Workers and offers at-least once delivery and message batching.
KubeMQ binding: Supports input and output bindings for KubeMQ, an enterprise-grade Kubernetes-based message broker and message queue that is scalable, highly available, and secure
KubeMQ: Enables pub/sub messaging using KubeMQ.
Solace AMQP: Enables pub/sub messaging using Solace PubSub+ Event Broker. The Solace Event Broker is a container-based message broker that enables real-time data distribution between applications.

Component Improvements

With 1.10 many components have graduated to the Stable certification level. All components have a certification level as mentioned in the Certification Lifecycle. The Stable level means:

The component must have component certification tests validating functionality and resiliency.
The component is maintained by Dapr maintainers and supported by the community.
The component is well documented and tested.
The component has been available as Alpha or Beta for at least 1 minor version release of Dapr runtime prior.
A maintainer will address component security, core functionality and test issues according to the Dapr support policy and issue a patch release that includes the patched stable component.

The following components have progressed to Stable:

AWS SQS/SNS: Enables pub/sub messaging using AWS SQS or SNS.
AWS DynamoDB: Enables state store functionality using AWS DynamoDB.
CockroachDB: Enables state store functionality using CockroachDB.
MySQL: Enables state store functionality using MySQL.
HashiCorp Vault: Enables secret store functionality using HashiCorp Vault.
Pulsar: Enables pub/sub messaging using Apache Pulsar.
Azure Service Bus Queues binding: supports input and output binding to Azure Service Bus Queues.
Cron binding: Enables scheduled task execution via cron expressions.

If you’re using any of these components and have a demo to show, drop a link in the #show-and-tell channel on the Dapr Discord.

What is next?

This post is not a complete list of features and changes released in version 1.10. Read the official Dapr release notes for more information. The release notes also contain information on how to upgrade to this latest version.

Excited about these features and want to learn more? I’ll cover the new features in more detail in future posts. Until then, join the Dapr Discord to connect with thousands of Dapr users.

Be ready for failure on stage: introducing the Speaker Buddy System

Marc Duiker — Thu, 24 Nov 2022 14:45:38 +0000

Conferences

I love ❤️ going to in-person conferences, especially when I'm invited to speak there. Although I've been speaking at dozens of conferences and meetups over the past years, I still have impostor syndrome when it comes to speaking. Some people really seem to have a gift for public speaking, and sometimes I feel way out of my league. I do realize those experienced speakers have been practicing for years, and perhaps I'll get there as well, practice makes ~~perfect~~ improvement! 💪

Failing on stage

One thing that can throw me off during my speaking sessions is technical issues. And I don't mean failing demos (I'm used to those 🫠), but audio/video issues that require minutes (feels like hours 😭) to solve.

A couple of weeks ago, I had such an issue where my laptop didn't mirror the screen to the AV system. I was using a MacBook that I had used a dozen times before, but I'm not very familiar with macOS, and even when I got some help (and tried multiple adapters), the issue wasn't solved. It was a few minutes past the official start time of the talk, and I was now getting nervous (and I'm quite a chill person otherwise). Luckily the speaker before me (Mattias Karlsson) had a brilliant idea: he asked me to install TeamViewer on my laptop, connect to the TeamViewer session on his laptop, and he would connect his machine to the AV system. This worked like a charm (WiFi was reasonable), and I was able to start my talk about 5 minutes late. 🎉 The stress I built up during those minutes was not beneficial for my delivery though. My breathing was shallow, and my pace was too fast.

Could I have prevented the technical issue? No, but I could have been better prepared.

TLDR: Have a look at the Speaker Buddy System.

Preparing for failure

There are several ways of preparing for technical issues. I'll share some of my ideas, and close with an idea initially proposed by Mattias, called the Speaker Buddy System.

I won't cover 'my demo doesn't work' failures here, since these things can be solved in different ways, such as; showing a solution that has been prepared beforehand, or recording the solution before the conference and playing it back during the session.

The general idea to overcome a catastrophic (laptop) failure is to ensure that your presentation, code, and demos are available on other environments you can quickly access.

Let's go through some solutions:

Bring a second laptop

Yes, it can be that 'easy'. But one, you need to have a second laptop (💸), and two, you need to take it with you when traveling, which isn't always an option. I have a small Windows Surface Go that I usually bring with me next to my main laptop.

Cloud storage

For things that don't require showing or running code, you can use a cloud storage solution like OneDrive, Google Drive, Dropbox, or even a git repository. I use OneDrive to store and access my presentations. If your laptop fails, you still need to use another machine, but you can access your presentation relatively quickly (if you have access to the internet).

Cloud-hosted coding environments

When you do need to show, or run, code in your session, make sure you can run it in the cloud instead of your own machine! I have all my source code on GitHub, and I'm using GitHub Codespaces so I can run a demo completely in the cloud if necessary. There are many similar solutions out there such as Gitpod, JetBrains Space, CodeSandbox.
The downside of this solution is that it does require a good internet connection.

TIP: If your source code is on GitHub, and you just need to show the source code, you can use github.dev, a lightweight, browser-based editor (based on VSCode) you can access by replacing .com with .dev when typing the repository URL. It even supports some extensions such as the brilliant CodeTour, which is great for showing code in a guided way throughout your session.

The Speaker Buddy System

This is the idea that Mattias and I talked about after my failing laptop experience, and I love it! We named it Speaker Buddy (not to be mistaken with Conference Buddy), but I'm open to better names. In the solutions mentioned above, you still need access to another laptop (and the internet), and the Speaker Buddy system solves this!

1. For conference speakers

1.1. For speakers who want to volunteer as Speaker Buddy

You can be a Speaker Buddy if you enjoy helping others to be successful during their talks.

You can help out by:

Being kind and respectful (e.g. following the Code of Conduct of the conference).
Announcing that you're available to help out as a Speaker Buddy (preferably do this via the conference organizers and their communication channels).
Agreeing up front how you can help (see 1.2).

1.2. For speakers who want a Speaker Buddy

If you are going to speak at a conference and you want another speaker to have your back in case you run into technical issues or just want a friendly and supportive face on the front row, then this is for you!

Once the conference agenda is known and the Speaker Buddies are confirmed by the conference organizers, contact one of the Speaker Buddies (who does not speak at the same time as you!) to ask if they are willing to help you out in case of technical issues/laptop failure, or just being there as a friendly face in the audience. If they are, you can discuss the details such as:

Supporting you by sitting in the front row (smiling and nodding).
Have a copy of your presentation on their machine.
Cloning your code repository, installing SDKs and tools on their machine, if you want to show/run code locally.
Doing a (remote) dry run via their laptop to be completely prepared for a technical failure. (You also test your database backups right?)
Is there any other way your buddy can help you out? Can they tell a funny story during the technical issue, ask a relevant question, help out in case you get difficult questions, or do something else to put you at ease?

Even with the existence of cloud-based coding environments, I still suggest having a local environment available in case the internet connection is not good enough.

2. For conference organizers

I know organizers have a lot to worry about when organizing a conference, and most of the conferences I attended did a good job regarding the AV setup. I prefer when there are hired AV professionals to help out, but in case they are not, please ensure there is at least someone from the organization available in the room to assist when technical issues arise.

Additionally, you can offer your speakers some peace of mind when they know someone has their back in case of technical difficulties (e.g. laptop failure).

2.1. CfP preparation

When preparing the Call for Papers (CfP), add a field to whatever system you're using to have the speaker indicate if they are willing to be a Speaker Buddy. Include a link to this repo so they can read more about it.

2.2. Speaker onboarding/confirmation

When onboarding/confirming speakers to your conference, mention the Speaker Buddy System and provide the list of speakers who have volunteered to be a Speaker Buddy.

Feel free to use this template in your communication:

Hi {speaker},

We highly encourage you to look for a Speaker Buddy before attending our conference.

A Speaker Buddy is another speaker that can help you out in case of technical issues (e.g. laptop failure).

These speakers are volunteering as Speaker Buddies:

{list of speakers}

Our conference agenda is published at {conference agenda url}, so look for a Speaker Buddy that is available during your session.

It's best to prepare well in advance. For more information on how to be prepared, read the tips at https://github.com/marcduiker/speaker-buddy.

3. Preparing the event location

When you prepare the conference rooms, label a front-row seat for the Speaker Buddy. This way, they can be supportive and help out the speaker quickly in case of technical issues.

Let's use it!

I've put together a repository that contains most of the info in this blog post. I highly encourage conference organizers to refer to this repo in their communication to inform speakers about the Speaker Buddy System.

If you see an opportunity for improvement, please submit an issue or pull request! ❤️

One year at Ably as a Developer Advocate

Marc Duiker — Fri, 11 Nov 2022 09:03:18 +0000

It has been one year since I've joined the DevRel team at Ably as Sr Developer Advocate. In this post I'll highlight some things I've been working on and what I've learned in the past year. I'll cover content creation, developer tooling, events, roadmap & predictability, communication & relationships, and finally 'anything that could be improved'.

Content creation

Before I joined Ably, I mostly worked on event-driven architectures using .NET-based backends and Azure services (Azure Functions, CosmosDB, Service Bus). Ably really shines when real-time communication is needed between clients, or between servers and clients, so this meant I had to get up to speed with client-side programming, and WebSocket-based communication using the Ably SDK.

During my onboarding, I created my first demo, Agile Flush, a small and playful web app to do remote planning poker. This was my first introduction to VueJS and the Ably client SDK, and after a while I got to like working with Vue. It did take me some time to get used to the toolchain though.

I've stuck to using Vue (TypeScript based, with Vite for the dev tooling) for most of my demos where I need a front-end. It pairs nicely with Azure Static Web Apps that I use for hosting the demos.

Here's a list with all the demos I've created so far, including related content pieces.

Agile Flush

A playful web app for remote poker planning. The clients publish their votes and actions to Ably, and Ably pushes the updates to the subscribed clients.

What is pub/sub and how to apply it in C# .NET to build a chat app

The demo is a .NET 6 console application that can publish or subscribe to messages which get delivered through Ably. The blog post also covers the basics what pub/sub is, the typical use cases, and benefits.

Serverless WebSockets Quest

A turn-based mini game with with real-time aspects build on Azure Functions, Durable Functions, and Ably.

Collaborative Pixelart Drawing

A collaborative pixelart drawing canvas. Multiple users draw on a canvas, and their movement and actions are shared with the other connected users.

I created two versions of this demo, one using Ably, and one using Azure Web PubSub, and did a write-up about difference in developer experience between the two services.

Serverless Pizza Workflow Visualizer

A demo that visualizes the real-time progress of a serverless workflow that is built with Durable Functions. I really had a lot of fun creating the pizza-themed visuals for this demo.

Developer tooling

I really like improving the developer experience from a tooling perspective. Ably has a Control API, a RESTful interface that allows management of the Ably apps. I've used this API in several tools to speed up the creation of apps and keys.

Ably Control API GitHub Action

Since most of my demos require a new Ably App, I created a GitHub action that creates an app from a GitHub workflow. The action also enables the the creation of an API key with a configurable set of capabilities. This was the first time I've created a GitHub action, which was a great learning experience for me. The action has a limited feature set, but I intend to add more features in the future.

Ably VSCode extension

During the first Ably Innovation Days, I proposed to create a VSCode extension that allows developers to manage their Ably apps directly from VSCode. I formed a team with several colleagues, and in two days we had a working prototype that lists all the Ably apps in the activity bar, and creates a new Ably app via the command palette. We won the Ship It 🚢 award with this prototype, which allowed me to continue working on the extension and release it to the VSCode extension marketplace.

Ably CLI

During the second Ably Innovation Days, I started working on specifications for an Ably CLI. After the first day Phil and I started with a prototype based on oclif. We managed to create a working prototype in a day that lists Ably apps, and creates a new Ably app. This project is still Work In Progress. Once the CLI is in a releasable state, I'll create some content around this.

GitHub repo

Events

I had the opportunity to speak at several conferences and meetups this year, both online and in-person. It was great to attend in-person events again, networking with other people, seeing people respond to your talk, and people asking questions afterwards. I'm still a proponent of online (or hybrid) events as well though. Online events can be more accessible, and allow for a more diverse audience.

Events I spoke at:

Roadmap & Predictability

Part of my role involves creating and updating a roadmap for the .NET & Azure community. This document refers to the company strategy, and how the DevRel team activities fit in that strategy. The roadmap contains the topics which I plan to create content for, estimations on their outcomes, and a timeline. The metrics & predictability of the outcomes is really one of the most difficult parts in DevRel. One blog post can go viral while the next one hardly gets any engagement. It's important to try understand why something works well or why it doesn't.

What I've learned over the last year is that content creation is just a small part of the bigger picture when working in DevRel. Content distribution is just as important. If I write a great blog post but hardly anyone will read it, then writing it has been a waste of my time. I'm spending more time these days on the distribution part, to make sure the content gets the proper exposure across various channels. It's not a part I particularly like, but it needs to be done, and I do appreciate the new insights it gives me.

Reflecting on the content, the engagement, and analyzing the performance (visits, session duration, sign-ups etc) is even more important. If a content piece is not resulting in (enough) sign-ups, then we investigate why, change the content, or use a different approach for future pieces. We're measuring several aspects for a couple of months now and it still feels like we're at the beginning of understanding the numbers. It's certainly an area that interests me, and where I want to improve the predictability of my work. Being in DevRel means that you're constantly learning, measuring, and tweaking. And that's what I love about it.

Communication & Relationships

So far, it looks like this is all a one-person-show, but it's far from that.

I depend on:

My DevRel and content team colleagues, who help me review the content I create.
Our community manager, who informs me of CfPs, sponsoring opportunities, and new questions on Discord and social media.
Our content marketing team, to provide me with insights on keyword research and content performance.
Our product team, to keep me up to date with the latest product features and changes.
My managers, to provide me with valuable feedback about my work, so I can keep improving.

The relations part of DevRel is really crucial. In order to have a good relation with your developer audience, you also need to have a good relation with your team members, Marketing, Product, Documentation, Engineering, and Customer Support. Establishing and growing these relations take time. New people join the company and others leave, it's an ever changing environment. It can be tiring and challenging at times, but once the relationship is there, it feels good to work together to achieve a common goal.

Anything that could be improved?

Always! 😅 I noticed that I spent less time on my open source projects than before I joined Ably. It's probably because I now create content for a living, I don't always feel like doing that in my spare time as well. I still have plenty of plans to continue working on these projects though, it just needs a bit more planning and prioritization.

One of the areas I really want to expand on is collaborations with other people. These could be collaborations with other DevRel folks, or individual developers who share a common interest around serverless, real-time communication, pixelart, or something completely out of the box! If you think we should combine forces to work on a fun project together, please reach out!

Create realtime dashboards to show serverless workflow progress

Marc Duiker — Tue, 18 Oct 2022 08:05:12 +0000

In this post I'll explain how to use a cloud pubsub service such as Ably to visualize the progress of a serverless workflow in realtime.

You'll learn:

How to build serverless workflows with Azure Functions & Durable Functions.
How to publish messages from activity functions in the back-end.
How to subscribe to these messages in the front-end.

TLDR: Go to the live demo or view the source on GitHub.

Background

Organizations that have their business processes automated often need to show the progress of these processes to their users - either via internal dashboards, or via external client portals. Common use cases include applying for a reimbursement at your health insurance provider, or making an online purchase.

Over the years, automation has resulted in the decoupling of front-ends and back-ends. Although decoupling is great for improving resiliency and effective scaling, it does make it more challenging to inform the front-end of status updates that occur in the back-end, especially with asynchronous communication, and serverless back-ends that are not always running.

A suitable way to update a front-end from back-end processes is to use pubsub over WebSockets. In this post I'll show how to use Ably, a cloud based pubsub service, to visualize the progress of a serverless workflow implemented with Azure Functions and Durable Functions.

Tech stack

The project uses the following components:

Azure Functions, the serverless compute service in Azure.
Durable Functions, an extension for Azure Functions that allows writing workflows as code and enables stateful functions.
Vue3, a popular front-end framework.
Azure Static Web Apps, a hosting solution in the Azure cloud.
Ably, a serverless pubsub service for realtime messaging at scale.

This diagram show the various functions and their interactions:

The serverless workflow

The serverless workflow is implemented with Durable Functions. This is an extension for Azure Functions that allows workflows to be written as code. It enables stateful orchestrator functions because an Azure storage account is used behind the scenes. The interactions with the storage account, the queues, and table storage, are abstracted away. The Durable Functions API is used when writing an orchestrator function that chains several activity functions in a sequence. The code below shows the PizzaWorkflowOrchestrator function that is chaining six activity functions:

public class PizzaWorkflowOrchestrator
{
    [FunctionName(nameof(PizzaWorkflowOrchestrator))]
    public async Task Run(
        [OrchestrationTrigger] IDurableOrchestrationContext context,
        ILogger logger)
    {
        var order = context.GetInput<Order>();

        var instructions = await context.CallActivityAsync<IEnumerable<Instructions>>(
            nameof(ReceiveOrder),
            order);
        await context.CallActivityAsync(
                nameof(SendInstructionsToKitchen),
                instructions);

        var preparationTasks = new List<Task>();
        foreach (var instruction in instructions)
        {
            if (instruction.MenuItem.Type == MenuItemType.Pizza)
            {
                preparationTasks.Add(context.CallActivityAsync(
                    nameof(PreparePizza),
                    instruction));
            }
        }

        await Task.WhenAll(preparationTasks);

        await context.CallActivityAsync(
            nameof(CollectOrder),
            order);
        await context.CallActivityAsync(
            nameof(DeliverOrder),
            order);
        await context.CallActivityAsync(
            nameof(DeliveredOrder),
            order);
    }
}

/// For the full implementation see https://github.com/ably-labs/serverless-workflow-visualizer/blob/main/api/PizzaWorkflow/Orchestrators/PizzaWorkflowOrchestrator.cs.

The responsibility of the orchestrator function is to initiate the execution of the activity functions in the right order. The orchestrator function will replay from the start several times and therefore the function must be deterministic to avoid side effects. Any non-deterministic behavior (e.g. communication with external APIs) should be put in activity functions.

In this demo, the activity functions are merely placeholders and don't do anything meaningful. The functions only log information statements, simulate a randomized wait time, and publish the progress to Ably.

Publishing messages from the back-end

Since each of the activity functions require their progress to be published, I created an abstract MessagingBase class to wrap the publishing behavior for easy re-use.

public abstract class MessagingBase
{
    private readonly IRestClient _ablyClient;

    protected MessagingBase(IRestClient ablyClient)
    {
        _ablyClient = ablyClient;
    }

    protected async Task PublishAsync(string orderId, string eventName, object data)
    {
        var channelName = $"{Environment.GetEnvironmentVariable("ABLY_CHANNEL_PREFIX")}:{orderId}";
        var channel = _ablyClient.Channels.Get(channelName);
        await channel.PublishAsync(eventName, data);
    }
}

/// For the full implementation see https://github.com/ably-labs/serverless-workflow-visualizer/blob/main/api/PizzaWorkflow/Activities/MessagingBase.cs.

The activity functions inherit from this abstract class and call the PublishAsync method, as can be seen in the CollectOrder activity function:

 public class CollectOrder : MessagingBase
{
    public CollectOrder(IRestClient ablyClient) : base(ablyClient)
    {
    }

    [FunctionName(nameof(CollectOrder))]
    public async Task Run(
        [ActivityTrigger] Order order,
        ILogger logger)
    {
        logger.LogInformation($"Collect menu items for order {order.Id}.");
        Thread.Sleep(new Random().Next(3000, 6000));
        await base.PublishAsync(order.Id, "collect-order", new WorkflowState(order.Id));
    }
}

/// For the full implementation see https://github.com/ably-labs/serverless-workflow-visualizer/blob/main/api/PizzaWorkflow/Activities/CollectOrder.cs.

The WorkflowState object is used as the payload when publishing progress updates:

public class WorkflowState
{
    public WorkflowState(string orderId)
    {
        OrderId = orderId;
        MessageSentTimeStampUTC = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();
    }

    [JsonProperty("orderId")]
    public string OrderId { get; set; }

    [JsonProperty("messageSentTimeStampUTC")]
    public long MessageSentTimeStampUTC { get; set; }
}

/// For the full implementation see https://github.com/ably-labs/serverless-workflow-visualizer/blob/main/api/PizzaWorkflow/Models/WorkflowState.cs.

Note that the WorkflowState doesn't contain information about the exact state of the workflow. This is because named events are used, and these names correspond with the activity function name. The front-end subscribes to these named events; therefore, no additional workflow information is required in the WorkflowState.

The MessageBase class requires an IRestClient object. This is the Ably REST client, and is configured in the StartUp class, and injected in each of the activity functions:

[assembly: FunctionsStartup(typeof(StartUp))]
namespace PizzaWorkflow
{
    public class StartUp : FunctionsStartup
    {
        public override void Configure(IFunctionsHostBuilder builder)
        {
            builder.Services.AddSingleton<IRestClient>(
                new AblyRest(Environment.GetEnvironmentVariable("ABLY_API_KEY")));
        }
    }
}

/// For the full implementation see https://github.com/ably-labs/serverless-workflow-visualizer/blob/main/api/PizzaWorkflow/StartUp.cs.

The ABLY_API_KEY environment variable contains an Ably API key with publish capabilities.

Now that we've seen how the serverless workflow publishes the progress updates for each activity, let's have a look at the front-end where the messages are received.

Receiving messages in the front-end

The Vue front-end uses Pinia as the local state store. The store contains WorkflowState definitions for each of the six workflow states, which are enabled - one by one - as the workflow progresses.

export type PizzaWorkflow = RealtimeState & {
  clientId: string;
  orderId: string;
  isWorkflowComplete: boolean;
  disableOrdering: boolean;
  orderReceivedState: WorkflowState;
  kitchenInstructionsState: WorkflowState;
  preparationState: WorkflowState;
  collectionState: WorkflowState;
  deliveryState: WorkflowState;
  deliveredState: WorkflowState;
  isOrderPlaced: boolean;
};

/// For the full implementation see https://github.com/ably-labs/serverless-workflow-visualizer/blob/main/src/types/PizzaWorkflow.ts.

export type WorkflowState = {
  title: string;
  orderId: string;
  image: string;
  isVisible: boolean;
  isDisabled: boolean;
  isCurrentState: boolean;
  messageSentTimeStampUTC: number;
  messageReceivedTimestamp: number;
  messageDeliveredTimestamp: number;
};

/// For the full implementation see https://github.com/ably-labs/serverless-workflow-visualizer/blob/main/src/types/WorkflowState.ts.

The WorkflowState contains the following timestamps:

messageSentTimeStampUTC, the time set when the WorkflowState object was instantiated in the .NET back-end.
messageReceivedTimestamp, the time that the message was received in the Ably platform.
messageDeliveredTimestamp, the time set in the front-end when the message was received.

These three times should all be very close to each other. However some irregularities will be visible since these times are set in different machines, across various networks, meaning the clocks are not synced. Therefore it is possible that the messageReceivedTimestamp is slightly earlier than the messageSentTimeStampUTC etc. So, the times are not 100% accurate, but they are close enough to give a good indication of the speed of message delivery.

Instantiating the Ably realtime client

A WebSocket-based connection is set up using the Ably realtime client.

async createRealtimeConnection(clientId: string, order: Order) {
    if (!this.isConnected) {
        this.realtimeClient = new Realtime.Promise({
          authUrl: `/api/CreateTokenRequest/${clientId}`,
          echoMessages: false,
        });
        this.realtimeClient.connection.on(
          "connected",
          async (message: Types.ConnectionStateChange) => {
            this.isConnected = true;
            this.attachToChannel(order.id);
            if (!this.isOrderPlaced) {
              await this.placeOrder(order);
              this.$state.isOrderPlaced = true;
            }
          }
        );

        this.realtimeClient.connection.on("disconnected", () => {
          this.$state.isConnected = false;
        });
        this.realtimeClient.connection.on("closed", () => {
          this.$state.isConnected = false;
        });
      } else {
        this.attachToChannel(this.orderId);
      }
    }

/// For the full implementation see https://github.com/ably-labs/serverless-workflow-visualizer/blob/main/src/stores/index.ts.

A call is made to the CreateTokenRequest endpoint (hosted as a serverless function) which returns an authentication URL, including a token that is used to initiate a secure connection with Ably.

[FunctionName(nameof(CreateTokenRequest))]
public async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "CreateTokenRequest/{clientId?}")] HttpRequestMessage req,
    string clientId,
    ILogger log)
{
    var tokenParams = new TokenParams() { ClientId = clientId };
    var tokenData = await _ablyClient.Auth.RequestTokenAsync(tokenParams);

    return new OkObjectResult(tokenData);
}

/// For the full implementation see https://github.com/ably-labs/serverless-workflow-visualizer/blob/main/api/Auth/CreateTokenRequest.cs.

Subscribing to named events

Once a connection is established and the Ably channel is retrieved, the front-end is subscribing to the named events that correspond with the activity functions:

subscribeToMessages() {
    this.channelInstance?.subscribe(
        "receive-order",
        (message: Types.Message) => {
          this.handleOrderReceived(message);
        }
      );
      this.channelInstance?.subscribe(
        "send-instructions-to-kitchen",
        (message: Types.Message) => {
          this.handleSendInstructions(message);
        }
      );
      this.channelInstance?.subscribe(
        "prepare-pizza",
        (message: Types.Message) => {
          this.handlePreparePizza(message);
        }
      );
      this.channelInstance?.subscribe(
        "collect-order",
        (message: Types.Message) => {
          this.handleCollectOrder(message);
        }
      );
      this.channelInstance?.subscribe(
        "deliver-order",
        (message: Types.Message) => {
          this.handleDeliverOrder(message);
        }
      );
      this.channelInstance?.subscribe(
        "delivered-order",
        (message: Types.Message) => {
          this.handleDeliveredOrder(message);
        }
      );
    },

/// For the full implementation see https://github.com/ably-labs/serverless-workflow-visualizer/blob/main/src/stores/index.ts.

Each of the subscribe methods calls a handler function that updates the specific WorkflowState in the Pinia store, see for example, the handleOrderReceived handler:

handleOrderReceived(message: Types.Message) {
    this.$patch({
        orderReceivedState: {
          orderId: message.data.orderId,
          messageSentTimeStampUTC: message.data.messageSentTimeStampUTC,
          messageReceivedTimestamp: message.timestamp,
          messageDeliveredTimestamp: Date.now(),
          isDisabled: false,
          isCurrentState: true,
        },
        kitchenInstructionsState: {
          isVisible: true,
        },
      });
    },

/// For the full implementation see https://github.com/ably-labs/serverless-workflow-visualizer/blob/main/src/stores/index.ts

Updating the UI

The PizzaProcess.vue component contains the sequence of the six states in the workflow:

<template>
  <ProgressItem
    class="animate"
    v-if="(orderReceivedState as WorkflowState).isVisible"
    :state="(orderReceivedState as WorkflowState)"
  />
  <ProgressItem
    class="animate"
    v-if="(kitchenInstructionsState as WorkflowState).isVisible"
    :state="(kitchenInstructionsState as WorkflowState)"
  />
  <ProgressItem
    class="animate"
    v-if="(preparationState as WorkflowState).isVisible"
    :state="(preparationState as WorkflowState)"
  />
  <ProgressItem
    class="animate"
    v-if="(collectionState as WorkflowState).isVisible"
    :state="(collectionState as WorkflowState)"
  />
  <ProgressItem
    class="animate"
    v-if="(deliveryState as WorkflowState).isVisible"
    :state="(deliveryState as WorkflowState)"
  />
  <ProgressItem
    class="animate"
    v-if="(deliveredState as WorkflowState).isVisible"
    :state="(deliveredState as WorkflowState)"
  />
</template>

<!-- For the full implementation see https://github.com/ably-labs/serverless-workflow-visualizer/blob/main/src/components/PizzaProcess.vue. -->

The ProgressItem.vue component contains the definition of a single workflow state:

<template>
  <div class="item">
    <div class="green-dot">
      <img
        v-bind:class="{
          disabled: props.state.isDisabled,
          transition: true,
        }"
        :src="GreenDot"
        height="32"
      />
    </div>
    <div class="details">
      <img
        v-bind:alt="props.state.title"
        v-bind:title="getImgTitle(props.state)"
        v-bind:class="{
          disabled: props.state.isDisabled,
          transition: true,
        }"
        :src="props.state.image"
      />
      <p v-bind:class="{ disabled: props.state.isDisabled }">
        {{
          props.state.isDisabled
            ? "Waiting for your order..."
            : `${convertToTimeSeconds(
                props.state.messageReceivedTimestamp
              )} - ${props.state.title} (${props.state.orderId.split("-")[1]})`
        }}
      </p>
    </div>
  </div>
</template>

<!-- For the full implementation see https://github.com/ably-labs/serverless-workflow-visualizer/blob/main/src/components/ProgressItem.vue.-->

Running locally

The following dependencies are required to run the solution locally:

.NET 6 SDK. The .NET SDK required for the C# Azure Functions.
Node 16. The JavaScript runtime required for the Vue front-end and installing the Static Web Apps CLI.
Azure Functions Core Tools. This is part of the Azure Functions extensions for VSCode that should be recommended for automatic installation when this repo is opened in VSCode.
Azurite. This is a local storage emulator that is required for Durable Functions. When this repo is opened in VSCode, a message will appear to install this extension.
Azure Static Web Apps CLI. Install this tool globally by running this command in the terminal: npm install -g @azure/static-web-apps-cli.
A free Ably Account, sign up or log in to ably.com, and create a new app and copy the API key.
Optional: The Ably VSCode extension to have easy access to the API keys of your Ably app.

There are two components in this solution that run independently from each other:

The back-end that runs the Durable Functions workflow (PizzaWorkflow.csproj).
The Static Web App that contains the front-end (a Vue3 project) and a function app (Auth.csproj).

In order to run and test the solution locally, first start the PizzaWorkflow function app, then the Static Web Apps project.

Steps to run the PizzaWorkflow function app

Run dotnet restore in the api/PizzaWorkflow folder to install the dependencies.
Rename the api/PizzaWorkflow/local.settings.json.example file to api/PizzaWorkflow/local.settings.json.
Copy/paste the Ably API key in the ABLY_API_KEY field in the local.settings.json file.
Start Azurite (VSCode: CTRL+SHIFT+P -> Azurite: Start).
Start the PizzaWorkflow function app by either pressing F5 or running func start in the api/PizzaWorkflow/ folder.

Steps to run the Static Web Apps locally

Run npm install in the root folder to install the dependencies.
Rename the api/Auth/local.settings.json.example file to api/Auth/local.settings.json.
Copy/paste the Ably API key in the ABLY_API_KEY field in the local.settings.json file.
Run swa start in the root folder.

Now, browse to http://localhost:4280 and click the Place Order button to start the workflow.

Summary

We've seen how to build a serverless workflow using Azure Functions and Durable Functions, and how to publish the progress in realtime using Ably. This type of solution is great for all kinds of realtime dashboards, and serverless back-ends, regardless of the cloud service provider.

When applied at a larger scale, with hundreds of workflows running simultaneously, the same approach can be used to drive a front-end summarizing progress using live charts. I'll explore this in a future post.

I encourage you to clone/fork the repository and run the solution yourself. Try to add another activity call to the workflow and have the front-end respond to it. Let me know on Discord what your experience is.

Cloud pubsub services compared: Azure Web PubSub & Ably

Marc Duiker — Thu, 18 Aug 2022 11:18:00 +0000

In this post, I compare two cloud pubsub services: Azure Web PubSub and Ably, to determine which provides the best development experience. The context will be a multi-user pixelart drawing application that I've built with both services.

How easy is it to use their SDKs/APIs?
How much code do you need to write to add realtime capabilities to your app?

This is not a step-by-step instruction on how to build the entire application, I'll highlight some key features and differences.

TLDR: Draw on the live canvas, or look at the source code in the GitHub repo which includes CodeTours to guide you through the solution.

Watch the video to learn about the three largest differences between Web PubSub and Ably.

Realtime messaging is taking over the world. Our food delivery apps show us our meal is only 5 minutes away. We use chat applications every day for work and private use. We receive the latest news on sports, stocks and celebrity news on our mobile devices, and we collaborate on digital documents.

As I mentioned in my recent article about pubsub with C#.NET, there are plenty of benefits of using pubsub in multi-user realtime applications. The number of cloud-based messaging services that include client-side pubsub has been growing significantly and for developers it can be difficult to make a decision which one to use. The services available are built using protocols such as WebSockets: some services offer the native WebSocket API directly while others have created abstractions on top of it, making it easier to use.

Let's have a look at the technologies used in this application and expand on the cloud-based WebSockets providers.

Tech stack

I've created two versions of a collaborative drawing application. Both versions use these components:

p5js: A creative coding library, used for the drawing canvas.
Azure Functions: A serverless compute service from Microsoft Azure, used for the authentication endpoint, and a function to change the color palette.
Azure Static Web Apps: An Azure service for hosting the static web app.

Serverless WebSockets

One version of the drawing application uses Ably, the other uses Azure Web PubSub. Both are cloud-based pubsub services (or Serverless WebSocket providers), used for realtime communication. Here's an overview of some features they offer.

Feature	Ably	Azure Web PubSub
pubsub messaging	Y	Y
message queues	Y	N
presence	Y	N
connection state recovery	Y	Y¹
automatic transport selection²	Y	N
guaranteed message ordering	Y	Y
message history	Y	N
webhooks	Y	Y

¹ Web PubSub reliable subprotocol is still in preview.
² Ability to use the best transport available depending on client capablities.

The communication between clients and the cloud-based messaging service is shown in this diagram:

How I compare cloud pubsub services

I compare the two services by considering the following criteria:

Creating the cloud resource
Authentication
Creating a client-side connection
Presence
Publishing messages
Subscribing to messages

Naming

Before I start comparing the developer experience, let's have a look at naming first, since both cloud services sometimes use a different terminology for certain concepts.

Ably	Azure Web PubSub	Description
App	Service Instance	A cloud resource is usually created per application. This resource can contain multiple channels/hubs.
Connection	Connection	An individual client connection (over WebSockets) that is connected to the cloud service.
Channel	Hub	Logical group of client connections, usually for one purpose (e.g. chat).
Presence	-	Awareness of the clients present in a channel. Clients can announce their presence by entering a channel, or remove their presence by leave a channel. Presence can be queried to retrieve a list of clients present in a channel.
-	Group	A subset of client connections. Clients can join or leave a group. A Group can't be queried for their members. Messages can be sent to a group instead of an entire Hub.
Integrations	Event Handlers	A method of adding extra functionality (e.g. calling a webhook, relaying a message to an upstream server) once messages are received at the cloud service.
User	User	A user (person) uses a client (device) to establish a connection to the cloud service. One user can have multiple connections when using several clients.
Client	Client	A client device that uses one connection to communicate with the cloud service.
Message	Message	Information that is published by a user, sent to the cloud service and distributed to the connected clients.

For more detailed info, see Web PubSub Service Internals and Ably Key Concepts.

Creating the cloud resource

Before we can do anything with cloud-based messaging, we need to create the appropriate resources.

Ably

For Ably, the first thing that has to be done is to create a new Ably app and an API key. If you've just signed up, a new default app and root API key is already created for you. I do suggest that you create a dedicated Ably app for each application you build.

The same goes for the API key. The default root API key has all the capabilities that Ably offers and probably has too many rights. For this application, you only require Publish, Subscribe and Presence capabilities. The API key is required when using the Ably SDK for authentication.

Creating the Ably app and API key can be done via:

Web PubSub

For Web PubSub Service, you need to create a new Web PubSub service resource in Azure. You require an Azure subscription. When creating the cloud resource, you have to specify a resource group and a region to deploy the service.

Once the service instance is created, you'll find the connection strings in the Keys blade in the portal. One of these connection strings is required when using the server-side Web PubSub SDK for authentication.

Creating the Azure resource can be done via:

The Azure portal
The Azure CLI
Bicep templates
Third-party infrastructure tools such as Terraform and Pulumi.

Resource creation differences

For the Azure resource, you need to define a region where the Web PubSub resource will be deployed. For Ably, you don't have to pick a region, it's multi-region by default (hosted on AWS). When a client connection is established, the Ably client will select a region that results in the lowest latency.

For Ably, you need to create an API key with the required capabilities, unless you're using the root key which has all the capabilities. For Web PubSub, there are connection strings (primary and secondary) and the Client URL Generator that is intended for test and validation purposes only.

Authentication

For a client to connect to the cloud service, it requires a client access token. Both Web PubSub and Ably provide SDKs to generate these tokens server-side, since it's not advised to have these tokens in client-side code. To generate the tokens, the SDKs require a connection string or API key to authenticate to the cloud service.

Ably

For Ably, an Azure Function is written in C# that uses the .NET ably.io NuGet package to create a client access token:

[FunctionName(nameof(CreateTokenRequest))]
public async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "CreateTokenRequest/{clientId}")] HttpRequestMessage req,
    string clientId,
    ILogger log)
{
    var tokenParams = new TokenParams() { ClientId = clientId };
    var tokenData = await _ablyClient.Auth.RequestTokenAsync(tokenParams);

    return new OkObjectResult(tokenData);
}

See GitHub for the full implementation.

The CreateTokenRequest function depends on an Ably IRestClient object via constructor injection. The dependency is configured in the StartUp class:

public override void Configure(IFunctionsHostBuilder builder)
{
    var ablyApiKey = Environment.GetEnvironmentVariable("ABLY_APIKEY");
    var ablyClient = new AblyRest(ablyApiKey);
    builder.Services.AddSingleton<IRestClient>(ablyClient);
}

See GitHub for the full implementation.

The Ably API key mentioned in the Creating the cloud resource section is put in the App Settings of the Azure Function App, so it can be retrieved as an environment variable, and used when an instance of the AblyRest client is created.

Azure Web PubSub

For Azure Web PubSub, a similar CreateTokenRequest Azure Function is created that uses the Azure.Messaging.WebPubSub NuGet package.

[FunctionName(nameof(CreateTokenRequest))]
public async Task<HttpResponseMessage> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "CreateTokenRequest/{hubName}/{groupName}/{clientId}")] HttpRequestMessage req,
    string hubName,
    string groupName,
    string clientId,
    ILogger log)
{
    var webPubSubService = new WebPubSubServiceClient(
        Environment.GetEnvironmentVariable("WebPubSubConnectionString"),
        hubName);
    var clientUri = await webPubSubService.GetClientAccessUriAsync(
        TimeSpan.FromMinutes(30),
        clientId,
        new[] { 
            $"webpubsub.joinLeaveGroup.{groupName}",
            $"webpubsub.sendToGroup.{groupName}"
            }
        );

    return new HttpResponseMessage(HttpStatusCode.OK)
    {
        Content = new StringContent(clientUri.ToString())
    };
}

See GitHub for the full implementation.

The Web PubSub connection string key mentioned in the Creating the cloud resource section is put in the App Settings of the Azure Function App, retrieved as an environment variable, and used when an instance of the WebPubSubServiceClient is created.

Authentication differences

The Ably specific function depends on the AblyRest client, which only requires the Ably API key. The API key has the configured capabilities to allow publishing, subscribing and presence management for the channel. This means that if several different access rights are required for various roles, multiple API keys need to be created.

The Web PubSub specific function requires more parameters to create a client token:

The connection string of the service.
The Hub name
The Group name*
The client ID*
The roles for leaving and joining the group*

These are required since a specific subprotocol is used for the client connection. See the *Creating a client-side connection section.

The Web PubSub connection string has all the rights to the service. When the client access token is generated, the group-specific access is defined.

Although the result is more or less the same (a client access token) the level of detail required for creating the connection is different.

Since the WebPubSubServiceClient requires the Hub name next to the connection string, I decided not to use dependency injection for the service client. Otherwise, I had to put the Hub name in an environment variable as well. I believe that a Hub name should be truly dynamic, so I prefer it not be present in configuration or back-end code.

Creating a client-side connection

The user (with a client device) need to establish a connection with the cloud service. The client-side code will call the CreateTokenRequest Azure Function shown earlier, that will return a client access token to establish the WebSocket-based connection.

Ably

Ably has a client SDK to manage connections and messaging, instead of using the native WebSockets API. An instance of the Ably.Realtime client is created that uses the CreateTokenRequest endpoint to obtain the client access token that contains the user ID.

const clientOptions = {
    authUrl: `/api/CreateTokenRequest/${user.id}`,
    echoMessages: false,
};
ably = new Ably.Realtime.Promise(clientOptions);

Once the ably client is connected, the channel can be retrieved:

channel = await ably.channels.get(channelName, {
    params: { rewind: "2m" },
});

Note that the rewind parameter is used to retrieve the last two minutes of messages. This is possible because messages are persisted by Ably.

Azure Web PubSub

Azure Web PubSub uses the WebSocket API directly by specifying the URL with the client access token, and a subprotocol:

let tokenResponse = await fetch(
    `/api/CreateTokenRequest/${hubName}/${groupName}/${user.id}`
);
let clientUrl = await tokenResponse.text();
webSocket = new WebSocket(clientUrl, "json.webpubsub.azure.v1");

See GitHub for the full implementation.

Client-side connection differences

For Ably, the JavaScript client library is used to create a WebSocket-based connection and interacting with the cloud service. The benefit of using this library over the native WebSocket API is that a lot of boilerplate WebSocket code and difficult to implement concepts, such as reliable connection management, and message ordering, are taken care of for you.

For Web PubSub, the json.webpubsub.azure.v1 WebSocket subprotocol is specified when creating the connection. This is required for doing pubsub without the need of using event handlers which push messages to an upstream server. The downside of using this subprotocol is that custom events can only be supported by using event handlers. In this application, I did not use any integrations/event handlers to reduce complexity.

Presence

When a user visits the web application and clicks the Connect button, they connect to the messaging service and their (randomly generated) client ID is added to a users collection in the client-side code. The total number of connected users (client devices, actually) is shown next to the button:

How do you find out which (or how many) clients are connected to the channel? This concept is called presence.

Ably

With Ably, presence is a built-in feature that is exposed via the client SDKs.

The following four actions are done when a user has established a connection to Ably:

Subscribe to presence enter messages.
Subscribe to presence leave messages.
Get the presence of the channel.
Enter their own presence.

Subscribing to enter and leave presence messages published by other clients is done via the channel.presence object:

channel.presence.subscribe("enter", (member) => {
    addUser(member.clientId, member.data.color);
});
channel.presence.subscribe("leave", (member) => {
    removeUser(member.clientId);
});

The entire channel presence can be retrieved as follows:

await channel.presence.get((err, members) => {
    members.forEach((member) => {
        if (member.data) {
            addUser(member.clientId, member.data.color);
        }
    });
});

Retrieving the total presence of a channel is very useful since you don't have to store the connected users yourself. As soon as a client has joined a channel, they can retrieve the presence and know which users are present in the same channel.

A client can announce their own presence to the channel as follows:

channel.presence.enter({
    color: user.strokeColor,
});

Note that you can submit a JSON payload when entering (or updating) presence information. This is ideal for storing client-specific data. In this case, the color of their pixel cursor.

See GitHub for the full implementation of user presence.

Azure Web PubSub

Although Web PubSub does have the Group concept and allows adding/remove users, it does not provide a way to retrieve user information from a Group. So, there is no presence awareness in Web PubSub.

Once a connection to the Web PubSub service has been established, these steps are performed:

Send a joinGroup message, so the user is part of this group, and can send and receive group messages.
Add user information to the users collection (to identify the user on the client-side).
Send a sendToGroup message to broadcast their user information to the rest of the group.

webSocket.send(
    JSON.stringify({
        type: "joinGroup",
        group: groupName,
    })
);
addUser(user.id, user.strokeColor);
webSocket.send(
    JSON.stringify({
        type: "sendToGroup",
        group: groupName,
        noEcho: true,
        data: {
            messageType: joinedMessage,
            clientId: user.id,
            color: user.strokeColor,
        }
    })
);

See GitHub for the full implementation.

However, one part is not yet accounted for. Say there are two clients, A and B, who are connecting in sequence (first A, then B) to the same Hub and Group. When B connects to the Hub, a sendToGroup message is published by B which is received by A to announce B has joined. But B has no idea that A is also connected, since B connected later to the Hub than A.

The only way for B to be aware of A is that A sends a sendToGroup message as well. The solution I chose was to always include the client ID and pixel cursor color when publishing the hoverPositionMessage (a user moves their mouse over the pixel canvas):

webSocket?.send(JSON.stringify({
    type: "sendToGroup",
    group: groupName,
    noEcho: true,
    data: {
        messageType: hoverPositionMessage,
        clientId: clientId,
        color: this.strokeColor,
        x: this.x,
        y: this.y,
    }
}));

See GitHub for the full implementation.

I don't really like this approach, since the payload gets a bit bloated with redundant information. Ideally, I'd only send x and y coordinates here.

Presence differences

The difference between Ably and Azure Web PubSub is significant when it comes to user presence. It would be great if Web PubSub would offer a way to list the users in a group. Currently, some workarounds are required to get the same functionality as is offered by Ably. On the other hand, the Group concept of Web PubSub has no equivalent in Ably. You could say that both Hubs and Groups map to Channels in Ably. So if you require multiple Groups, you can use multiple channels in Ably.

Publishing messages

The application publishes messages when:

The user's mouse hovers over the canvas.
The user clicks a pixel on the canvas.
The user enters the 'r' key to reset the canvas.
The user selects a color palette.

Scenarios 1 to 3 use client-side publishing. Scenario 4 uses server-side publishing (from the Azure Function). Scenario 4 could also have been implemented via client-side publishing, but I wanted to use the .NET SDK to see how it differs from JavaScript and what other options there are when using server-side code.

Client-side publishing

Let's look at the mouseClicked function as an example of client-side publishing.

Ably

For Ably, the publish method is used on the channel object. The method requires an event name and a payload.

async function mouseClicked() {
    if (mouseX >= 0 && mouseX <= resoX && mouseY >= 0 && mouseY <= resoY) {
        clickCell(mouseX, mouseY);
        await channel?.publish(clickPositionMessage, {
            x: mouseX,
            y: mouseY,
        });
    }
}

See GitHub for the full implementation.

Azure Web PubSub

For Web PubSub, the send method is used on the WebSocket object. The method takes a JSON string and requires a type, groupName, and a payload.

async function mouseClicked() {
    if (mouseX >= 0 && mouseX <= resoX && mouseY >= 0 && mouseY <= resoY) {
        clickCell(mouseX, mouseY);
        webSocket?.send(JSON.stringify({
            type: "sendToGroup",
            group: groupName,
            noEcho: true,
            data: {
                messageType: clickPositionMessage,
                x: mouseX,
                y: mouseY,
            }
        }));
    }
}

See GitHub for the full implementation.

To distinguish between messages, I added the messageType field to the payload. The noEcho argument is optional, but since I don't want to echo the message back to the user, it is set to true.

Client-side publishing differences

The Azure Web PubSub code is a bit more verbose since Groups are used. The usage of Groups is required though since the json.webpubsub.azure.v1 subprotocol is used because there was no need for me to send messages to an upstream server before sending them to the clients. Ideally, I want to use custom events using this subprotocol without the need of going through an upstream server. This is what Ably does by default by using the event name as the first argument.

The noEcho can be configured for each send method separately using Web PubSub. Although this is very flexible, I wonder how many use cases there are that require this flexibility. For Ably, the echoMessages option is set when creating the Ably.Realtime client and is applied across all publish methods.

Server-side publishing

The ChangeColorPalette Azure Function selects a color palette based on a palette ID in the route, and publishes a message to the cloud service.

Ably

For Ably, the publishing is done using the AblyRest client that is injected via the constructor and assigned to the _ablyClient parameter:

[FunctionName(nameof(ChangeColorPalette))]
public async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "ChangeColorPalette/{paletteId}")] HttpRequestMessage req,
    string paletteId,
    ILogger log)
{
    string[] colors;
    switch (paletteId)
    {
        // removed the switch cases to shorten this code snippet.
    }

    var channel = HttpUtility.ParseQueryString(req.RequestUri.Query)["channel"];
    if (channel != null)
    {
        await _ablyClient.Channels.Get(channel).PublishAsync(
            "color-palette",
            new {
                paletteId = paletteId,
                colors = colors,
            });
    }

    return new OkObjectResult(colors);
}

See GitHub for the full implementation.

A channel is obtained by name and the PublishAsync method on that channel is called that takes an event name (color-palette) and a payload containing the paletteId and the colors array.

Azure Web PubSub

For Web PubSub, the WebPubSub output binding is used:

[FunctionName(nameof(ChangeColorPalette))]
public async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "ChangeColorPalette/{groupId}/{paletteId}")] HttpRequestMessage req,
    [WebPubSub(Hub = "{query.hubName}")] IAsyncCollector<WebPubSubAction> actions,
    string groupId,
    string paletteId,
    ILogger log)
{
    string[] colors;
    switch (paletteId)
    {
        // removed the switch cases to shorten this code snippet.
    }

    var data = BinaryData.FromObjectAsJson(
        new {
            messageType = "color-palette",
            paletteId = paletteId,
            colors = colors,
        });
    var action = WebPubSubAction.CreateSendToGroupAction(groupId, data, WebPubSubDataType.Json);
    await actions.AddAsync(action);

    return new OkObjectResult(colors);
}

See GitHub for the full implementation.

In general, I really like input & output bindings in Azure Functions, since they offer a quick way to move data in and out of a function without writing much code in the function body. The WebPubSub binding however still requires a few lines of code since the payload needs to be formatted, a WebPubSubAction object has to be created, and this has to be added to the IAsyncCollector.

An alternative would be to use the WebPubSubServiceClient object with the SendToGroup method in the function body instead of the output binding. It won't be much different regarding the lines of code required.

Server-side publishing differences

On the server-side, the amount of code required to publish a message is similar between Ably and Azure Web PubSub. I expected it to be less code for Web PubSub when using an output binding, but this wasn't the case. When looking at the steps required to publish a message, I find the Ably API a bit more concise and readable.

Subscribing to messages

The clients are subscribing to the following messages:

hoverPositionMessage: When the mouse is moved over the canvas.
clickPositionMessage: When the mouse is clicked on the canvas.
changeColorPaletteMessage: When the color palette is changed.
resetMessage: When the canvas is reset.

Ably

For Ably, subscribing to specific messages looks like this:

channel.subscribe(hoverPositionMessage, (message) => {
    setUserPosition(message.clientId, message.data.x, message.data.y);
});
channel.subscribe(clickPositionMessage, (message) => {
    clickCell(message.data.x, message.data.y);
});
channel.subscribe(changeColorPaletteMessage, (message) => {
    handleChangeColorPalette(message.data.paletteId, message.data.colors);
});
channel.subscribe(resetMessage, () => {
    resetGrid();
});

See GitHub for the full implementation.

In addition, the client can subscribe to presence events, when a user joins or leaves a channel:

 channel.presence.subscribe("enter", (member) => {
    addUser(member.clientId, member.data.color);
});
channel.presence.subscribe("leave", (member) => {
    removeUser(member.clientId);
});

See GitHub for the full implementation.

Azure Web PubSub

For Azure Web PubSub, since it's using the native WebSocket API, the onmessage event is used, which captures all kinds of events. It up to the developer to filter the exact type and since I added a separate messageType field to the payload, that is used to identify the exact message.

webSocket.onmessage = (event) => {
    const message = JSON.parse(event.data);
    if (message.type === "message") {
        switch (message.data.messageType) {
            case hoverPositionMessage:
                setUserPosition(
                    message.data.clientId,
                    message.data.color,
                    message.data.x,
                    message.data.y
                );
                break;
            case clickPositionMessage:
                clickCell(message.data.x, message.data.y);
                break;
            case changeColorPaletteMessage:
                handleChangeColorPalette(
                    message.data.paletteId,
                    message.data.colors
                );
                break;
            case resetMessage:
                resetGrid();
                break;
            case joinedMessage:
                addUser(
                    message.data.clientId, 
                    message.data.color);
                break;
            default:
               break;
        }
    }
};

See GitHub for the full implementation.

Subscribing differences

The largest difference is the presence events, which are supported by Ably but not by Azure Web PubSub. Next to that, Ably supports event names that make it very convenient to subscribe to specific events. For Web PubSub, the lack of specific event subscriptions results in a large switch statement inside the onmessage handler. Azure Web PubSub does support custom events, but these have to be processed with event handlers and sent to an upstream server, which adds additional complexity.

Summary

Both Azure Web PubSub and Ably offer a similar pubsub feature set. Ably provides some additional features not offered by Web PubSub, such as presence, message history, and transport selection. I missed presence the most when creating the application with Web PubSub.

I found the Ably client-side API easier to develop with than the native WebSockets API. Using a higher level client SDK for realtime messaging removes a lot of complexity and makes the code more concise. I prefer writing less code and focusing on the (business) domain, so I'm happy with using client SDKs if they make my life easier.

Being able to publish named events and subscribe to them (client-side) without the need of handling them via an upstream server and custom event handlers is a big plus for me.

A potential negative aspect of using a 3rd party library could be the download size of the client app. If you need to keep that to a minimum, then that would be an argument to choose native WebSockets.

I haven't touched on reliable message delivery, message ordering, and default multi-region support. The Ably SDK takes care of this for you completely, and there's no need to manage ackIDs, connectionIds, and reconnectionTokens yourself.

I do admit I'm biased, since I have used Ably more than I have used the native WebSockets API. But look at the code snippets in this post and decide for yourself.

I encourage you to clone/fork the GitHub repository and run the collaborative pixel drawing application yourself (either using Ably or Web PubSub). Try to add some extra pubsub features to it and let me know what your experience is.

Combine realtime pub/sub messaging with Azure Functions & Durable Entities

Marc Duiker — Thu, 30 Jun 2022 13:13:00 +0000

In this post I'll explain how data is distributed in realtime using pub/sub over WebSockets in a serverless application running in Azure. The context I'll be using is a multiplayer Advanced Dungeons & Dragons (ADnD) style game that is turn-based with realtime state updates.

You'll learn:

How to use pub/sub in C# Azure Functions to publish messages.
How to use pub/sub in a JavaScript front-end to receive messages.
How to persist state in Azure Functions using Durable Entities.

TLDR: Play the live game, or look at the source code in the GitHub repo.

Distributing state in serverless applications is complex

Working with state in serverless applications and across many client devices is a difficult thing. First, serverless functions are usually stateless, so they can scale out easily without side effects, such as inconsistent state between the serverless instances. Secondly, synchronizing state across devices in a reliable and scalable way is a challenge to build yourself. Clients can temporarily lose connection, messages can get lost or be out of order.

This post focuses on using the right cloud services to manage the game logic and synchronization of data in a reliable and scalable way. Let's assume we have the following requirements:

Developers should be up & running quickly to produce a prototype.
Operational maintenance should be minimal.
Game logic should be running in the cloud and exposed via an HTTP API.
A small amount of game data should be persisted.
Game data provided by the backend should be distributed in realtime across all players.
The client devices should cope with temporary connection issues and should receive messages in order.

The tech stack

A good solution that fits the above requirements is to have a serverless application that is quick to build, low in maintenance, and affordable to get started with.

Player actions trigger HTTP-based Azure Functions that handle the game logic. Ably handles the distribution of data between the Functions and the clients.

These are the high-level components used for the game:

Azure Functions, a serverless compute offering in Azure. This is used to create the HTTP API that clients can interact with.
- Entity Functions, an extension of Azure Functions, used to persist small pieces of game & player state.
Ably, an edge messaging solution, that offers serverless pub/sub over WebSockets to distribute data in realtime.
VueJS, a well-known front-end framework.
Azure Static Web Apps, a hosting solution that serves the static files.

Diagram 1: Communication between player devices and the serverless application.

The game API

The API of the game exposes several HTTP endpoints which are implemented in C# (.NET 6) Azure Functions:

CreateQuest; triggered by the first player to start a new quest.
GetQuestExists; triggered by players who would like to join a quest to determine if they provided a valid quest ID.
AddPlayer; triggered by the player once they have selected their character and name.
ExecuteTurn; triggered by the player when they want to attack.
CreateTokenRequest; provides an authentication token and is triggered when a connection to Ably is made via the front-end.

All Azure Functions are just a couple of lines of code. The majority of the game logic is implemented in the GameEngine, GameState, and Player classes. All functions related to game interaction only call methods in the GameEngine class. The GameEngine class is responsible for the game flow, and updating the state of the game and player objects.

Diagram 2: Communication flow within the HTTP Azure Functions.

Creating a new quest

To illustrate how Azure Functions and the GameEngine, GameState, and Player classes work together, I'll show the CreateQuest functionality starting at the Azure Function, and ending with publishing messages using Ably.

CreateQuest function

The CreateQuest HTTP function is triggered when a player clicks the Start Quest button. A new quest ID is generated client-side and provided in the request.

public class CreateQuest
{
    // Only showing the class members relevant for this blog section.
    // For the full implementation see https://github.com/ably-labs/serverless-websockets-quest/blob/main/api/Functions/CreateQuest.cs

    [FunctionName(nameof(CreateQuest))]
    public async Task<IActionResult> Run(
        [HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = null)] HttpRequestMessage req,
        [DurableClient] IDurableClient durableClient,
        ILogger log)
    {
        if (req.Content != null)
        {
            var questId = await req.Content.ReadAsStringAsync();
            var channel = _realtime.Channels.Get(questId);
            var gameEngine = new GameEngine(durableClient, questId, channel);
            var gamePhase = await gameEngine.CreateQuestAsync();
            return new OkObjectResult(gamePhase);
        }
        else
        {
            return new BadRequestObjectResult("QuestId is required");
        }
    }
}

If the request is valid, this function will call the CreateQuestAsync() method in the GameEngine class.

GameEngine - CreateQuestAsync

The GameEngine is responsible for the majority of the game flow and orchestrates actions using the GameState and Player classes.

public class GameEngine
{
    // Only showing the class members relevant for this blog section.
    // For the full implementation see https://github.com/ably-labs/serverless-websockets-quest/blob/main/api/Models/GameEngine.cs

    public async Task<string> CreateQuestAsync()
    {
        var nextGamePhase = GamePhases.Character;
        await InitializeGameStateAsync(nextGamePhase);
        return nextGamePhase;
    }

    private async Task InitializeGameStateAsync(string phase)
    {
        var monsterEntityId = new EntityId(nameof(Player), Player.GetEntityId(_questId, CharacterClassDefinitions.Monster.Name));
        await _durableClient.SignalEntityAsync<IPlayer>(monsterEntityId, proxy => proxy.InitPlayer(
            new object[] {
                _questId,
                CharacterClassDefinitions.Monster.Name,
                CharacterClassDefinitions.Monster.CharacterClass,
                CharacterClassDefinitions.Monster.InitialHealth
            }));

        var gameStateEntityId = new EntityId(nameof(GameState), _questId);
        await _durableClient.SignalEntityAsync<IGameState>(gameStateEntityId, proxy => proxy.InitGameState(new[] { _questId, phase }));
        await _durableClient.SignalEntityAsync<IGameState>(gameStateEntityId, proxy => proxy.AddPlayerName(CharacterClassDefinitions.Monster.Name));
    }
}

The InitializeGameStateAsync method is responsible for:

Creating the monster, a Player (a non-player character, NPC).
Creating the initial GameState that contains the quest ID and the name of the game phase.
Adding the monster to the list of players in the GameState.

Stateful Entity Functions

The GameState and Player classes are so-called Entity Functions, functions that are stateful. Their state is persisted in an Azure Storage Account that is abstracted away. You can interact with entities in two ways:

Signaling (SignalEntityAsync), which involves one-way (fire and forget) communication.
Reading the state (ReadEntityStateAsync), which involves two-way communication.

For more information about Entity Functions, please see the Azure docs.

I chose Entity Functions since they're quick to get started with and ideal for storing small objects. Entity Functions require no additional Azure services, since a regular function app already comes with a storage account. Ideal for a demo like this.

There are downsides to Entity Functions though. First, entities prioritize durability over latency. This means that it's not the fastest way to store data. This is because signaling tasks are sent to a storage queue which is being polled at a certain (configurable) frequency. The default configuration also enforces batch processing of signaling tasks which, in this game context, is not desirable. I changed the maxQueuePollingInterval and maxEntityOperationBatchSize settings in the host.json file to have an acceptable latency and consistency.

{
    "version": "2.0",
    "extensions": {
        "durableTask": {
          ...
          "storageProvider" : {
            "maxQueuePollingInterval": "00:00:01"
          },
          "maxEntityOperationBatchSize": 1
        }
    },
    ...
}

Read the Azure docs to learn more about performance and scale related to Entity Functions.

Player entity function

The Player entity function is responsible for maintaining the state of a player in the game. The game has four players: the monster (NPC), and 3 real players. Each one has their own Player entity function.

[JsonObject(MemberSerialization.OptIn)]
public class Player : IPlayer
{
    // Only showing the class members relevant for this blog section.
    // For the full implementation see https://github.com/ably-labs/serverless-websockets-quest/blob/main/api/Models/Player.cs

    [JsonProperty("questId")]
    public string QuestId { get; set; }

    [JsonProperty("playerName")]
    public string PlayerName { get; set; }

    [JsonProperty("characterClass")]
    public string CharacterClass { get; set; }

    [JsonProperty("health")]
    public int Health { get; set; }

    public async Task InitPlayer(object[] playerFields)
    {
        QuestId = (string)playerFields[0];
        PlayerName = (string)playerFields[1];
        CharacterClass = (string)playerFields[2];
        Health = Convert.ToInt32(playerFields[3]);
        await _publisher.PublishAddPlayer(QuestId, PlayerName, CharacterClass, Health);
    }
}

Once a Player entity is initialized, a message will be published to an Ably channel. The players who have joined the quest are subscribed to this channel and will receive a message that a new player has joined.

Operations on Entity Functions are recommended to be implemented via interfaces to ensure type checking. There are however some restrictions on entity interfaces, as described in the Azure docs. One limitation is that interface methods must not have more than one parameter. Since I want to initialize a Player entity and set multiple parameters in one go instead of setting each one individually, I decided to provide an object array as a parameter. This then requires casting/converting the array elements to their correct type. Not ideal, but it works.

GameState entity function

The GameState entity function is responsible for maintaining the state of the game, such as the quest ID, the player names, and the game phase (start, character selection, play, end).

[JsonObject(MemberSerialization.OptIn)]
public class GameState : IGameState
{
    // Only showing the class members relevant for this blog section.
    // For the full implementation see https://github.com/ably-labs/serverless-websockets-quest/blob/main/api/Models/GameState.cs

    [JsonProperty("questId")]
    public string QuestId { get; set; }

    [JsonProperty("phase")]
    public string Phase { get; set; }

    public async Task InitGameState(string[] gameStateFields)
    {
        QuestId = gameStateFields[0];
        Phase = gameStateFields[1];
        await _publisher.PublishUpdatePhase(QuestId, Phase);
    }

    [JsonProperty("players")]
    public List<string> PlayerNames { get; set; }

    public async Task AddPlayerName(string playerName)
    {
        if (PlayerNames == null)
        {
            PlayerNames =  new List<string> { playerName };
        }
        else
        {
            PlayerNames.Add(playerName);
        }

        if (IsPartyComplete)
        {
            await UpdatePhase(GamePhases.Play);
            await Task.Delay(2000);
            await AttackByMonster();
        }
    }

    public async Task UpdatePhase(string phase)
    {
        Phase = phase;
        await _publisher.PublishUpdatePhase(QuestId, Phase);
    }

    private async Task AttackByMonster()
    {
        var playerAttacking = CharacterClassDefinitions.Monster.Name;
        var playerUnderAttack = GetRandomPlayerName();
        var damage = CharacterClassDefinitions.GetDamageFor(CharacterClassDefinitions.Monster.CharacterClass);
        await _publisher.PublishPlayerAttacking(QuestId, playerAttacking, playerUnderAttack, damage);
        await Task.Delay(1000);
        var playerEntityId = new EntityId(nameof(Player), Player.GetEntityId(QuestId, playerUnderAttack));
        Entity.Current.SignalEntity<IPlayer>(playerEntityId, proxy => proxy.ApplyDamage(damage));
        await Task.Delay(1000);
        var nextPlayerName = GetNextPlayerName(CharacterClassDefinitions.Monster.Name);
        await _publisher.PublishPlayerTurnAsync(QuestId, $"Next turn: {nextPlayerName}", nextPlayerName);
    }
}

The GameState also performs actions such as signaling Player entities and publishing messages, as can be seen in the AttackByMonster method.

Note that the AttackByMonster method contains two calls to Task.Delay(). This is to add a bit of delay between publishing the messages about the automated monster attack. Without the delay, the action would be much quicker compared with what real players do. Since this is a turn-based game, with realtime state updates, this seemed more natural to me.

Publishing messages

The final step of game logic functionality in the API is publishing messages to the players that have joined the quest. Since several classes need access to this functionality, I've wrapped it in a Publisher class for ease of use.

public class Publisher
{
    // Only showing the class members relevant for this blog section.
    // For the full implementation see https://github.com/ably-labs/serverless-websockets-quest/blob/main/api/Models/Publisher.cs

    public async Task PublishAddPlayer(string questId, string playerName, string characterClass, int health)
    {
        if (_ablyClient != null)
        {
            var channel = _ablyClient.Channels.Get(questId);
            await channel.PublishAsync(
                "add-player",
                    new
                    {
                        name = playerName,
                        characterClass = characterClass,
                        health = health
                    }
                );
        }
    }

    public async Task PublishUpdatePhase(string questId, string phase, bool? teamHasWon = null)
    {
        if (_ablyClient != null)
        {
            var channel = _ablyClient.Channels.Get(questId);
            await channel.PublishAsync(
                "update-phase",
                new
                {
                    phase = phase,
                    teamHasWon = teamHasWon
                }
            );
        }
    }
}

Publishing messages is the easiest part of the API. The _ablyClient in the code sample above is an instance of the Ably REST client and responsible for publishing messages to a channel. The REST client is used since code is running in a short-lived Azure Function and doesn't require a bidirectional WebSocket connection. The client retrieves the channel, the quest ID in this case, and PublishAsync is called that accepts an event name and a payload.

Receiving messages client-side

The client-side is subscribed to the messages published via the API using the realtime Ably client that is based on WebSockets. Based on the type of message received, the game progresses to the next phase, and local player state is updated. So, even though this is a turn-based game, updates in the API result in realtime communication with the players to update their local player state.

The clients require a connection to Ably to receive messages in realtime. The createRealtimeConnection function is called when players start a new quest or join a quest.

async createRealtimeConnection(clientId: string, questId: string) {
    if (!this.isConnected) {
        const realtimeClient = new Realtime.Promise({
            authUrl: `/api/CreateTokenRequest/${clientId}`,
            echoMessages: false,
        });
        this.realtimeClient = realtimeClient;
        realtimeClient.connection.on("connected", async (message: Types.ConnectionStateChange) => {
            this.isConnected = true;
            const messageText = `Ably connection status: ${realtimeClient.connection.state}`;
            this.writeMessage(messageText);
            await this.attachToChannel(questId);
        });

        realtimeClient.connection.on("disconnected", () => {
            this.isConnected = false;
            const messageText = `Ably connection status: ${realtimeClient.connection.state}`;
            this.writeMessage(messageText);
        });
    }
},
async attachToChannel(channelName: string) {
    const channelInstance = this.realtimeClient?.channels.get(
        channelName,
        {
            params: { rewind: "2m" },
        }
    );
    this.channelInstance = channelInstance;
    this.subscribeToMessages();
},

When a new instance of the Realtime object is created, the authUrl is set by calling the CreateTokenRequest endpoint in the API. This returns a JWT token that is used to authenticate with Ably. This approach prevents any API keys from being present in the front-end and potentially ending up in source control.

Once a connection is made, the client attaches to the channel (named after the questId) and subscribes to messages published by Ably.

As an example of how the front-end updates when a player attacks, let's have a look how the player-under-attack message is handled.

subscribeToMessages() {

    // Only showing the functions relevant for this blog section.
    // For the full implementation see https://github.com/ably-labs/serverless-websockets-quest/blob/main/src/stores/index.ts

    this.channelInstance?.subscribe(
        "player-under-attack",
        (message: Types.Message) => {
            this.handlePlayerIsUnderAttack(message);
        }
    );
},

handlePlayerIsUnderAttack(message: Types.Message) {
    if (this.teamHasWon !== undefined) return;
    const playerName: string = message.data.name;
    const characterClass: CharacterClass = message.data.characterClass as CharacterClass;
    const health: number = message.data.health;
    const damage: number = message.data.damage;
    const isDefeated: boolean = message.data.isDefeated;
    const messageText = `${playerName} received ${damage} damage`;
    this.writeMessage(messageText);
    this.updatePlayer(playerName, characterClass, health, damage, isDefeated, false, true);
},

updatePlayer(playerName: string, characterClass: CharacterClass, health: number, damage: number, isDefeated: boolean, isAvailable: boolean, isUnderAttack: boolean) {
    if (characterClass === CharacterClass.Fighter) {
        this.$patch({
            fighter: {
                name: playerName,
                health: health,
                damage: damage,
                isAvailable: isAvailable,
                isUnderAttack: isUnderAttack,
                isDefeated: isDefeated
            },
        });
        setTimeout(() => this.fighter.damage = 0, 3000);
    } else if (characterClass === CharacterClass.Ranger) {
        // Update ranger object
    } else if (characterClass === CharacterClass.Mage) {
        // Update mage object
    } else if (characterClass === CharacterClass.Monster) {
        // Update monster object
    }
},

The local Vue store (Pinia) contains definitions for each player. The store is updated with data coming from the messages pushed by Ably.

Vue components such as the PlayerUnit use the local data store to display the character information:

<!-- See https://github.com/ably-labs/serverless-websockets-quest/blob/main/src/components/PlayerUnit.vue for the full implementation. -->

<template>

    <div v-if="!props.isPlayerSelect">
        <p v-if="props.useHealth">
            <span class="health">{{ targetPlayer.health }} HP</span>
            <span class="damage" v-if="showDamage()">-{{ targetPlayer.damage }}</span>
        </p>
        <p class="stats" v-if="props.showStats">
            <span>Damage caused:</span>
            <span class="info">{{ targetPlayer.totalDamageApplied }}</span>
        </p>
        <img v-bind:class="{ isActive: isActive(), isDefeated: targetPlayer.isDefeated }" :alt="targetPlayer.characterClass" :src="getAsset()" />
        <figcaption>{{ targetPlayer.name }}</figcaption>
    </div>

    <div v-if="props.isPlayerSelect">
        <input type="radio" :id="targetPlayer.characterClass" name="character" :value="targetPlayer.characterClass" v-model="store.characterClass" @click="store.playerName=getName()" :disabled="isDisabled()" />
        <label :for="targetPlayer.characterClass">
            <img :alt="targetPlayer.characterClass" :src="getAsset()" />
            <figcaption>{{ getName() }}</figcaption>
        </label>
    </div>

</template>

Running locally

You require the following dependencies to run the solution locally:

.NET 6. The .NET runtime required for the C# Azure Functions.
Node 16. The JavaScript runtime required for the Vue front-end.
Azure Functions Core Tools. This is part of the Azure Functions extensions for VSCode that should be recommended for installation when this repo is opened in VSCode.
Azurite. This is a local storage emulator that is required for Entity Functions. When this repo is opened in VSCode, a message will appear to install this extension.
Azure Static Web Apps CLI. This is the command line interface to develop and deploy Azure Static Web Apps. Install this tool globally by running this command in the terminal: npm install -g @azure/static-web-apps-cli.
Sign up for a free Ably Account, create a new app, and copy the API key.

Steps

Clone or fork the Serverless WebSockets Quest GitHub repo.
Run npm install in the root folder.
Rename the api\local.settings.json.example file to api\local.settings.json.
Copy/paste the Ably API key in the ABLY_APIKEY field in the local.settings.json file.
Start Azurite (VSCode: CTRL+SHIFT+P -> Azurite: Start)

Run swa start in the root folder.

You'll see this error message, which is a warning really, you can ignore this when running the solution locally:

Function app contains non-HTTP triggered functions. Azure Static Web Apps managed functions only support HTTP functions. To use this function app with Static Web Apps, see 'Bring your own function app'.

The terminal will eventually output this message that indicates the emulated Static Web App is running:

Azure Static Web Apps emulator started at http://localhost:4280. Press CTRL+C to exit.

Open the browser and navigate to http://localhost:4280/

Deploying to the cloud

To have the entire solution running in the Azure cloud, you'll need an Azure account, and a GitHub account.

The free Azure Static Web Apps (SWA) tier comes with Managed Azure Functions. These are functions that are included in the Static Web App service. The downside of these managed functions is that only HTTP trigger functions are supported. Our game API uses Entity Functions as well. In order for Static Web Apps to work with our API we need to:

Deploy the API separately to a dedicated Function App.
Use the Standard (non-free) tier of Azure Static Web Apps.
Update the configuration of SWA to indicate that a dedicated Function App is being used.

Deployment steps

I've created a GitHub workflow to:
- Create the Azure resources.
- Build the C# API.
- Deploy the API to the Function App.

This approach uses the Azure Login action and requires the creation of an Azure Service Principal, as is explained in more detail in this README.

The SWA resource was created in the Azure portal using this quick start. This results in a generated GitHub workflow that will be included in the GitHub repository.
Follow these instructions to configure SWA to use a dedicated Function App.

Summary

Using serverless technology is a great way to get up and running in the cloud quickly and not worry about server maintenance. By combining serverless functions (Azure Functions) with serverless WebSockets (Ably) you can build a realtime solution that is cost-efficient and can scale automatically.

Although this demo is built around a game concept, other live and collaborative experiences are also a good fit for this tech stack. These include chat apps, location tracking apps, and realtime monitoring dashboards.

You've learned how to publish messages from the Azure Functions back-end and receive messages in the VueJS front-end to create a realtime experience for the players.

I encourage you to fork the repository available on GitHub and see if you can extend it (add a cleric who can heal other players?). Please don't hesitate to contact me on Twitter or join our Discord server in case you have any questions or suggestions related to this project.