ballerina/websub package

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.

Records Summary

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

Objects Summary

Object Description
CallerActions

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

Client

Object representing the WebSub Hub Client Endpoint.

IntentVerificationRequest

Object representing and intent verification request received.

Listener

Object representing the WebSubSubscriber Service Endpoint.

Service
SignatureValidationFilter

Signature validation filter for WebSub services.

WebSubHub

Object to represent a WebSub Hub.

Functions Summary

Return Type Function and Description
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.

WebSubHub startUpBallerinaHub()

Starts up 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 type 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 type 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 type 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 type 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 type 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 type 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 type 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 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 startUpBallerinaHub() returns (WebSubHub)

Starts up the Ballerina Hub.

Return Type Description
WebSubHub

WebSubHub The WebSubHub object representing the started up hub

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.

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