ballerina/websubhub

Package Overview

This package contains an API specification to implement W3C WebSub Hub which facilitates a push-based content delivery / notification mechanism.

This package contains following components :

  1. API Specification of W3C WebSub Hub specification.

  2. HTTP based Hub Listener implementation.

  3. HTTP based implementation of Hub Client which is responsible for delivering content to subscribers.

  4. HTTP based implementation of W3C WebSub Publisher specification.

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

WebSub Hub Specification

One of the key features of this package is the ballerina specific API abstraction for WebSub Hub specification.

According to the W3C WebSub specification Hub has following responsibilities.

  • Register / Deregister topics advertised by the publishers.
  • Subscribe / Unsubscribe subscribers to advertised topics.
  • Verify the valid subscriptions.
  • Distribute published content to the subscriber base of a topic.

In the API specification for WebSub Hub, package provides following abstractions to be implemented.

  • Publisher Interactions
1 remote function onRegisterTopic(websubhub:TopicRegistration msg)
2 returns websubhub:TopicRegistrationSuccess | websubhub:TopicRegistrationError;
3
4 remote function onDeregisterTopic(websubhub:TopicDeregistration msg)
5 returns websubhub:TopicDeregistrationSuccess | websubhub:TopicDeregistrationError;
6
7 remote function onUpdateMessage(websubhub:UpdateMessage msg)
8 returns websubhub:Acknowledgement | websubhub:UpdateMessageError;
  • Subscriber Interactions
1 remote function onSubscription(websubhub:Subscription msg)
2 returns websubhub:SubscriptionAccepted
3 |websubhub:SubscriptionPermanentRedirect
4 |websubhub:SubscriptionTemporaryRedirect
5 |websubhub:BadSubscriptionError
6 |websubhub:InternalSubscriptionError;
7
8 remote function onSubscriptionValidation(websubhub:Subscription msg)
9 returns websubhub:SubscriptionDeniedError?;
10
11 remote function onSubscriptionIntentVerified(websubhub:VerifiedSubscription msg);
12
13 remote function onUnsubscription(websubhub:Unsubscription msg)
14 returns websubhub:UnsubscriptionAccepted
15 |websubhub:BadUnsubscriptionError
16 |websubhub:InternalUnsubscriptionError;
17
18 remote function onUnsubscriptionIntenVerified(websubhub:VerifiedUnsubscription msg);

Since WebSub Specification is not thorough enough with regard to the relationship between the Publisher and Hub;

  • Below methods are strictly websub compliant

    • onSubscription
    • onSubscriptionIntentVerified
    • onUnsubscritpion
    • onUnsubscriptionIntenVerified
  • Below methods are not strictly websub compliant

    • onRegisterTopic
    • onDeregisterTopic
    • onUpdateMessage

Hub Listener

HubListener is essentially a wrapper for ballerina HTTP Listener. Following is a sample of the hub-listener.

  • websubhub:Listener using http:Listener.
1 listener websubhub:Listener hub = new(new http:Listener(9091));
  • websubhub:Listener with port number.
1 listener websubhub:Listener hub = new(9090);

Hub Client

WebSub HubClient can be used to distribute the published content among subscriber base. Current implementation is based on ballerina HTTP Client.

1 client class HubClient {
2 remote function notifyContentDistribution(websubhub:ContentDistributionMessage msg)
3 returns ContentDistributionSuccess | SubscriptionDeletedError | error?
4 }

Following is a sample of WebSub HubClient.

1 type HubService service object {
2 remote function onSubscriptionIntentVerified(websubhub:Subscription msg) {
3
4 // you can pass client config if you want
5 // say maybe retry config
6 websub:HubClient hubclient = new(msg);
7 check start notifySubscriber(hubclient);
8 }
9
10 function notifySubscriber(websubhub:HubClient hubclient) returns error? {
11 while (true) {
12 // fetch the message from MB
13 check hubclient->notifyContentDistribution({
14 content: "This is sample content delivery"
15 });
16 }
17 }
18 }

WebSub Publisher Client

PublisherClient APIs are defined by the Ballerina standard library team and it has nothing to do with websub specification. As mentioned earlier, Even though the websub specification extensively discusses the relationship between the subscriber and hub, it does not really discuss much about the relationship between the publisher and hub.

Following is a sample of WebSub Publisher Client.

1 websubhub:PublisherClient publisherClient = new ("http://localhost:9191/websub/hub");
2
3 check publisherClient->registerTopic("http://websubpubtopic.com");
4
5 var publishResponse = publisherClient->publishUpdate(
6 "http://websubpubtopic.com",
7 {
8 "action": "publish",
9 "mode": "remote-hub"
10 });

Listeners

[1]

Listener

Represents a Service listener endpoint.

Clients

[2]

HubClient

HTTP Based client for WebSub content publishing to subscribers

PublisherClient

The HTTP based client for WebSub topic registration and deregistration, and notifying the hub of new updates.

Classes

[3]

StatusOK

Response status OK

StatusPermanentRedirect

Response status Permanent Redirect

StatusTemporaryRedirect

Response status Temporary Redirect

Object Types

[1]

Service

Records

[18]

Acknowledgement

Record to represent acknowledgement of content updated by the publisher

ClientConfiguration

Record to represent client configuration for HubClient / PublisherClient

ContentDistributionMessage

Record to represent a WebSub content delivery.

ContentDistributionSuccess

Record to represent the successful WebSub content delivery

ListenerConfiguration

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

Subscription

Record to represent subscription request body

SubscriptionAccepted

Record to represent accepted subscription by the `hub`

SubscriptionPermanentRedirect

Record to represent permanent subscription redirects

SubscriptionTemporaryRedirect

Record to represent temporary subscription redirects

TopicDeregistration

Record to represent Topic-Deregistration request body

TopicDeregistrationSuccess

Record to represent Topic Deregistration Success

TopicRegistration

Record to represent Topic-Registration request body

TopicRegistrationSuccess

Record to represent Topic Registration success

Unsubscription

Record to represent the unsubscription request body

UnsubscriptionAccepted

Record to represent unsubscription acceptance

UpdateMessage

Record to represent content-update message

VerifiedSubscription

Record to represent completed subscription

VerifiedUnsubscription

Record to represent completed unsubscription

Enums

[1]

MessageType

Enum to differenciate the type of content-update message

Errors

[1]

Error

Represents a websubhub distinct error