webpubsub-apollo-experimental

Introduction

Microsoft Azure Web PubSub is a real-time messaging cloud service.

In GraphQL, subscriptions are long-lasting GraphQL read operations that can update their result whenever a particular server-side event occurs. And it is usually implemented with WebSocket protocol.

This package helps developers use Microsoft Azure WebPub service to avoid server-side maintenance of WebSocket connections between users clients and GraphQL server caused by subscriptions query from clients.



Let's show how to apply the package into the subscription sample provided by Apollo GraphQL.

Get the subscription sample

> [!NOTE]
>
> Please Note that this document is based on sample commit 50808f11c5, the latest version as of the time of writing the document.

``batch
git clone https://github.com/apollographql/docs-examples
cd docs-examples
git checkout 50808f11c5cfeaf02
cd apollo-server/v3/subscriptions
yarn install
`



Add the webpubsub-apollo-subscription package



Since the original sample uses yarn, to keep consistency, we use yarn to add the package.

`batch
yarn add webpubsub-apollo-subscription
`



Update index.js to use the package



1. import WebPubSubServerAdapter:

`javascript
const { WebPubSubServerAdapter } = require("webpubsub-apollo-subscription");
`

2. Update SubscriptionServer.create to use a WebPubSubServerAdapter instance
Note that we read the connection string from environment. Connection string is used to connect to Azure Web PubSub and we will get the value in later steps.

`javascript
const serverAdapter = new WebPubSubServerAdapter(
{
connectionString: process.env.WebPubSubConnectionString,
hub: "graphql_subscription",
path: "/graphql_subscription",
},
app
);
SubscriptionServer.create({ schema, execute, subscribe }, serverAdapter);
`

3. Also print out subscription endpoint and event handler endpoint
Add the logs after httpServer starts. These endpoints will be used in later setup.

`javascript
serverAdapter.getSubscriptionPath().then((v) => {
console.log(🚀 Subscription endpoint ready at ${v});
console.log(
🚀 Event handler listens at http://localhost:${PORT}${serverAdapter.path}
);
});
`

The complete code change can be found here.

Setup the Azure Web PubSub resource and configurations

$3

Follow the instruction to create an Azure Web PubSub service.

Get the ConnectionString of the service for later use:

`azurecli
az webpubsub key show --name "" --resource-group "myResourceGroup" --query primaryConnectionString
`

Copy the fetched ConnectionString and it will be used later in this article as the value of .

$3

Run the below command with replaced by the value fetched in the above step:

`cmd
SET WebPubSubConnectionString=
yarn start
`

The console log shows the exposed endpoints:

`
🚀 Query endpoint ready at http://localhost:4000/graphql
🚀 Subscription endpoint ready at wss://.webpubsub.azure.com/client/hubs/graphql_subscription
🚀 Event handler listens at http://localhost:4000/graphql_subscription/
`

The console log shows that the exposed endpoint for Azure Web PubSub event handlers is http://localhost:4000/graphql_subscription/. Let's expose this local endpoint to public so that the Azure Web PubSub can redirect traffic to your localhost.

$3

`
ngrok http 4000
`

Then you'll get a forwarding endpoint http://.ngrok.io like http://e27c-167-220-255-102.ngrok.io

$3

Since GraphQL has its own Authentication logic, graphql_subscription hub can allow anonymous connect and delegate all the event handling to the upstream. Setting the event handler through Azure CLI with below command:

`azurecli
az webpubsub hub create --hub-name graphql_subscription --name "" --resource-group "myResourceGroup" --allow-anonymous --event-handler url-template=http://.ngrok.io/{hub}/{event} user-event-pattern=* system-event=connect system-event=disconnected system-event=connected
`

$3

1. Open http://localhost:4000/graphql and click Query your server, click the top settings gear, and update the subscription URL to the Web PubSub endpoint wss://.webpubsub.azure.com/client/hubs/graphql_subscription.

!Set the subscription URL to use the Web PubSub endpoint.

2. Update the operations to query the incremental number and run:

`graphql
subscription IncrementingNumber {
numberIncremented
}
``

You can see that the subscription updates are consistently pushed to the GraphQL clients through the WebSocket connection.

!Run the subscription operation to use the Web PubSub endpoint.

Check the internals of the package here:
* Use Web PubSub to host WebSocket connections for GraphQL subscription