ballerina/websub package

Primitives Summary

Type Description

Type Definitions

Type Values Description
TopicIdentifier TOPIC_ID_PAYLOAD_KEY | TOPIC_ID_HEADER_AND_PAYLOAD | TOPIC_ID_HEADER

Annotations

Name Attachement Points Data Type Description
SubscriberServiceConfig service SubscriberServiceConfiguration
WebSubSubscriber Configuration for the service.

Objects Summary

Object Description
HubClientEndpointConfiguration
Object representing the WebSub Hub Client Endpoint configuration.
Notification
Record representing the WebSubSubscriber notification received.
SubscriberServiceConfiguration
Configuration for a WebSubSubscriber service.
SubscriberServiceEndpointConfiguration
Object representing the configuration for the WebSubSubscriber Service Endpoint.
SubscriptionChangeRequest
Record to represent a WebSub subscription request.
SubscriptionChangeResponse
Record to represent subscription/unsubscription details on success.
SubscriptionDetails
Struct to represent Subscription Details retrieved from the database.

Endpoints Summary

Endpoint Description

Functions Summary

Return Type Function and Description
addSubscription(SubscriptionDetails subscriptionDetails)
Adds a new subscription for the specified topic in the Ballerina Hub.
Response addWebSubLinkHeaders(Response response, string[] hubs, string topic)
Function to add link headers to a response to allow WebSub discovery.
FilterResult interceptWebSubRequest(Request request, FilterContext context)
The function called to validate signature for content received by WebSub services.
boolean isTopicRegistered(string topic)
Retrieves whether a topic is registered with the Ballerina Hub.
error processWebSubNotification(Request request, typedesc serviceType)
Function to validate signature for requests received at the callback.
string publishToInternalHub(string topic, json payload)
Publishes an update against the topic in the Ballerina Hub.
string registerTopicAtHub(string topic, string secret)
Registers a topic in the Ballerina Hub.
removeSubscription(string topic, string callback)
Removes a subscription added for the specified topic in the Ballerina Hub.
string retrievePublisherSecret(string topic)
Retrieves secret for a topic registered with the Ballerina Hub.
WebSubHub startUpBallerinaHub()
Starts up the Ballerina Hub.
string unregisterTopicAtHub(string topic, string secret)
Unregisters a topic in the Ballerina Hub.
error validateSignature(string xHubSignature, string stringPayload, string secret)
Function to validate the signature header included in the notification.

Global Variables

Name Data Type Description
CONTENT_TYPE string
HUB_CALLBACK string
HUB_CHALLENGE string
HUB_LEASE_SECONDS string
HUB_MODE string
HUB_SECRET string
HUB_TOPIC string
MD5 string
MODE_PUBLISH string
MODE_REGISTER string
MODE_SUBSCRIBE string
MODE_UNREGISTER string
MODE_UNSUBSCRIBE string
PUBLISHER_SECRET string
PUBLISHER_SIGNATURE string
REMOTE_PUBLISHING_MODE_DIRECT string
REMOTE_PUBLISHING_MODE_FETCH string
SHA1 string
SHA256 string
TOPIC_ID_HEADER TopicIdentifier
TOPIC_ID_HEADER_AND_PAYLOAD TopicIdentifier
TOPIC_ID_PAYLOAD_KEY TopicIdentifier
X_HUB_SIGNATURE string
X_HUB_TOPIC string
X_HUB_UUID string

public object HubClientEndpointConfiguration

Object representing the WebSub Hub Client Endpoint configuration.

Field Name Data Type Default Value Description
url string

The URL of the target Hub

secureSocket SecureSocket

SSL/TLS related options

auth AuthConfig

public object Notification

Record representing the WebSubSubscriber notification received.

Field Name Data Type Default Value Description
payload json

The payload of the notification received

request Request

The HTTP POST request received as the notification

public object SubscriberServiceConfiguration

Configuration for a WebSubSubscriber service.

Field Name Data Type Default Value Description
endpoints Listener[]

Array of endpoints the service would be attached to

path string

Path of the WebSubSubscriber service

subscribeOnStartUp boolean

Whether a subscription request is expected to be sent on start up

resourceUrl string

The resource URL for which discovery will be initiated to identify hub and topic if not specified

hub string

The hub at which the subscription should be registered

