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.
Firstly, 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.
Secondly, this package provides a replacement for PubSub
using Azure Web PubSub service. PubSub is an in-memory event-publishing system provided by Apollo server.
-
Create a Microsoft Azure Web PubSub resource instance. Details are Here.
-
Use
ngrok
to expose our local endpoint to the public Internet
Notice: make sure the region of your Azure Web PubSub resource and the region of ngrok tunnel server are the same. For Example, if your Azure Web PubSub instance is located in Asia Pacific (ap) region , run your ngrok with parameter --region=ap
as below. Ngrok documents shows more location settings.
ngrok http --region=ap 8888
Then you'll get a forwarding endpoint http://{ngrok-id}.ngrok.io
like http://1bff94a2f246.ap.ngrok.io
- Set
Event Handler
in Azure Web PubSub service. Go to Azure portal -> Find your Web PubSub resource -> Settings. Add two new hub settings as below. Replace the {ngrok-id} to yours.
Hub Name: graphql_main | ||
---|---|---|
URL Template | User Event Pattern | System Events |
http://{ngrok-id}.ngrok.io/wps-services/main | * | connect,connected,disconnected |
Hub Name: graphql_pubsub | ||
---|---|---|
URL Template | User Event Pattern | System Events |
http://{ngrok-id}.ngrok.io/wps-services/pubsub | * | No system Events is selected |
- Clone this repository and install required package
git clone https://github.com/xingsy97/webpubsub-graphql-subscribe
cd webpubsub-graphql-subscribe
npm install
-
replace
<web-pubsub-connection-string>
indemos/demo.js
Line 7 to your own Azure Web PubSub connection string -
Compile && Run the demo
npm run compile && npm run demo
- Open your web browser like Google Chrome, visit
http://localhost:4000/graphql
. Copy the following GraphQL query to the left panel.
subscription sampleSubscription {
numberIncremented
}
Then click the play button and watch the right pannel.
src/demos/demo-without-webpubsub.ts
is a sample show Subscriptions in Apollo Server without Azure WebPub service. Follow these instructions, we will apply Web Pubsub to this sample.
- define a variable to store Web PubSub connection string
const webpubsub_conn_string = "<webpubsub-connection-string>"
- replace original in-memory event system
PubSub
to ourWpsPubSub
based on Web PubSub.
Old:
const pubsub = new PubSub();
New:
const pubsub = new WpsPubSub(webpubsub_conn_string);
- use
create_webpubsub_subscribe_server
exported by our package to create a subscription server
Old:
SubscriptionServer.create(
{ schema, execute, subscribe },
{ server: httpServer, path: apolloServer.graphqlPath }
);
New:
await create_webpubsub_subscribe_server(apolloServer, schema, pubsub, webpubsub_conn_string);
Now your subscription server inside Apollo Server is based on Azure Web PubSub service. Refer to src/demos/demo.ts
for complete source code.
-
class
WpsWebSocketServer
- Original GraphQL subscriptions implementation starts up a WebSocket server which listens to clients and maintains WebSocket connections in server-side.
- This class replaces original
WebSocket.Server
and communicate between the server and WebPub service using HTTP protocol. - And clients use WebSocket communicates with WebPub service rather than directly communicate with our server by WebSocket.
-
class
WpsPubSub
- It implements the
PubSubEngine
Interface from thegraphql-subscriptions
package using Azure Web PubSub service. - It replaces the original in-memory event system
PubSub
and allows you to connect your subscriptions manager to an Azure Web PubSub service to support multiple subscription manager instances.
- It implements the