Standard library

websubhub

Module websubhub

Listener

HubClientPublisherClient

StatusOK
StatusPermanentRedirect
StatusTemporaryRedirect

Service

Acknowledgement
ClientConfiguration
CommonResponse
ContentDistributionMessage
ContentDistributionSuccess
ListenerConfiguration
ServiceConfiguration
Subscription
SubscriptionAccepted
SubscriptionPermanentRedirect
SubscriptionTemporaryRedirect
TopicDeregistration
TopicDeregistrationSuccess
TopicRegistration
TopicRegistrationSuccess
Unsubscription
UnsubscriptionAccepted
UpdateMessage
VerifiedSubscription
VerifiedUnsubscription

MessageType

COMPRESSION_ALWAYS
COMPRESSION_AUTO
COMPRESSION_NEVER

ServiceConfig

Compression

TOPIC_REGISTRATION_SUCCESS
TOPIC_REGISTRATION_ERROR
TOPIC_DEREGISTRATION_SUCCESS
TOPIC_DEREGISTRATION_ERROR
ACKNOWLEDGEMENT
UPDATE_MESSAGE_ERROR
SUBSCRIPTION_ACCEPTED
BAD_SUBSCRIPTION_ERROR
INTERNAL_SUBSCRIPTION_ERROR
SUBSCRIPTION_DENIED_ERROR
UNSUBSCRIPTION_ACCEPTED
BAD_UNSUBSCRIPTION_ERROR
INTERNAL_UNSUBSCRIPTION_ERROR
UNSUBSCRIPTION_DENIED_ERROR

BadSubscriptionError
BadUnsubscriptionError
ContentDeliveryError
Error
InternalSubscriptionError
InternalUnsubscriptionError
ServiceExecutionError
SubscriptionDeletedError
SubscriptionDeniedError
TopicDeregistrationError
TopicRegistrationError
UnsubscriptionDeniedError
UpdateMessageError

ballerina/websubhub

1.6.1

Overview

This module provides APIs for a WebSub Hub service and WebSub Publisher client.

WebSub is a common mechanism for communication between publishers of any kind of web content and their subscribers based on HTTP webhooks. Subscription requests are relayed through hubs, which validate and verify the requests. Hubs then distribute new and updated content to subscribers when it becomes available. WebSub was previously known as PubSubHubbub.

WebSub Hub is an implementation that handles subscription requests and distributes the content to subscribers when the corresponding topic URL has been updated.

WebSub Publisher is an implementation that advertises a topic and hub URL on one or more resource URLs.

Basic flow with WebSub

  1. The subscriber discovers (from the publisher) the topic it needs to subscribe to and the hub(s) that deliver notifications on the updates of the topic.

  2. The subscriber sends a subscription request to one or more discovered hub(s) specifying the discovered topic along with other subscription parameters such as:

    • The callback URL to which the content is expected to be delivered.
    • (Optional) The lease period (in seconds) the subscriber wants the subscription to stay active.
    • (Optional) A secret to use for authenticated content distribution.

  3. The hub sends an intent verification request to the specified callback URL. 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.

  4. The publisher notifies the hub of the updates to the topic and the content to deliver is identified.

  5. The hub delivers the identified content to the subscribers of the topic.

Use websubhub:HubClient

  • WebSub HubClient can be used to distribute the published content to subscribers. The current implementation is based on Ballerina HTTP Client.
Copy
  • The following is a sample usage for WebSub HubClient.
Copy

Use websubhub:PublisherClient

  • The PublisherClient APIs are defined by Ballerina and it has no connection with the WebSub specification. As mentioned earlier, even though the WebSub specification extensively discusses the relationship between the subscriber and hub, it does not discuss much the relationship between the publisher and hub.

  • The following is a sample WebSub Publisher Client.

Copy

Return errors from remote methods

  • Remote functions in websubhub:Service can return error type.
Copy
  • For each remote method error return has a different meaning. Following table depicts the meaning inferred from error returned from all available remote methods.