topic string

The topic to which this WebSub subscriber (callback) should be registered

leaseSeconds int

The period for which the subscription is expected to be active

secret string

The secret to be used for authenticated content distribution

callback string

The callback to use when registering, if unspecified host:port/path will be used

auth AuthConfig

The auth configuration to use when subscribing at the hub

secureSocket SecureSocket

The secure socket configuration to use when subscribing at the hub

public object SubscriberServiceEndpointConfiguration

Object representing the configuration for the WebSubSubscriber Service Endpoint.

Field Name Data Type Default Value Description
host string

The configuration for the endpoint

port int

The underlying HTTP service endpoint

secureSocket ServiceSecureSocket

The SSL configurations for the service endpoint

topicIdentifier TopicIdentifier

The identifier based on which dispatching should happen for custom subscriber services

topicHeader string

The header to consider if required with dispatching for custom services

topicPayloadKeys string[]

The payload keys to consider if required with dispatching for custom services

topicResourceMap map<map<string>>

The mapping between topics and resources if required for custom services

public object SubscriptionChangeRequest

Record to represent a WebSub subscription request.

Field Name Data Type Default Value Description
topic string

The topic for which the subscription/unsubscription request is sent

callback string

The callback which should be registered/unregistered for the subscription/unsubscription request is sent

leaseSeconds int

The lease period for which the subscription is expected to be active

secret string

The secret to be used for authenticated content distribution with this subscription

public object SubscriptionChangeResponse

Record to represent subscription/unsubscription details on success.

Field Name Data Type Default Value Description
hub string

The hub at which the subscription/unsubscription was successful

topic string

The topic for which the subscription/unsubscription was successful

response Response

The response from the hub to the subscription/unsubscription requests

public object SubscriptionDetails

Struct to represent Subscription Details retrieved from the database.

Field Name Data Type Default Value Description
topic string

The topic for which the subscription is added

callback string

The callback specified for the particular subscription

secret string

The secret to be used for authenticated content distribution

leaseSeconds int

The lease second period specified for the particular subscription

createdAt int

The time at which the subscription was created

public function addSubscription(SubscriptionDetails subscriptionDetails)

Adds a new subscription for the specified topic in the Ballerina Hub.

Parameter Name Data Type Default Value Description
subscriptionDetails SubscriptionDetails

The details of the subscription including WebSub specifics

public function addWebSubLinkHeaders(Response response, string[] hubs, string topic) returns (Response)

Function to add link headers to a response to allow WebSub discovery.

Parameter Name Data Type Default Value Description
response Response

The response being sent

hubs string[]

The hubs the publisher advertises as the hubs that it publishes updates to

topic string

The topic to which subscribers need to subscribe to, to receive updates for the resource/topic

Return Type Description
Response

http:Response Response with the link header added

public function interceptWebSubRequest(Request request, FilterContext context) returns (FilterResult)

The function called to validate signature for content received by WebSub services.

Parameter Name Data Type Default Value Description
request Request

The request being intercepted

context FilterContext

The filter context

Return Type Description
FilterResult

http:FilterResult The result of the filter indicating whether or not proceeding can be allowed

public function isTopicRegistered(string topic) returns (boolean)

Retrieves whether a topic is registered with the Ballerina Hub.

Parameter Name Data Type Default Value Description
topic string

The topic to check

Return Type Description
boolean

boolean True if the topic has been registered by a publisher, false if not

public function processWebSubNotification(Request request, typedesc serviceType) returns (error)

Function to validate signature for requests received at the callback.

Parameter Name Data Type Default Value Description
request Request

The request received

serviceType typedesc

The type of the service for which the request was rceived

Return Type Description
error

error, if an error occurred in extraction or signature validation failed

public function publishToInternalHub(string topic, json payload) returns (string)

Publishes an update against the topic in the Ballerina Hub.

Parameter Name Data Type Default Value Description
topic string

The topic for which the update should happen

payload json

The update payload

Return Type Description
string

string Error Message if an error occurred with publishing

public function registerTopicAtHub(string topic, string secret) returns (string)

Registers a topic in the Ballerina Hub.

Parameter Name Data Type Default Value Description
topic string

The topic to register

secret string

The secret to use to identify the registration

Return Type Description
string

string Error Message if an error occurred with registration

