ballerina/websub package
Package overview
This package contains an implementation of the W3C WebSub recommendation, which facilitates a push-based content delivery/notification mechanism between publishers and subscribers.
This implementation supports introducing all WebSub components: subscribers, publishers, and hubs.
- Subscriber - A party interested in receiving update notifications for particular topics.
- Publisher - A party that advertises topics to which interested parties subscribe in order to receive notifications on occurrence of events.
- Hub - A party that accepts subscription requests from subscribers and delivers content to the subscribers when the topic is updated by the topic's publisher.
Basic Flow with WebSub
-
Subscriber discovers the topics it needs to subscribe to in order to receive updates/content and discovers the hub(s) where it can subscribe.
-
Subscriber sends a subscription request to a hub, specifying the topic it needs to receive notifications for along with other subscription parameters, such as:
- The callback URL where content is expected to be delivered
- (Optional) A lease seconds value indicating how long the subscriber wants the subscription to stay active
- (Optional) A secret to use for authenticated content distribution
-
The hub sends an intent verification request to the specified callback URL, and 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.
-
Publisher notifies the hub of updates to the topic, and the content to deliver is identified.
-
The hub delivers the identified content to the subscribers of the topic.
Features
This package allows introducing a WebSub Subscriber Service with onIntentVerification
, which accepts HTTP GET requests for intent verification, and onNotification
, which accepts HTTP POST requests for notifications. The WebSub Subscriber Service provides the following capabilities:
- Subscription Requests are sent at service start time for the hub and topic, which are either specified as annotations or discovered based on the resource URL specified as an annotation.
- Auto Intent Verification against the topic specified as an annotation, or discovered based on the resource URL specified as an annotation, if
onIntentVerification
is not specified. - Signature Validation for authenticated content distribution if a secret is specified for the subscription.
A WebSub compliant hub based on the Ballerina Message Broker is also available for use as a remote hub or to be used by publishers who want to have their own internal hub. Ballerina's WebSub Hub honors specified lease periods and supports authenticated content distribution.
Ballerina WebSub publishers can use utility functions to add WebSub link headers indicating the hub and topic URLs, which facilitates WebSub discovery.
A hub client endpoint is also made available to publishers and subscribers to perform the following:
- Publishers
- Register a topic at the Hub
- Publish to the hub, indicating an update of the topic
- Subscribers
- Subscribe/Unsubscribe to topics at a hub
Samples
This sample demonstrates a Subscriber Service with subscribeOnStartUp
set to true, which will result in a
subscription request being sent to the specified hub for the specified topic, with the specified lease seconds value
and the specified secret for authenticated content distribution.
Since an onIntentVerification
resource is not included, intent verification for subscription and unsubscription
requests would happen automatically, if the topic specified in the request matches that specified as an annotation or
that discovered for the annotated resource URL.
import ballerina/log;
import ballerina/websub;
endpoint websub:Listener websubEP {
port: 8181
};
@websub:SubscriberServiceConfig {
path: "/websub",
subscribeOnStartUp: true,
topic: "<TOPIC_URL>",
hub: "<HUB_URL>",
leaseSeconds: 3600,
secret: "<SECRET>"
}
service websubSubscriber bind websubEP {
onNotification(websub:Notification notification) {
match (notification.getPayloadAsString()) {
string payloadAsString => log:printInfo("WebSub Notification Received: "
+ payloadAsString);
error e => log:printError("Error retrieving payload as string", err = e);
}
}
}
Explicit intent verification can be done by introducing an onIntentVerification
resource.
import ballerina/log;
import ballerina/http;
import ballerina/websub;
endpoint websub:Listener websubEP {
port: 8181
};
@websub:SubscriberServiceConfig {
path: "/websub",
subscribeOnStartUp: true,
topic: "<TOPIC_URL>",
hub: "<HUB_URL>",
leaseSeconds: 3600,
secret: "<SECRET>"
}
service websubSubscriber bind websubEP {
onIntentVerification(endpoint caller, websub:IntentVerificationRequest request) {
http:Response response = new;
// Insert logic to build subscription/unsubscription intent verification response
caller->respond(response) but {
error e => log:printError("Error responding to intent verification request", err = e)
};
}
onNotification(websub:Notification notification) {
match (notification.getPayloadAsString()) {
string payloadAsString => log:printInfo("WebSub Notification Received: "
+ payloadAsString);
error e => log:printError("Error retrieving payload as string", err = e);
}
}
}
Functions are made available on the websub:IntentVerificationRequest
to build a subscription or unsubscription
verification response, specifying the topic to verify intent against:
http:Response response = request.buildSubscriptionVerificationResponse("<TOPIC_TO_VERIFY_FOR>");
http:Response response = request.buildUnsubscriptionVerificationResponse("<TOPIC_TO_VERIFY_FOR>");
Ballerina publishers can start up and publish directly to the Ballerina WebSub hub.
import ballerina/log;
import ballerina/runtime;
import ballerina/websub;
function main(string... args) {
log:printInfo("Starting up the Ballerina Hub Service");
websub:WebSubHub webSubHub = websub:startUpBallerinaHub(port = 9191) but {
websub:HubStartedUpError hubStartedUpErr => hubStartedUpErr.startedUpHub
};
var registrationResponse = webSubHub.registerTopic("<TOPIC_URL>");
match (registrationResponse) {
error webSubError => log:printError("Error occurred registering topic: " + webSubError.message);
() => log:printInfo("Topic registration successful!");
}
// Make the publisher wait until the subscriber subscribes at the hub.
runtime:sleep(20000);
log:printInfo("Publishing update to internal Hub");
var publishResponse = webSubHub.publishUpdate("<TOPIC_URL>", {"action": "publish", "mode": "internal-hub"});
match (publishResponse) {
error webSubError => log:printError("Error notifying hub: " + webSubError.message);
() => log:printInfo("Update notification successful!");
}
// Make sure the service is running until the subscriber receives the update notification.
runtime:sleep(5000);
}
Ballerina publishers can also use the hub client endpoint to register topics at Ballerina WebSub hubs and publish/notify updates to the remote hubs.
import ballerina/log;
import ballerina/runtime;
import ballerina/websub;
endpoint websub:Client websubHubClientEP {
url: "https://localhost:9191/websub/hub"
};
function main(string... args) {
var registrationResponse = websubHubClientEP->registerTopic("<TOPIC_URL>");
match (registrationResponse) {
error webSubError => log:printError("Error occurred registering topic: " + webSubError.message);
() => log:printInfo("Topic registration successful!");
}
// Make the publisher wait until the subscriber subscribes at the hub.
runtime:sleep(10000);
log:printInfo("Publishing update to remote Hub");
var publishResponse = websubHubClientEP->publishUpdate("<TOPIC_URL>", {"action": "publish", "mode": "remote-hub"});
match (publishResponse) {
error webSubError => log:printError("Error notifying hub: " + webSubError.message);
() => log:printInfo("Update notification successful!");
}
}
The hub client endpoint can also be used by subscribers to send subscription and unsubscription requests explicitly.
import ballerina/log;
import ballerina/websub;
endpoint websub:Client websubHubClientEP {
url: "<HUB_URL>"
};
function main(string... args) {
// Send subscription request for a subscriber service.
websub:SubscriptionChangeRequest subscriptionRequest = { topic: "<TOPIC_URL>",
callback: "<CALLBACK_URL>",
secret: "<SECRET>" };
var response = websubHubClientEP->subscribe(subscriptionRequest);
match (response) {
websub:SubscriptionChangeResponse subscriptionChangeResponse => {
log:printInfo("Subscription Request successful at Hub [" + subscriptionChangeResponse.hub
+ "] for Topic [" + subscriptionChangeResponse.topic + "]");
}
error e => {
log:printError("Error occurred with Subscription Request", err = e);
}
}
// Send unsubscription request for the subscriber service.
websub:SubscriptionChangeRequest unsubscriptionRequest = { topic: "<TOPIC_URL>",
callback: "<CALLBACK_URL>" };
response = websubHubClientEP->unsubscribe(unsubscriptionRequest);
match (response) {
websub:SubscriptionChangeResponse subscriptionChangeResponse => {
log:printInfo("Unsubscription Request successful at Hub [" + subscriptionChangeResponse.hub
+ "] for Topic [" + subscriptionChangeResponse.topic + "]");
}
error e => {
log:printError("Error occurred with Unsubscription Request", err = e);
}
}
}
Configuration Parameters
The Ballerina WebSub implementation allows specifying the following properties/parameters via the Ballerina Config API, where the values specified via the Config API would be used if the values are not specified as params on hub start up.
Configuration Key | Default Value | Description |
---|---|---|
b7a.websub.hub.port | 9292 | The port to start the WebSub Hub Service on |
b7a.websub.hub.leasetime | 86400 | The default lease period, if not specified in a request |
b7a.websub.hub.signaturemethod | "SHA256" | The signature method to use for authenticated content distribution |
b7a.websub.hub.remotepublish | false | Whether publishing updates against the topics in the hub could be done by remote publishers via HTTP requests with hub.mode set to publish |
b7a.websub.hub.topicregistration | true | Whether a topic needs to be registered at the hub for publishers to publish updates against the topic and for subscribers to send subscription requests for the topic |
b7a.websub.hub.enablessl | true | Whether the Hub service should be exposed over HTTPS |
Annotations
Name | Attachement Points | Data Type | Description |
---|---|---|---|
SubscriberServiceConfig | service | SubscriberServiceConfiguration | WebSub Subscriber Configuration for the service, indicating subscription related parameters. |
Records Summary
Record | Description | ||
---|---|---|---|
HubClientEndpointConfig | Record representing the configuration parameters for the WebSub Hub Client Endpoint. | ||
HubStartedUpError | Error to represent that a WebSubHub is already started up, encapsulating the started up Hub. | ||
SubscriberServiceConfiguration | Configuration for a WebSubSubscriber service. | ||
SubscriberServiceEndpointConfiguration | Object representing the configuration for the WebSub Subscriber Service Endpoint. | ||
SubscriptionChangeRequest | Record representing a WebSub subscription change request. | ||
SubscriptionChangeResponse | Record representing subscription/unsubscription details if a subscription/unsubscription request is successful. |
Objects Summary
Object | Description | ||
---|---|---|---|
CallerActions | The HTTP based Caller actions for outbound WebSub Subscription, Unsubscription, Registration, Unregistration and Notification requests to a Hub. |
||
IntentVerificationRequest | Object representing an intent verification request received. |
||
Notification | Object representing the WebSub Content Delivery Request received. |
||
Service | The object representing the WebSub Subscriber Service. |
||
WebSubHub | Object representing a Ballerina WebSub Hub. |
Endpoints Summary
Endpoint | Description | ||
---|---|---|---|
Client | Object representing the WebSub Hub Client Endpoint. |
||
Listener | Object representing the WebSubSubscriber Service Endpoint. |
Functions Summary
Return Type | Function and Description | ||
---|---|---|---|
Response | addWebSubLinkHeader(http:Response response, string[] hubs, string topic) Function to add link headers to a response to allow WebSub discovery. |
||
WebSubHub | HubStartedUpError | startUpBallerinaHub(int? port, int? leaseSeconds, string? signatureMethod, boolean? remotePublishingEnabled, string? remotePublishingMode, boolean? topicRegistrationRequired, string? publicUrl, boolean? sslEnabled) Starts up the Ballerina Hub. |
public type HubClientEndpointConfig record
Record representing the configuration parameters for the WebSub Hub Client Endpoint.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
url | string | The URL of the target Hub |
|
clientSecureSocket | http:SecureSocket? | SSL/TLS related options for the underlying HTTP Client |
|
auth | http:AuthConfig? | Authentication mechanism for the underlying HTTP Client |
|
followRedirects | http:FollowRedirects? | HTTP redirect related configuration |
public type HubStartedUpError record
Error to represent that a WebSubHub is already started up, encapsulating the started up Hub.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
message | string | The error message |
|
startedUpHub | websub:0.0.0:WebSubHub | The |
public type SubscriberServiceConfiguration record
Configuration for a WebSubSubscriber service.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
endpoints | websub:0.0.0:Listener[] | Array of endpoints the service would be attached to |
|
path | string | Path of the WebSubSubscriber service |
|
subscribeOnStartUp | boolean | Boolean indicating 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 for 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 | http:AuthConfig? | The auth configuration to use when subscribing at the hub |
|
secureSocket | http:SecureSocket? | The secure socket configuration to use when subscribing at the hub |
|
followRedirects | http:FollowRedirects? | The HTTP redirect related configuration specifying if subscription requests should be sent to redirected hubs/topics |
public type SubscriberServiceEndpointConfiguration record
Object representing the configuration for the WebSub Subscriber Service Endpoint.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
host | string | The configuration for the endpoint |
|
port | int | The underlying HTTP service endpoint |
|
httpServiceSecureSocket | http:ServiceSecureSocket? | The SSL configurations for the service endpoint |
|
topicIdentifier | TOPIC_ID_HEADER_AND_PAYLOAD|TOPIC_ID_PAYLOAD_KEY|TOPIC_ID_HEADER? | 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 | The mapping between topics and resources if required for custom services |
public type SubscriptionChangeRequest record
Record representing a WebSub subscription change 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
Record representing subscription/unsubscription details if a subscription/unsubscription request is successful.
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 | http:Response | The response from the hub to the subscription/unsubscription requests |
public function addWebSubLinkHeader(http: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 | http: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 |
Return Type | Description | ||
---|---|---|---|
Response |
|
public function startUpBallerinaHub(int? port, int? leaseSeconds, string? signatureMethod, boolean? remotePublishingEnabled, string? remotePublishingMode, boolean? topicRegistrationRequired, string? publicUrl, boolean? sslEnabled) returns (WebSubHub | HubStartedUpError)
Starts up the Ballerina Hub.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
port | int? | null | The port to start up the hub on |
leaseSeconds | int? | null | The default lease seconds value to honour if not specified in subscription requests |
signatureMethod | string? | null | The signature method to use for authenticated content delivery ( |
remotePublishingEnabled | boolean? | null | Whether remote publishers should be allowed to publish to this hub (HTTP requests) |
remotePublishingMode | string? | null | If remote publishing is allowed, the mode to use, |
topicRegistrationRequired | boolean? | null | Whether a topic needs to be registered at the hub prior to publishing/subscribing to the topic |
publicUrl | string? | null | The URL for the hub to be included in content delivery requests, defaults to
|
sslEnabled | boolean? | null | Whether SSL needs to be enabled for the hub, enabled by default |
Return Type | Description | ||
---|---|---|---|
WebSubHub | HubStartedUpError |
|
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 | The URL of the target Hub to which requests need to be sent |
-
<CallerActions> subscribe(websub:0.0.0:SubscriptionChangeRequest subscriptionRequest) returns (SubscriptionChangeResponse | error)
Sends a subscription request to a WebSub Hub.
Parameter Name Data Type Default Value Description subscriptionRequest websub:0.0.0:SubscriptionChangeRequest The
SubscriptionChangeRequest
containing subscription detailsReturn Type Description SubscriptionChangeResponse | error SubscriptionChangeResponse
indicating subscription details, if the request was successful elseerror
if an error occurred with the subscription request -
<CallerActions> unsubscribe(websub:0.0.0:SubscriptionChangeRequest unsubscriptionRequest) returns (SubscriptionChangeResponse | error)
Sends an unsubscription request to a WebSub Hub.
Parameter Name Data Type Default Value Description unsubscriptionRequest websub:0.0.0:SubscriptionChangeRequest The
SubscriptionChangeRequest
containing unsubscription detailsReturn 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, string? secret) returns (error)
Registers 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
secret string? null The secret the publisher will use to generate a signature when publishing updates
Return Type Description error error
if an error occurred registering the topic -
<CallerActions> unregisterTopic(string topic, string? secret) returns (error)
Unregisters a topic in a Ballerina WebSub Hub.
Parameter Name Data Type Default Value Description topic string The topic to unregister
secret string? null The secret the publisher used when registering the topic
Return Type Description error error
if an error occurred unregistering the topic -
<CallerActions> publishUpdate(string topic, string|xml|json|blob|io:ByteChannel payload, string? contentType, string? secret, string signatureMethod, map<string>? headers) returns (error)
Publishes 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 string|xml|json|blob|io:ByteChannel The update payload
contentType string? null secret string? null The secret used when registering the topic
signatureMethod string sha256 The signature method to use to generate a secret
headers map ? null The headers, if any, that need to be set
Return Type Description error error
if an error occurred with the update -
<CallerActions> notifyUpdate(string topic, map<string>? headers) returns (error)
Notifies 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
headers map ? null The headers, if any, that need to be set
Return Type Description error error
if an error occurred with the notification
public type IntentVerificationRequest object
Object representing an 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 | http:Request | The HTTP request received for intent verification |
-
<IntentVerificationRequest> buildSubscriptionVerificationResponse(string t) returns (Response)
Builds the response for the request, verifying intention to subscribe, if the topic matches that expected.
Parameter Name Data Type Default Value Description t string The topic for which subscription should be accepted
Return Type Description Response http:Response
The response to the hub verifying/denying intent to subscribe -
<IntentVerificationRequest> buildUnsubscriptionVerificationResponse(string t) returns (Response)
Builds the response for the request, verifying intention to unsubscribe, if the topic matches that expected.
Parameter Name Data Type Default Value Description t string The topic for which unsubscription should be accepted
Return Type Description Response http:Response
The response to the hub verifying/denying intent to unsubscribe
public type Notification object
Object representing the WebSub Content Delivery Request received.
-
<Notification> getQueryParams() returns (map<string>)
Retrieves the query parameters of the content delivery request, as a map.
Return Type Description map String constrained map of query params
-
<Notification> getEntity() returns (mimeEntity | error)
Retrieves the
Entity
associated with the content delivery request.Return Type Description mimeEntity | error The
Entity
of the request. Anerror
is returned, if entity construction fails -
<Notification> hasHeader(string headerName) returns (boolean)
Returns whether the requested header key exists in the header map of the content delivery request.
Parameter Name Data Type Default Value Description headerName string The header name
Return Type Description boolean Returns true if the specified header key exists
-
<Notification> getHeader(string headerName) returns (string)
Returns the value of the specified header. If the specified header key maps to multiple values, the first of these values is returned.
Parameter Name Data Type Default Value Description headerName string The header name
Return Type Description string The first header value for the specified header name. An exception is thrown if no header is found. Ideally
hasHeader()
needs to be used to check the existence of header initially. -
<Notification> getHeaders(string headerName) returns (string[])
Retrieves all the header values to which the specified header key maps to.
Parameter Name Data Type Default Value Description headerName string The header name
Return Type Description string[] The header values the specified header key maps to. An exception is thrown if no header is found. Ideally
hasHeader()
needs to be used to check the existence of header initially. -
<Notification> getHeaderNames() returns (string[])
Retrieves all the names of the headers present in the content delivery request.
Return Type Description string[] An array of all the header names
-
<Notification> getContentType() returns (string)
Retrieves the type of the payload of the content delivery request (i.e: the
content-type
header value).Return Type Description string Returns the
content-type
header value as a string -
<Notification> getJsonPayload() returns (json | error)
Extracts
json
payload from the content delivery request.Return Type Description json | error The
json
payload orerror
in case of errors. If the content type is not JSON, anerror
is returned. -
<Notification> getXmlPayload() returns (xml | error)
Extracts
xml
payload from the content delivery request.Return Type Description xml | error The
xml
payload orerror
in case of errors. If the content type is not XML, anerror
is returned. -
<Notification> getTextPayload() returns (string | error)
Extracts
text
payload from the content delivery request.Return Type Description string | error The
text
payload orerror
in case of errors. If the content type is not of type text, anerror
is returned. -
<Notification> getPayloadAsString() returns (string | error)
Retrieves the content delivery request payload as a
string
. Content type is not checked during payload construction which makes this different fromgetTextPayload()
function.Return Type Description string | error The string representation of the message payload or
error
in case of errors -
<Notification> getByteChannel() returns (ioByteChannel | error)
Retrieves the request payload as a
ByteChannel
except in the case of multiparts.Return Type Description ioByteChannel | error A byte channel from which the message payload can be read or
error
in case of errors -
<Notification> getBinaryPayload() returns (blob | error)
Retrieves the request payload as a
blob
.Return Type Description blob | error The blob representation of the message payload or
error
in case of errors -
<Notification> getFormParams() returns (map<string> | error)
Retrieves the form parameters from the content delivery request as a
map
.Return Type Description map | error The map of form params or
error
in case of errors
public type Service object
The object representing the WebSub Subscriber Service.
-
<Service> getEndpoint() returns (Listener)
Returns the WebSub Listener endpoint to which this service binds.
Return Type Description Listener WebSub
Listener
endpoint
public type WebSubHub object
Object representing a Ballerina WebSub Hub.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
hubUrl | string | The URL of the started up Ballerina WebSub Hub |
-
<WebSubHub> stop() returns (boolean)
Stops the started up Ballerina WebSub Hub.
Return Type Description boolean boolean
indicating whether the internal Ballerina Hub was stopped -
<WebSubHub> publishUpdate(string topic, string|xml|json|blob|io:ByteChannel payload, string? contentType) 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 string|xml|json|blob|io:ByteChannel The update payload
contentType string? null The content type header to set for the request delivering the 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
Endpoint Client
Object representing the WebSub Hub Client Endpoint.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
config | websub:0.0.0:HubClientEndpointConfig | The configuration for the endpoint |
-
<Client> subscribe(websub:0.0.0:SubscriptionChangeRequest subscriptionRequest) returns (websub:0.0.0:SubscriptionChangeResponse|error)
Sends a subscription request to a WebSub Hub.
Parameter Name Data Type Default Value Description subscriptionRequest websub:0.0.0:SubscriptionChangeRequest Return Type Description websub:0.0.0:SubscriptionChangeResponse|error -
<Client> unsubscribe(websub:0.0.0:SubscriptionChangeRequest unsubscriptionRequest) returns (websub:0.0.0:SubscriptionChangeResponse|error)
Sends an unsubscription request to a WebSub Hub.
Parameter Name Data Type Default Value Description unsubscriptionRequest websub:0.0.0:SubscriptionChangeRequest Return Type Description websub:0.0.0:SubscriptionChangeResponse|error -
<Client> registerTopic(string topic, string? secret) returns (error?)
Registers 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 secret string? Return Type Description error? -
<Client> unregisterTopic(string topic, string? secret) returns (error?)
Unregisters a topic in a Ballerina WebSub Hub.
Parameter Name Data Type Default Value Description topic string secret string? Return Type Description error? -
<Client> publishUpdate(string topic, string|xml|json|blob|io:ByteChannel payload, string? contentType, string? secret, string signatureMethod, map<string>? headers) returns (error?)
Publishes an update to a remote Ballerina WebSub Hub.
Parameter Name Data Type Default Value Description topic string payload string|xml|json|blob|io:ByteChannel contentType string? secret string? signatureMethod string headers map ? Return Type Description error? -
<Client> notifyUpdate(string topic, map<string>? headers) returns (error?)
Notifies 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 headers map ? Return Type Description error?
Endpoint Listener
Object representing the WebSubSubscriber Service Endpoint.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
config | websub:0.0.0:SubscriberServiceEndpointConfiguration | The configuration for the endpoint |
-
<Listener> respond(http:Response|string|xml|json|blob|io:ByteChannel|mime:Entity[]? message) returns (error?)
Sends the outbound response to the caller.
Parameter Name Data Type Default Value Description message http:Response|string|xml|json|blob|io:ByteChannel|mime:Entity[]? Return Type Description error? -
<Listener> promise(http:PushPromise promise) returns (error?)
Pushes a promise to the caller.
Parameter Name Data Type Default Value Description promise http:PushPromise Return Type Description error? -
<Listener> pushPromisedResponse(http:PushPromise promise, http:Response response) returns (error?)
Sends a promised push response to the caller.
Parameter Name Data Type Default Value Description promise http:PushPromise response http:Response Return Type Description error? -
<Listener> acceptWebSocketUpgrade(map headers) returns (http:WebSocketListener)
Sends an upgrade request with custom headers.
Parameter Name Data Type Default Value Description headers map Return Type Description http:WebSocketListener -
<Listener> cancelWebSocketUpgrade(int status, string reason) returns (error?)
Cancels the handshake.
Parameter Name Data Type Default Value Description status int reason string Return Type Description error? -
<Listener> continue() returns (error?)
Sends a `100-continue` response to the caller.
Return Type Description error? -
<Listener> redirect(http:Response response, 305|303|302|308|300|307|304|301 code, string[] locations) returns (error?)
Sends a redirect response to the user with the specified redirection status code.
Parameter Name Data Type Default Value Description response http:Response code 305|303|302|308|300|307|304|301 locations string[] Return Type Description error?