Specification: Ballerina WebSubHub Library

Owners: @shafreenAnfar @chamil321 @ayeshLK
Reviewers: @shafreenAnfar
Created: 2021/11/23
Updated: 2022/02/17
Edition: Swan Lake

Introduction

This is the specification for the WebSubHub standard library of Ballerina language, which provides WebSub compliant hub and publisher related functionalities.

The WebSubHub library specification has evolved and may continue to evolve in the future. The released versions of the specification can be found under the relevant Github tag.

If you have any feedback or suggestions about the library, start a discussion via a GitHub issue or in the Slack channel. Based on the outcome of the discussion, the specification and implementation can be updated. Community feedback is always welcome. Any accepted proposal which affects the specification is stored under /docs/proposals. Proposals under discussion can be found with the label type/proposal in Github.

The conforming implementation of the specification is released and included in the distribution. Any deviation from the specification is considered a bug.

Contents

  1. Overview
  2. Hub
  3. Publisher Client
  4. Common Client Configuration

1. Overview

WebSub is a real-time content delivery protocol over HTTP(S) and it is a specification which evolved from PubSubHubbub.

WebSub specification describes three main roles:

  • Publisher: Advertises a topic and hub URL on one or more resource URLs.
  • Subscriber: Discovers the hub and topic URL given a resource URL, subscribes to updates at the hub, and accepts content distribution requests from the hub.
  • Hub: Handles subscription requests and distributes the content to subscribers when the corresponding topic URL has been updated.

WebSubHub is a library which is derived from the WebSub specification which could be used by developers to implement WebSub compliant hub services and publisher clients. Since WebSub specification has limited details on the relationship between publisher and hub, the Ballerina standard library team has made minor improvements to the original protocol to provide a seamless developer experience.

2. Hub

WebSub hub is the exchange point for publisher and subscriber.

It has the following responsibilities:

  • Handles/manages WebSub topics.
  • Handles/manages WebSub subscriptions.
  • Handles WebSub content distribution.

The hub is designed in the form of listener and service.

  • websubhub:Listener: A listener end-point to which websubhub:Service could be attached.
  • websubhub:Service: An API service, which receives WebSub events.

In addition to websubhub:Listener and websubhub:Service, websubhub:HubClient is available which could be used to notify content updates to the subscribers.

2.1. Listener

The websubhub:Listener opens the given port and attaches the provided websubhub:Service object to the given service-path. websubhub:Listener can be initialized either by providing a port with listener configurations or by providing an http:Listener.

2.1.1. Configuration

When initializing a websubhub:Listener, following configurations could be provided.

For more details on the available configurations please refer http:ListenerConfiguration.

2.1.2. Initialization

The websubhub:Listener could be initialized by providing either a port with websubhub:ListenerConfiguration or by providing an http:Listener.

2.1.3. Methods

Following APIs should be available in the websubhub:Listener to dynamically attach websubhub:Service objects to it.

Following APIs should be available in the websubhub:Listener to dynamically detach websubhub:Service objects from it.

Following APIs should be available to dynamically start the websubhub:Listener.

Following APIs should be available to dynamically stop the websubhub:Listener.

2.2. Service

websubhub:Service is responsible for handling the received events. Underlying http:Service will receive the original request, and then it will trigger the WebSubHub dispatcher which will invoke the respective remote method with the event details.

Following is the type-definition for websubhub:Service.

2.2.1. Methods

2.2.1.1. onRegisterTopic

This remote method is invoked when the publisher sends a request to register a topic to the hub.

2.2.1.2. onDeregisterTopic

This remote method is invoked when the publisher sends a request to remove a topic from the hub.

2.2.1.3. onEventMessage

This remote method is invoked when the publisher sends a request to notify the hub about content update for a topic.

2.2.1.4. onSubscription

This remote method is invoked when the subscriber sends a request to subscribe for a topic in the hub. (This is an optional remote method.)

2.2.1.5. onSubscriptionValidation

This remote method is invoked when subscription request from the subscriber is accepted from the hub. hub could enforce additional validation for the subscription request when this method is invoked. If the validations are failed the hub could deny the subscription request by responding with websubhub:SubscriptionDeniedError. (This is an optional remote method.)

2.2.1.6. onSubscriptionIntentVerified

This remote method is invoked after the hub verifies the subscription request.

2.2.1.7. onUnsubscritpion

This remote method is invoked when the subscriber sends a request to unsubscribe from a topic in the hub. (This is an optional remote method.)

2.2.1.8. onUnsubscriptionValidation

This remote method is invoked when unsubscription request from the subscriber is accepted from the hub. hub could enforce additional validation for the unsubscription request when this method is invoked. If the validations are failed the hub could deny the unsubscription request by responding with websubhub:UnsubscriptionDeniedError. (This is an optional remote method.)

2.2.1.9. onUnsubscriptionIntenVerified

This remote method is invoked after the hub verifies the unsubscription request.

While the below remote methods are strictly WebSub compliant,

  • onSubscription
  • onSubscriptionValidation
  • onSubscriptionIntentVerified
  • onUnsubscritpion
  • onUnsubscriptionValidation
  • onUnsubscriptionIntenVerified

The below remote functions are not,

  • onEventMessage
  • onRegisterTopic
  • onUnregisterTopic

This is due to the limited information in the WebSub specification on the relationship between the publisher and the hub.

In the event of a bad request from the publisher or the subscriber, the WebSubHub dispatcher will automatically send back the appropriate response to the client.

2.2.2. Annotation

Apart from the listener level configurations a hub will require few additional configurations. Hence, there should be websubhub:ServiceConfig a service-level-annotation for websubhub:Service which contains websubhub:ServiceConfiguration record.

2.3. Hub Client

In accordance with the WebSub specification, WebSubHub package has provided support for websubhub:HubClient which could be used to distribute content-updates to subscribers.

2.3.1. Initialization

Since the relationship of the subscriber and the topic is unique in the hub, websubhub:HubClient is designed to be initialized per subscription basis. Hence, websubhub:HubClient could be initialized by providing websubhub:Subscription and optional websubhub:ClientConfiguration.

2.3.2. Distribute Content

websubhub:HubClient should provide following API to be used to deliver content to the subscriber.

3. Publisher Client

WebSub publisher, has two main responsibilities:

  • Advertise topics in a hub
  • Publish/Update content for the topics registered in a hub

3.1. Initialization

websubhub:PublisherClient can be initialized by providing the hub URL and optional websubhub:ClientConfiguration.

3.2. Register/Deregister Topics

websubhub:PublisherClient could be used to register/deregister topics in a hub.

registerTopic

This remote method is invoked when the publisher tries to register a topic in a particular hub.

deregisterTopic

This remote method is invoked when the publisher tries to deregister a topic from a particular hub.

3.2. Update Content

websubhub:PublisherClient has the capability to notify the content-update for a topic to the hub.

publishUpdate

This remote method is used to directly send the content-update for a topic to the hub.

notifyUpdate

This remote method is used to notify the hub, that the topic has been updated.

4. Common Client Configuration

WebSubHub library provides following client configurations to be used when initializing websubhub:HubClient/websubhub:PublisherClient.