public function removeSubscription(string topic, string callback)

Removes a subscription added for the specified topic in the Ballerina Hub.

Parameter Name Data Type Default Value Description
topic string

The topic for which the subscription was added

callback string

The callback registered for this subscription

public function retrievePublisherSecret(string topic) returns (string)

Retrieves secret for a topic registered with the Ballerina Hub.

Parameter Name Data Type Default Value Description
topic string

The topic for which the publisher's secret needs to be retrieved

Return Type Description
string

string The secret specified at registration

public function startUpBallerinaHub() returns (WebSubHub)

Starts up the Ballerina Hub.

Return Type Description
WebSubHub

WebSubHub The WebSubHub struct representing the started up hub

public function unregisterTopicAtHub(string topic, string secret) returns (string)

Unregisters a topic in the Ballerina Hub.

Parameter Name Data Type Default Value Description
topic string

The topic to unregister

secret string

The secret specified at registration

Return Type Description
string

string Error Message if an error occurred with unregistration

public function validateSignature(string xHubSignature, string stringPayload, string secret) returns (error)

Function to validate the signature header included in the notification.

Parameter Name Data Type Default Value Description
xHubSignature string

The X-Hub-Signature header included in the notification request from the hub

stringPayload string

The string representation of the notification payload received

secret string

The secret used when subscribing

Return Type Description
error

error if an error occurs validating the signature or the signature is invalid

public type CallerActions object

The HTTP based Caller actions for outbound WebSub Subscription, Unsubscription, Registration, Unregistration and
Notification requests to a Hub.

Field Name Data Type Default Value Description
hubUrl string
  • <CallerActions> subscribe(SubscriptionChangeRequest subscriptionRequest) returns (SubscriptionChangeResponse | error)

        Function to send a subscription request to a WebSub Hub.
    

    Parameter Name Data Type Default Value Description
    subscriptionRequest SubscriptionChangeRequest

    The SubscriptionChangeRequest containing subscription details

    Return Type Description
    SubscriptionChangeResponse | error

    SubscriptionChangeResponse indicating subscription details, if the request was successful else error if an error occurred with the subscription request

  • <CallerActions> unsubscribe(SubscriptionChangeRequest unsubscriptionRequest) returns (SubscriptionChangeResponse | error)

        Function to send an unsubscription request to a WebSub Hub.
    

    Parameter Name Data Type Default Value Description
    unsubscriptionRequest SubscriptionChangeRequest

    The SubscriptionChangeRequest containing unsubscription details

    Return Type Description
    SubscriptionChangeResponse | error

    SubscriptionChangeResponse indicating unsubscription details, if the request was successful else error if an error occurred with the unsubscription request

  • <CallerActions> registerTopic(string topic) returns (error)

        Function to register a topic in a Ballerina WebSub Hub against which subscribers can subscribe and the publisher
         will publish updates, with a secret which will be used in signature generation if specified.
    

    Parameter Name Data Type Default Value Description
    topic string

    The topic to register

    Return Type Description
    error

    error if an error occurred registering the topic

  • <CallerActions> unregisterTopic(string topic) returns (error)

        Function to unregister a topic in a Ballerina WebSub Hub.
    

    Parameter Name Data Type Default Value Description
    topic string

    The topic to unregister

    Return Type Description
    error

    error if an error occurred unregistering the topic

  • <CallerActions> publishUpdate(string topic, json payload) returns (error)

        Function to publish an update to a remote Ballerina WebSub Hub.
    

    Parameter Name Data Type Default Value Description
    topic string

    The topic for which the update occurred

    payload json

    The update payload

    Return Type Description
    error

    error if an error occurred with the update

  • <CallerActions> notifyUpdate(string topic) returns (error)

        Function to notify a remote WebSub Hub that an update is available to fetch, for hubs that require publishing to
         happen as such.
    

    Parameter Name Data Type Default Value Description
    topic string

    The topic for which the update occurred

    Return Type Description
    error

    error if an error occurred with the notification

public type Client object

Object representing the WebSub Hub Client Endpoint.

