ballerina/websub

Package Overview

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

  1. 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.

  2. 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.

  1. 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.

  1. The publisher notifies the hub of updates to the topic and the content to deliver is identified.

  2. The hub delivers the identified content to the subscribers of the topic.

Features

Subscriber

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.

  • If onSubscriptionVerification is 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.

  • If onSubscriptionValidationDenied is not specified, subscriber service will respond to the incoming request automatically.

  • If target is not specified the initial subscription will not happen on service startup.

  • If a secret is specified for the subscription, signature validation will be done for authenticated content distribution.

    1websub:ListenerConfiguration listenerConfigs = {
    2 secureSocket: {
    3 key: {
    4 certFile: "../resource/path/to/public.crt",
    5 keyFile: "../resource/path/to/private.key"
    6 }
    7 }
    8};
    9
    10listener websub:Listener sslEnabledListener = new(9095, listenerConfigs);
    11
    12@websub:SubscriberServiceConfig {
    13 target: ["<HUB_URL>", "<TOPIC_URL>"],
    14 leaseSeconds: 36000,
    15 secret: "<SECRET>"
    16}
    17service /subscriber on sslEnabledListener {
    18 remote function onSubscriptionValidationDenied(websub:SubscriptionDeniedError msg) returns websub:Acknowledgement? {
    19 // implement subscription validation denied logic here
    20 return websub:ACKNOWLEDGEMENT;
    21 }
    22
    23 remote function onSubscriptionVerification(websub:SubscriptionVerification msg)
    24 returns websub:SubscriptionVerificationSuccess|websub:SubscriptionVerificationError {
    25 // implement subscription intent verification logic here
    26 return websub:SUBSCRIPTION_VERIFICATION_SUCCESS;
    27 }
    28
    29 remote function onEventNotification(websub:ContentDistributionMessage event)
    30 returns websub:Acknowledgement|websub:SubscriptionDeletedError? {
    31 // implement on event notification logic here
    32 return websub:ACKNOWLEDGEMENT;
    33 }
    34}

Listeners

[1]

Listener

Represents a Subscriber Service listener endpoint.

Clients

[2]

DiscoveryService

Represents resource-discovery service which identify the hub and topic from resource-URL.

SubscriptionClient

The HTTP based client for WebSub subscription and unsubscription.

Object Types

[1]

SubscriberService

The WebSub service type

Records

[8]

Acknowledgement

Record representing the subscription-denial / content-distribution acknowledgement

ContentDistributionMessage

Record representing the content-distribution request.

ListenerConfiguration

Provides a set of configurations for configure the underlying HTTP listener of the WebSub listener.

SubscriberServiceConfiguration

Configuration for a WebSubSubscriber service.

SubscriptionChangeRequest

Record representing a WebSub subscription change request-body.

SubscriptionChangeResponse

Record representing subscription/unsubscription details if a subscription/unsubscription request is successful.

SubscriptionVerification

Record representing the subscription / unsubscription intent verification request-body.

SubscriptionVerificationSuccess

Record representing the subscription / unsubscription intent verification success.

Annotations

[1]

SubscriberServiceConfig

WebSub Subscriber Configuration for the service, indicating subscription related parameters.

Errors

[1]

Error

Represents a webSub distinct error.