MethodInterpreted meaning for Error Return
onRegisterTopicTopic registration failure
onDeregisterTopicTopic de-registration failure
onUpdateMessageUpdate message error
onSubscriptionSubscription internal server error
onSubscriptionValidationSubscription validation failure
onSubscriptionIntentVerifiedSubscription intent verification failure
onUnsubscriptionUnsubscription internal server error
onUnsubscriptionValidationUnsubscription validation failure
onUnsubscriptionIntentVerifiedUnsubscription intent verification failure

Listeners

websubhub: Listener

Represents a Service listener endpoint.

Constructor

Initiliazes the websubhub:Listener instance.

listener websubhub:Listener hubListenerEp = check new (9090);

init (int|Listener listenTo, *ListenerConfiguration config)
  • listenTo int|Listener - Port number or an http:Listener instance
  • config *ListenerConfiguration - Custom websubhub:ListenerConfiguration to be provided to the underlying HTTP listener

attach

Isolated Function
function attach(Service 'service, string[]|string? name) returns Error?

Attaches the provided websubhub:Service to the websubhub:Listener.

Copy
Parameters
  • 'service Service - The websubhub:Service object to attach
  • name string[]|string? (default ()) - The path of the service to be hosted
Return Type
  • Error? - An websubhub:Error if an error occurred during the service attaching process or else ()

detach

Isolated Function
function detach(Service s) returns Error?

Detaches the provided websubhub:Service from the websubhub:Listener.

Copy
Parameters
  • s Service - The websubhub:Service object to be detached
Return Type
  • Error? - An websubhub:Error if an error occurred during the service detaching process or else ()

'start

Isolated Function
function 'start() returns Error?

Starts the registered service programmatically.

Copy
Return Type
  • Error? - An websubhub:Error if an error occurred during the listener-starting process or else ()

gracefulStop

Isolated Function
function gracefulStop() returns Error?

Gracefully stops the hub listener. Already-accepted requests will be served before the connection closure.

Copy
Return Type
  • Error? - An websubhub:Error if an error occurred during the listener-stopping process

immediateStop

Isolated Function
function immediateStop() returns Error?

Stops the service listener immediately.

Copy
Return Type
  • Error? - An websubhub:Error if an error occurred during the listener-stopping process or else ()

Clients

websubhub: HubClient

HTTP Based client for WebSub content publishing to subscribers

Constructor

Initializes the websubhub:HubClient.

websubhub:HubClient hubClientEP = check new({
  hub: "https://hub.com",
  hubMode: "subscribe", 
  hubCallback: "http://subscriber.com/callback", 
  hubTopic: "https://topic.com", 
  hubSecret: "key"
});

init (Subscription subscription, *ClientConfiguration config)
  • subscription Subscription - Original websubhub:Subscription record, which contains the details of the subscriber

notifyContentDistribution

Isolated FunctionRemote Function
function notifyContentDistribution(ContentDistributionMessage message) returns ContentDistributionSuccess|SubscriptionDeletedError|Error

Distributes the published content to the subscribers.

Copy
Parameters
Return Type

websubhub: PublisherClient

The HTTP based client for WebSub topic registration and deregistration, and notifying the hub of new updates.

Constructor

Initializes the websub:PublisherClient.

websub:PublisherClient publisherClient = check new("https://sample.hub.com");

init (string url, *ClientConfiguration config)
  • url string - The URL to publish/notify updates
  • config *ClientConfiguration - The websubhub:ClientConfiguration for the underlying client or else ()

registerTopic

Isolated FunctionRemote Function
function registerTopic(string topic) returns TopicRegistrationSuccess|TopicRegistrationError

Registers a topic in a Ballerina WebSub Hub to which the subscribers can subscribe and the publisher will publish updates.

Copy
Parameters
  • topic string - The topic to register
Return Type

deregisterTopic

Isolated FunctionRemote Function
function deregisterTopic(string topic) returns TopicDeregistrationSuccess|TopicDeregistrationError

Deregisters a topic in a Ballerina WebSub Hub.

Copy
Parameters
  • topic string - The topic to deregister
Return Type

publishUpdate

Isolated FunctionRemote Function
function publishUpdate(string topic, map<string>|string|xml|json|byte[] payload, string? contentType) returns Acknowledgement|UpdateMessageError

Publishes an update to a remote Ballerina WebSub Hub.

Copy
Parameters
  • topic string - The topic for which the update occurred
  • contentType string? (default ()) - The type of the update content to set as the ContentType header
Return Type

notifyUpdate

Isolated FunctionRemote Function
function notifyUpdate(string topic) returns Acknowledgement|UpdateMessageError

Notifies a remote WebSubHub from which an update is available to fetch for hubs that require publishing.

Copy
Parameters
  • topic string - The topic for which the update occurred
Return Type

Classes

websubhub: StatusOK

Read Only

Response status OK.

Fields
  • code int - Status code value
  • code STATUS_OK(default http:STATUS_OK) - Status code for action

websubhub: StatusPermanentRedirect

Read Only

Response status Permanent Redirect.

Fields
  • code int - Status code value

websubhub: StatusTemporaryRedirect

Read Only

Response status Temporary Redirect.

Fields
  • code int - Status code value

Object types

websubhub: Service

Distinct

The WebSubHub service type.

Records

websubhub: Acknowledgement

Record to represent the acknowledgement of content updated by the publisher.

Fields
  • statusCode int(default http:STATUS_OK) - HTTP status code for the response

websubhub: ClientConfiguration

Closed record

Record to represent the client configuration for the HubClient/PublisherClient.

Fields
  • httpVersion HttpVersion(default HTTP_1_1) - The HTTP version understood by the client
  • timeout decimal(default 60) - The maximum time to wait (in seconds) for a response before closing the connection
  • retryConfig RetryConfig? - Configurations associated with retrying
  • responseLimits ResponseLimitConfigs(default {}) - Configurations associated with inbound response size limits
  • circuitBreaker CircuitBreakerConfig? - Configurations associated with the behaviour of the Circuit Breaker

websubhub: CommonResponse

Closed record

Record to represent the parent type for all the response records.

Fields
  • statusCode int - HTTP status code for the response
  • mediaType string?(default ()) - Content-Type of the request received
  • headers map<string|string[]>?(default ()) - Additional request headers received to be included in the request

websubhub: ContentDistributionMessage

Closed record

Record to represent a WebSub content delivery.

Fields
  • headers map<string|string[]>?(default ()) - Additional Request headers to include when distributing content
  • contentType string?(default ()) - The content-type of the payload
  • content json|xml|string|byte[]? - The payload to be sent

websubhub: ContentDistributionSuccess

Closed record

Record to represent the successful WebSub content delivery.

Fields
  • statusreadonly StatusOK(default StatusOK) - Status of the request processing. This is 200 OK by default since this is a successful response

websubhub: ListenerConfiguration

Closed record

Provides a set of configurations for configure the underlying HTTP listener of the WebSubHub listener.

Fields

websubhub: ServiceConfiguration

Closed record

Configuration for a WebSub Hub service.

Fields
  • leaseSeconds int? - The period for which the subscription is expected to be active in the hub
  • webHookConfig ClientConfiguration? - HTTP client configurations for subscription/unsubscription intent verification

websubhub: Subscription

Record to represent the subscription request body.

Fields
  • hub string - URL of the hub to which the subscriber has subscribed
  • hubMode string - Current hub action
  • hubCallback string - Callback URL for subscriber to receive distributed content
  • hubTopic string - Topic to which subscriber has subscribed
  • hubLeaseSeconds string?(default ()) - Amount of time in seconds during when the subscription is valid
  • hubSecret string?(default ()) - Secret Key to sign the distributed content

websubhub: SubscriptionAccepted

Record to represent the subscription accepted by the hub.

Fields
  • statusCode int(default http:STATUS_ACCEPTED) - HTTP status code for the response

websubhub: SubscriptionPermanentRedirect

Record to represent the permanent subscription redirects.

Fields
  • redirectUrls string[] - URLs to which the subscription has been redirected
  • statusCode int -
  • anydata... -

websubhub: SubscriptionTemporaryRedirect

Record to represent temporary subscription redirects.

Fields
  • redirectUrls string[] - URLs to which the subscription has been redirected
  • statusCode int -
  • anydata... -

websubhub: TopicDeregistration

Closed record

Record to represent the topic-deregistration request body.

Fields
  • topic string - Topic, which should be unregistered from the hub
  • hubMode string(default MODE_DEREGISTER) - Current hub action

websubhub: TopicDeregistrationSuccess

Record to represent the successful topic deregistration.

Fields
  • statusCode int(default http:STATUS_OK) - HTTP status code for the response

websubhub: TopicRegistration

Closed record

Record to represent the topic-registration request body.

Fields
  • topic string - Topic, which should be registered in the hub
  • hubMode string(default MODE_REGISTER) - Current hub action

websubhub: TopicRegistrationSuccess

Record to represent the successful topic registration.

Fields
  • statusCode int(default http:STATUS_OK) - HTTP status code for the response

websubhub: Unsubscription

Record to represent the unsubscription request body.

Fields
  • hubMode string - Current hub action
  • hubCallback string - Callback URL for subscriber to received distributed content
  • hubTopic string - Topic from which subscriber wants to unsubscribe
  • hubSecret string?(default ()) - Secret Key to sign the distributed content

websubhub: UnsubscriptionAccepted

Record to represent the unsubscription acceptance.

Fields
  • statusCode int(default http:STATUS_ACCEPTED) - HTTP status code for the response

websubhub: UpdateMessage

Record to represent the content update message.

Fields
  • msgType MessageType - Type of the content update message
  • hubTopic string - Topic of which the content should be updated
  • contentType string - Content-Type of the update-message
  • content string|byte[]|json|xml? - Content to be distributed to subscribers

websubhub: VerifiedSubscription

Record to represent the completed subscription.

Fields
  • verificationSuccess boolean(default true) - Flag to notify whether a subscription verification is successfull

websubhub: VerifiedUnsubscription

Record to represent a completed unsubscription.

Fields
  • verificationSuccess boolean(default true) - Flag to notify whether a unsubscription verification is successfull

Enums

websubhub: MessageType

Enum to differentiate the type of the content-update message.

Members

EVENT - Content update in the topic
PUBLISH - Content distribution to the topic

Constants

websubhub: COMPRESSION_ALWAYS

string "ALWAYS"

Always set accept-encoding/content-encoding in outbound request/response.

websubhub: COMPRESSION_AUTO

string "AUTO"

When service behaves as a HTTP gateway inbound request/response accept-encoding option is set as the outbound request/response accept-encoding/content-encoding option.

websubhub: COMPRESSION_NEVER

string "NEVER"

Never set accept-encoding/content-encoding header in outbound request/response.

Annotations

websubhub: ServiceConfig

ServiceConfiguration service

WebSub Hub Configuration for the service.

Types

websubhub: Compression

COMPRESSION_AUTO|COMPRESSION_ALWAYS|COMPRESSION_NEVER

Options to compress using Gzip or deflate.

AUTO: When service behaves as a HTTP gateway inbound request/response accept-encoding option is set as the outbound request/response accept-encoding/content-encoding option ALWAYS: Always set accept-encoding/content-encoding in outbound request/response NEVER: Never set accept-encoding/content-encoding header in outbound request/response

Variables

websubhub: TOPIC_REGISTRATION_SUCCESS

readonly & TopicRegistrationSuccess(default {})

Common response, which could be used for websubhub:TopicRegistrationSuccess.

websubhub: TOPIC_REGISTRATION_ERROR

TopicRegistrationError(default error TopicRegistrationError( "Topic registration failed", statusCode = http:STATUS_OK))

Common response, which could be used for websubhub:TopicRegistrationError.

websubhub: TOPIC_DEREGISTRATION_SUCCESS

readonly & TopicDeregistrationSuccess(default {})

Common response, which could be used for websubhub:TopicDeregistrationSuccess.

websubhub: TOPIC_DEREGISTRATION_ERROR

TopicDeregistrationError(default error TopicDeregistrationError( "Topic deregistration failed!", statusCode = http:STATUS_OK))

Common response, which could be used for websubhub:TopicDeregistrationError.

websubhub: ACKNOWLEDGEMENT

readonly & Acknowledgement(default {})

Common response, which could be used for websubhub:Acknowledgement.

websubhub: UPDATE_MESSAGE_ERROR

UpdateMessageError(default error UpdateMessageError( "Error in accessing content", statusCode = http:STATUS_OK))

Common response, which could be used for websubhub:UpdateMessageError.

websubhub: SUBSCRIPTION_ACCEPTED

readonly & SubscriptionAccepted(default {})

Common response, which could be used for websubhub:SubscriptionAccepted.

websubhub: BAD_SUBSCRIPTION_ERROR

BadSubscriptionError(default error BadSubscriptionError( "Bad subscription request", statusCode = http:STATUS_BAD_REQUEST))

Common response, which could be used for websubhub:BadSubscriptionError.

websubhub: INTERNAL_SUBSCRIPTION_ERROR

InternalSubscriptionError(default error InternalSubscriptionError( "Internal error occurred while processing subscription request", statusCode = http:STATUS_INTERNAL_SERVER_ERROR))

Common response, which could be used for websubhub:InternalSubscriptionError.

websubhub: SUBSCRIPTION_DENIED_ERROR

SubscriptionDeniedError(default error SubscriptionDeniedError( "Subscription denied", statusCode = http:STATUS_NOT_ACCEPTABLE))

Common response, which could be used for websubhub:SubscriptionDeniedError.

websubhub: UNSUBSCRIPTION_ACCEPTED

readonly & UnsubscriptionAccepted(default {})

Common response, which could be used for websubhub:UnsubscriptionAccepted.

websubhub: BAD_UNSUBSCRIPTION_ERROR

BadUnsubscriptionError(default error BadUnsubscriptionError( "Bad unsubscription request", statusCode = http:STATUS_BAD_REQUEST))

Common response, which could be used for websubhub:BadUnsubscriptionError.

websubhub: INTERNAL_UNSUBSCRIPTION_ERROR

InternalUnsubscriptionError(default error InternalUnsubscriptionError( "Internal error occurred while processing unsubscription request", statusCode = http:STATUS_INTERNAL_SERVER_ERROR))

Common response, which could be used for websubhub:InternalUnsubscriptionError.

websubhub: UNSUBSCRIPTION_DENIED_ERROR

UnsubscriptionDeniedError(default error UnsubscriptionDeniedError( "Unsubscription denied", statusCode = http:STATUS_NOT_ACCEPTABLE))

Common response, which could be used for websubhub:UnsubscriptionDeniedError.

Errors

websubhub: BadSubscriptionError

Distinct
Error

Error type representing the errors in the subscription request.

websubhub: BadUnsubscriptionError

Distinct
Error

Error type representing the errors in the unsubscription request.

websubhub: ContentDeliveryError

Distinct
Error

Error type representing the internal errors in the content distribution.

websubhub: Error

Distinct
CommonResponse

Represents a websubhub distinct error.

websubhub: InternalSubscriptionError

Distinct
Error

Error type representing the internal errors in the subscription action.

websubhub: InternalUnsubscriptionError

Distinct
Error

Error type representing the internal errors in the unsubscription action.

websubhub: ServiceExecutionError

Distinct
Error

Represents a websubhub service execution error.

websubhub: SubscriptionDeletedError

Distinct
Error

Error type representing the subscriber ending the subscription by sending HTTP 410 for the content delivery response.

websubhub: SubscriptionDeniedError

Distinct
Error

Error type representing the validation errors in the subscription request body.

websubhub: TopicDeregistrationError

Distinct
Error

Error type representing the errors in the topic unregistration action.

websubhub: TopicRegistrationError

Distinct
Error

Error type representing the errors in the topic registration action.

websubhub: UnsubscriptionDeniedError

Distinct
Error

Error type representing the validation errors in the unsubscription request body.

websubhub: UpdateMessageError

Distinct
Error

Error type representing the errors in the content update request.

Other versions

1.6.2

1.6.1

1.6.01.5.21.5.1
See more...

Terms of service

Privacy policy

Cookie policy

2023 WSO2