Field Name Data Type Default Value Description
config HubClientEndpointConfiguration
  • <Client> init(HubClientEndpointConfiguration config)

        Gets called when the endpoint is being initialized during package init.
    

    Parameter Name Data Type Default Value Description
    config HubClientEndpointConfiguration

    The configuration for the endpoint

  • <Client> register(typedesc serviceType)

        Gets called whenever a service attaches itself to this endpoint and during package init.
    

    Parameter Name Data Type Default Value Description
    serviceType typedesc

    The service attached

  • <Client> start()

        Starts the registered service.
    

  • <Client> getCallerActions() returns (CallerActions)

        Returns the connector that client code uses.
    

    Return Type Description
    CallerActions

    CallerActions The caller actions available for clients

  • <Client> stop()

        Stops the registered service.
    

public type IntentVerificationRequest object

Object representing and intent verification request received.

Field Name Data Type Default Value Description
mode string

The mode specified whether intent is being verified for subscription or unsubscription

topic string

The for which intent is being verified for subscription or unsubscription

challenge string

The challenge to be echoed to verify intent to subscribe/unsubscribe

leaseSeconds int

The lease seconds period for which a subscription will be active if intent verification is being done for subscription

request Request

The HTTP request received for intent verification

  • <IntentVerificationRequest> buildSubscriptionVerificationResponse() returns (Response)

        Function to build intent verification response for subscription requests sent.
    

    Return Type Description
    Response

    http:Response The response to the hub verifying/denying intent to subscribe

  • <IntentVerificationRequest> buildUnsubscriptionVerificationResponse() returns (Response)

        Function to build intent verification response for unsubscription requests sent.
    

    Return Type Description
    Response

    http:Response The response to the hub verifying/denying intent to unsubscribe

public type Listener object

Object representing the WebSubSubscriber Service Endpoint.

Field Name Data Type Default Value Description
config SubscriberServiceEndpointConfiguration

The configuration for the endpoint

  • <Listener> init(SubscriberServiceEndpointConfiguration config)

         Gets called when the endpoint is being initialized during package init.
    

    Parameter Name Data Type Default Value Description
    config SubscriberServiceEndpointConfiguration

    The Subscriber Service Endpoint Configuration of the endpoint

  • <Listener> register(typedesc serviceType)

        Gets called whenever a service attaches itself to this endpoint and during package init.
    

    Parameter Name Data Type Default Value Description
    serviceType typedesc

    The service attached

  • <Listener> start()

        Starts the registered service.
    

  • <Listener> getCallerActions() returns (Connection)

        Returns the connector that client code uses.
    

    Return Type Description
    Connection

    http:Connection The connector that client code uses

  • <Listener> stop()

        Stops the registered service.
    

  • <Listener> initWebSubSubscriberServiceEndpoint()

  • <Listener> registerWebSubSubscriberServiceEndpoint(typedesc serviceType)

    Parameter Name Data Type Default Value Description
    serviceType typedesc

public type Service object

  • <Service> getEndpoint() returns (Listener)

    Return Type Description
    Listener

public type SignatureValidationFilter object

Signature validation filter for WebSub services.

  • <SignatureValidationFilter> filterRequest(Request request, FilterContext context) returns (FilterResult)

    Parameter Name Data Type Default Value Description
    request Request
    context FilterContext
    Return Type Description
    FilterResult

public type WebSubHub object

Object to represent a WebSub Hub.

Field Name Data Type Default Value Description
hubUrl string
  • <WebSubHub> stop() returns (boolean)

        Stops the started up Ballerina Hub.
    

    Return Type Description
    boolean

    boolean indicating whether the internal Ballerina Hub was stopped

  • <WebSubHub> publishUpdate(string topic, json payload) returns (error)

        Publishes an update against the topic in the initialized Ballerina Hub.
    

    Parameter Name Data Type Default Value Description
    topic string

    The topic for which the update should happen

    payload json

    The update payload

    Return Type Description
    error

    error if the hub is not initialized or does not represent the internal hub

  • <WebSubHub> registerTopic(string topic) returns (error)

        Registers a topic in the Ballerina Hub.
    

    Parameter Name Data Type Default Value Description
    topic string

    The topic to register

    Return Type Description
    error

    error if an error occurred with registration

  • <WebSubHub> unregisterTopic(string topic) returns (error)

        Unregisters a topic in the Ballerina Hub.
    

    Parameter Name Data Type Default Value Description
    topic string

    The topic to unregister

    Return Type Description
    error

    error if an error occurred with unregistration