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 |
|
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 |
|
public function startUpBallerinaHub() returns (WebSubHub)
Starts up the Ballerina Hub.
Return Type | Description | ||
---|---|---|---|
WebSubHub |
|
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 |
|
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 elseerror
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 elseerror
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