Standard library

websubhub

ballerina/websubhub

Overview

This module provides APIs for WebSub Hub service and WebSub Publisher client.

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 requests. Hubs then distribute new and updated content to subscribers when it becomes available. WebSub was previously known as PubSubHubbub.

WebSub Hub is an implementation that handles subscription requests and distributes the content to subscribers when the corresponding topic URL has been updated.

WebSub Publisher is an implementation that advertises a topic and hub URL on one or more resource URLs.

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 the 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 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 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 the updates to the topic and the content to deliver is identified.

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

Using Hub Client

  • WebSub HubClient can be used to distribute the published content among the subscriber base. The current implementation is based on

a ballerina HTTP Client.

1    client class HubClient {
2        remote function notifyContentDistribution(websubhub:ContentDistributionMessage msg) 
3                returns ContentDistributionSuccess | SubscriptionDeletedError | error?
4    }
  • The following is a sample 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    }

Using Publisher Client

  • The PublisherClient APIs are defined by Ballerina and it has no connection with the WebSub specification. As mentioned earlier, even though the

WebSub specification extensively discusses the relationship between the subscriber and hub, it does not discuss much the relationship between the publisher and hub.

  • The following is a sample 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                });

Returning Errors from Remote Methods

  • Remote functions in websubhub:Service can return error type.
1service /websubhub on new websubhub:Listener(9090) {
2
3    isolated remote function onRegisterTopic(websubhub:TopicRegistration message)
4                                returns websubhub:TopicRegistrationSuccess|websubhub:TopicRegistrationError|error {
5        boolean validationSuccessfull = check validateRegistration(message);
6        if (validationSuccessfull) {
7            websubhub:TOPIC_REGISTRATION_SUCCESS;
8        } else {
9            return websubhub:TOPIC_REGISTRATION_ERROR;
10        }
11    }
12
13    // implement other remote methods
14}
15
16function validateRegistration(websubhub:TopicRegistration message) returns boolean|error {
17   // implement validation
18}
  • For each remote method error return has a different meaning. Following table depicts the meaning inferred from error returned from all available remote methods.
Method Interpreted meaning for Error Return
onRegisterTopic Topic registration failure
onDeregisterTopic Topic de-registration failure
onUpdateMessage Update message error
onSubscription Subscription internal server error
onSubscriptionValidation Subscription validation failure
onSubscriptionIntentVerified Subscription intent verification failure
onUnsubscription Unsubscription internal server error
onUnsubscriptionValidation Unsubscription validation failure
onUnsubscriptionIntentVerified Unsubscription intent verification failure

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

[19]

Acknowledgement

Record to represent the 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.

ServiceConfiguration

Configuration for a WebSub Hub service.

Subscription

Record to represent the subscription request body.

SubscriptionAccepted

Record to represent the subscription accepted by the hub.

SubscriptionPermanentRedirect

Record to represent the permanent subscription redirects.

SubscriptionTemporaryRedirect

Record to represent temporary subscription redirects.

TopicDeregistration

Record to represent the topic-deregistration request body.

TopicDeregistrationSuccess

Record to represent the successful topic deregistration.

TopicRegistration

Record to represent the topic-registration request body.

TopicRegistrationSuccess

Record to represent the successful topic registration.

Unsubscription

Record to represent the unsubscription request body.

UnsubscriptionAccepted

Record to represent the unsubscription acceptance.

UpdateMessage

Record to represent the content update message.

VerifiedSubscription

Record to represent the completed subscription.

VerifiedUnsubscription

Record to represent a completed unsubscription.

Constants

[3]

COMPRESSION_ALWAYS

Always set accept-encoding/content-encoding in outbound request/response.

COMPRESSION_AUTO

When service behaves as a HTTP gateway inbound request/response accept-encoding option is set as the outbound request/response accept-encoding/content-encoding option.

COMPRESSION_NEVER

Never set accept-encoding/content-encoding header in outbound request/response.

Enums

[1]

MessageType

Enum to differentiate the type of the content-update message.

Annotations

[1]

ServiceConfig

WebSub Hub Configuration for the service.

Types

[1]

Compression

Options to compress using Gzip or deflate.

Variables

[14]

TOPIC_REGISTRATION_SUCCESS

Common responses to be used in the hub implementation.

TOPIC_REGISTRATION_ERROR
TOPIC_DEREGISTRATION_SUCCESS
TOPIC_DEREGISTRATION_ERROR
ACKNOWLEDGEMENT
UPDATE_MESSAGE_ERROR
SUBSCRIPTION_ACCEPTED
BAD_SUBSCRIPTION_ERROR
INTERNAL_SUBSCRIPTION_ERROR
SUBSCRIPTION_DENIED_ERROR
UNSUBSCRIPTION_ACCEPTED
BAD_UNSUBSCRIPTION_ERROR
INTERNAL_UNSUBSCRIPTION_ERROR
UNSUBSCRIPTION_DENIED_ERROR

Errors

[13]

BadSubscriptionError

Error type representing the errors in the subscription request.

BadUnsubscriptionError

Error type representing the errors in the unsubscription request.

ContentDeliveryError

Error type representing the internal errors in the content distribution.

Error

Represents a websubhub distinct error.

InternalSubscriptionError

Error type representing the internal errors in the subscription action.

InternalUnsubscriptionError

Error type representing the internal errors in the unsubscription action.

ServiceExecutionError

Represents a websubhub service execution error.

SubscriptionDeletedError

Error type representing the subscriber ending the subscription by sending HTTP 410 for the content delivery response.

SubscriptionDeniedError

Error type representing the validation errors in the subscription request body.

TopicDeregistrationError

Error type representing the errors in the topic unregistration action.

TopicRegistrationError

Error type representing the errors in the topic registration action.

UnsubscriptionDeniedError

Error type representing the validation errors in the unsubscription request body.

UpdateMessageError

Error type representing the errors in the content update request.