ballerina/websub Ballerina library
This module provides APIs for a WebSub Subscriber Service.
WebSub is a common mechanism for communication between publishers of any kind of Web content and their subscribers, based on HTTP webhooks. Subscription requests are relayed through hubs, which validate and verify the request. Hubs then distribute new and updated content to subscribers when it becomes available. WebSub was previously known as PubSubHubbub.
WebSub Subscriber is an implementation that discovers the
topic URL of a given
resource URL, subscribes to updates at the hub, and accepts content distribution requests from the
Basic flow with WebSub
The subscriber discovers (from the publisher) the topic it needs to subscribe to and the hub(s) that deliver notifications on the updates of the topic.
The subscriber sends a subscription request to one or more discovered hub(s) specifying the discovered topic along with the other subscription parameters such as:
- The callback URL to which the content is expected to be delivered.
- (Optional) The lease period (in seconds) the subscriber wants the subscription to stay active.
- (Optional) A secret to use for the authenticated content distribution.
The hub sends an intent verification request to the specified callback URL. If the response indicates the verification (by echoing a challenge specified in the request) by the subscriber, the subscription is added for the topic at the hub.
The publisher notifies the hub of the updates to the topic and the content to deliver is identified.
The hub delivers the identified content to the subscribers of the topic.
Subscribe to a
- The WebSub Subscriber provides the mechanism to subscribe in a
hubto a given
- The WebSub Subscriber also provides the mechanism to discover the
topic URLresources dynamically via the provided
resource URLand initiates the subscription.
Dynamic URI generation
- The service path for a WebSub Subscriber is optional. The WebSub Subscriber service has the capability to generate the service path dynamically.
- ngrok is a TCP Tunneling software, which is used to expose services running locally in the public network.
- If you want to run the subscriber service in your local machine, you could use ngrok to expose it to the public network.
- First, download and install ngrok.
- Run the following command to expose the local port
9090to the public network via
HTTPS. For information, see the ngrok documentation).
- Extract the public URL provided by ngrok and provide it as the callback URL for the subscriber service.
Unsubscribe from the
- The WebSub Subscriber has the capability to initiate unsubscription flow on Subscriber termination.
Return errors from remote methods
- Remote functions in
- For each remote method
errorreturn has a different meaning. Following table depicts the meaning inferred from
errorreturned from all available remote methods.
|Method||Interpreted meaning for Error Return|
|onSubscriptionVerification||Subscription verification failure|
|onUnsubscriptionVerification||Unsubscription verification failure|