ballerina/websub Ballerina library
This package contains an implementation of the W3C WebSub recommendation, which facilitates a push-based content delivery/notification mechanism between publishers and subscribers.
This implementation supports introducing WebSub Subscriber, A party interested in receiving update notifications for particular topics.
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 updates of the topic.
The subscriber sends a subscription request to one or more discovered hub(s) specifying the discovered topic along with other subscription parameters such as:
- The callback URL to which 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 authenticated content distribution.
The hub sends an intent verification request to the specified callback URL. If the response indicates 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 updates to the topic and the content to deliver is identified.
The hub delivers the identified content to the subscribers of the topic.
This package allows introducing a WebSub Subscriber Service with
onSubscriptionVerification, which accepts HTTP GET requests for intent verification,
onSubscriptionValidationDenied which accepts subscription denied response from hub and
onEventNotification, which accepts HTTP POST requests for notifications. The WebSub Subscriber Service provides the following capabilities:
When the service is started a subscription request is sent for a hub/topic combination, either specified as annotations or discovered based on the resource URL specified as an annotation.
onSubscriptionVerificationis not specified, intent verification will be done automatically against the topic specified as an annotation or discovered based on the resource URL specified as an annotation.
onSubscriptionValidationDeniedis not specified, subscriber service will respond to the incoming request automatically.
targetis not specified the initial subscription will not happen on service startup.
secretis specified for the subscription, signature validation will be done for authenticated content distribution.