Module websubhub
ballerina/websubhub Ballerina library
Classes
websubhub: StatusOK
Response status OK.
Fields
- code int - Status code value
- code STATUS_OK(default http:STATUS_OK) - Status code for action
websubhub: StatusPermanentRedirect
Response status Permanent Redirect.
Fields
- code int - Status code value
- code STATUS_PERMANENT_REDIRECT(default http:STATUS_PERMANENT_REDIRECT) - Status code for action
websubhub: StatusTemporaryRedirect
Response status Temporary Redirect.
Fields
- code int - Status code value
- code STATUS_TEMPORARY_REDIRECT(default http:STATUS_TEMPORARY_REDIRECT) - Status code for action
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:Subscriptionrecord, which contains the details of thesubscriber
- config *ClientConfiguration - The
websubhub:ClientConfigurationfor the underlying client
notifyContentDistribution
function notifyContentDistribution(ContentDistributionMessage message) returns ContentDistributionSuccess|SubscriptionDeletedError|ErrorDistributes the published content to the subscribers.
ContentDistributionSuccess publishUpdate = check websubHubClientEP->notifyContentDistribution({ content: "This is sample content" });
Parameters
- message ContentDistributionMessage - Content to be distributed to the topic subscriber
Return Type
- ContentDistributionSuccess|SubscriptionDeletedError|Error - An
websubhub:Errorif an exception occurred, awebsubhub:SubscriptionDeletedErrorif the subscriber responded withHTTP 410, or else awebsubhub:ContentDistributionSuccessfor successful content delivery
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:ClientConfigurationfor the underlying client or else()
registerTopic
function registerTopic(string topic) returns TopicRegistrationSuccess|TopicRegistrationErrorRegisters a topic in a Ballerina WebSub Hub to which the subscribers can subscribe and the publisher will publish updates.
websubhub:TopicRegistrationSuccess response = check publisherClient->registerTopic("http://websubpubtopic.com");
Parameters
- topic string - The topic to register
Return Type
- TopicRegistrationSuccess|TopicRegistrationError - A
websubhub:TopicRegistrationErrorif an error occurred registering the topic or elsewebsubhub:TopicRegistrationSuccess
deregisterTopic
function deregisterTopic(string topic) returns TopicDeregistrationSuccess|TopicDeregistrationErrorDeregisters a topic in a Ballerina WebSub Hub.
websubhub:TopicDeregistrationSuccess response = check publisherClient->deregisterTopic("http://websubpubtopic.com");
Parameters
- topic string - The topic to deregister
Return Type
- TopicDeregistrationSuccess|TopicDeregistrationError - A
websubhub:TopicDeregistrationErrorif an error occurred un registering the topic or elsewebsubhub:TopicDeregistrationSuccess
publishUpdate
function publishUpdate(string topic, map<string>|string|xml|json|byte[] payload, string? contentType) returns Acknowledgement|UpdateMessageErrorPublishes an update to a remote Ballerina WebSub Hub.
websubhub:Acknowledgement response = check publisherClient->publishUpdate("http://websubpubtopic.com",{"action": "publish", "mode": "remote-hub"});
Parameters
- topic string - The topic for which the update occurred
- contentType string? (default ()) - The type of the update content to set as the
ContentTypeheader
Return Type
- Acknowledgement|UpdateMessageError - A
websubhub:UpdateMessageErrorif an error occurred with the update or elsewebsubhub:Acknowledgement
notifyUpdate
function notifyUpdate(string topic) returns Acknowledgement|UpdateMessageErrorNotifies a remote WebSubHub from which an update is available to fetch for hubs that require publishing.
websubhub:Acknowledgement|websubhub:UpdateMessageError response = check publisherClient->notifyUpdate("http://websubpubtopic.com");
Parameters
- topic string - The topic for which the update occurred
Return Type
- Acknowledgement|UpdateMessageError - A
websubhub:UpdateMessageErrorif an error occurred with the notification or elsewebsubhub:Acknowledgement
Service types
websubhub: Service
The WebSubHub service type.
Constants
websubhub: COMPRESSION_ALWAYS
Always set accept-encoding/content-encoding in outbound request/response.
websubhub: COMPRESSION_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
Never set accept-encoding/content-encoding header in outbound request/response.
Enums
websubhub: MessageType
Enum to differentiate the type of the content-update message.
Members
topictopicVariables
websubhub: TOPIC_REGISTRATION_SUCCESS
Common response, which could be used for websubhub:TopicRegistrationSuccess.
websubhub: TOPIC_REGISTRATION_ERROR
Common response, which could be used for websubhub:TopicRegistrationError.
websubhub: TOPIC_DEREGISTRATION_SUCCESS
Common response, which could be used for websubhub:TopicDeregistrationSuccess.
websubhub: TOPIC_DEREGISTRATION_ERROR
Common response, which could be used for websubhub:TopicDeregistrationError.
websubhub: ACKNOWLEDGEMENT
Common response, which could be used for websubhub:Acknowledgement.
websubhub: UPDATE_MESSAGE_ERROR
Common response, which could be used for websubhub:UpdateMessageError.
websubhub: SUBSCRIPTION_ACCEPTED
Common response, which could be used for websubhub:SubscriptionAccepted.
websubhub: BAD_SUBSCRIPTION_ERROR
Common response, which could be used for websubhub:BadSubscriptionError.
websubhub: INTERNAL_SUBSCRIPTION_ERROR
Common response, which could be used for websubhub:InternalSubscriptionError.
websubhub: SUBSCRIPTION_DENIED_ERROR
Common response, which could be used for websubhub:SubscriptionDeniedError.
websubhub: UNSUBSCRIPTION_ACCEPTED
Common response, which could be used for websubhub:UnsubscriptionAccepted.
websubhub: BAD_UNSUBSCRIPTION_ERROR
Common response, which could be used for websubhub:BadUnsubscriptionError.
websubhub: INTERNAL_UNSUBSCRIPTION_ERROR
Common response, which could be used for websubhub:InternalUnsubscriptionError.
websubhub: UNSUBSCRIPTION_DENIED_ERROR
Common response, which could be used for websubhub:UnsubscriptionDeniedError.
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:Listenerinstance
- config *ListenerConfiguration - Custom
websubhub:ListenerConfigurationto be provided to the underlying HTTP listener
attach
Attaches the provided websubhub:Service to the websubhub:Listener.
check hubListenerEp.attach('service, "/hub");
Parameters
- 'service Service - The
websubhub:Serviceobject to attach
Return Type
- Error? - An
websubhub:Errorif an error occurred during the service attaching process or else()
detach
Detaches the provided websubhub:Service from the websubhub:Listener.
check hubListenerEp.detach('service);
Parameters
- s Service - The
websubhub:Serviceobject to be detached
Return Type
- Error? - An
websubhub:Errorif an error occurred during the service detaching process or else()
'start
function 'start() returns Error?Starts the registered service programmatically.
check hubListenerEp.'start();
Return Type
- Error? - An
websubhub:Errorif an error occurred during the listener-starting process or else()
gracefulStop
function gracefulStop() returns Error?Gracefully stops the hub listener. Already-accepted requests will be served before the connection closure.
check hubListenerEp.gracefulStop();
Return Type
- Error? - An
websubhub:Errorif an error occurred during the listener-stopping process
immediateStop
function immediateStop() returns Error?Stops the service listener immediately.
check hubListenerEp.immediateStop();
Return Type
- Error? - An
websubhub:Errorif an error occurred during the listener-stopping process or else()
Annotations
websubhub: ServiceConfig
serviceWebSub Hub Configuration for the service.
Records
websubhub: Acknowledgement
Record to represent the acknowledgement of content updated by the publisher.
Fields
- Fields Included from *CommonResponse
- statusCode int(default http:STATUS_OK) - HTTP status code for the response
websubhub: ClientConfiguration
Record to represent the client configuration for the HubClient/PublisherClient.
Fields
- httpVersion HttpVersion(default HTTP_1_1) - The HTTP version understood by the client
- http1Settings ClientHttp1Settings(default {}) - Configurations related to HTTP/1.x protocol
- http2Settings ClientHttp2Settings(default {}) - Configurations related to HTTP/2 protocol
- timeout decimal(default 60) - The maximum time to wait (in seconds) for a response before closing the connection
- poolConfig? PoolConfiguration - Configurations associated with request pooling
- auth? ClientAuthConfig - Configurations related to client authentication
- retryConfig? RetryConfig - Configurations associated with retrying
- responseLimits ResponseLimitConfigs(default {}) - Configurations associated with inbound response size limits
- secureSocket? ClientSecureSocket - SSL/TLS related options
- circuitBreaker? CircuitBreakerConfig - Configurations associated with the behaviour of the Circuit Breaker
websubhub: CommonResponse
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
websubhub: ContentDistributionMessage
Record to represent a WebSub content delivery.
Fields
- contentType string?(default ()) - The content-type of the payload
websubhub: ContentDistributionSuccess
Record to represent the successful WebSub content delivery.
Fields
- Fields Included from *CommonResponse
- statusreadonly StatusOK(default STATUS_OK_OBJ) - Status of the request processing. This is
200 OKby default since this is a successful response
websubhub: ListenerConfiguration
Provides a set of configurations for configure the underlying HTTP listener of the WebSubHub listener.
websubhub: ServiceConfiguration
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
hubto which the subscriber has subscribed
- hubMode string - Current
hubaction
- 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
- Fields Included from *CommonResponse
- 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 -
- mediaType string|() -
- anydata... -
- codereadonly STATUS_PERMANENT_REDIRECT(default http:STATUS_PERMANENT_REDIRECT) - Status code for the action
websubhub: SubscriptionTemporaryRedirect
Record to represent temporary subscription redirects.
Fields
- redirectUrls string[] - URLs to which the subscription has been redirected
- statusCode int -
- mediaType string|() -
- anydata... -
- codereadonly STATUS_TEMPORARY_REDIRECT(default http:STATUS_TEMPORARY_REDIRECT) - Status code of the action
websubhub: TopicDeregistration
Record to represent the topic-deregistration request body.
Fields
- topic string -
Topic, which should be unregistered from thehub
- hubMode string(default MODE_DEREGISTER) - Current
hubaction
websubhub: TopicDeregistrationSuccess
Record to represent the successful topic deregistration.
Fields
- Fields Included from *CommonResponse
- statusCode int(default http:STATUS_OK) - HTTP status code for the response
websubhub: TopicRegistration
Record to represent the topic-registration request body.
Fields
- topic string -
Topic, which should be registered in thehub
- hubMode string(default MODE_REGISTER) - Current
hubaction
websubhub: TopicRegistrationSuccess
Record to represent the successful topic registration.
Fields
- Fields Included from *CommonResponse
- 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
hubaction
- 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
- Fields Included from *CommonResponse
- 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
websubhub: VerifiedSubscription
Record to represent the completed subscription.
Fields
- Fields Included from *Subscription
- verificationSuccess boolean(default true) - Flag to notify whether a subscription verification is successfull
websubhub: VerifiedUnsubscription
Record to represent a completed unsubscription.
Fields
- Fields Included from *Unsubscription
- verificationSuccess boolean(default true) - Flag to notify whether a unsubscription verification is successfull
Errors
websubhub: BadSubscriptionError
Error type representing the errors in the subscription request.
websubhub: BadUnsubscriptionError
Error type representing the errors in the unsubscription request.
websubhub: ContentDeliveryError
Error type representing the internal errors in the content distribution.
websubhub: Error
Represents a websubhub distinct error.
websubhub: InternalSubscriptionError
Error type representing the internal errors in the subscription action.
websubhub: InternalUnsubscriptionError
Error type representing the internal errors in the unsubscription action.
websubhub: ServiceExecutionError
Represents a websubhub service execution error.
websubhub: SubscriptionDeletedError
Error type representing the subscriber ending the subscription
by sending HTTP 410 for the content delivery response.
websubhub: SubscriptionDeniedError
Error type representing the validation errors in the subscription request body.
websubhub: TopicDeregistrationError
Error type representing the errors in the topic unregistration action.
websubhub: TopicRegistrationError
Error type representing the errors in the topic registration action.
websubhub: UnsubscriptionDeniedError
Error type representing the validation errors in the unsubscription request body.
websubhub: UpdateMessageError
Error type representing the errors in the content update request.
Union types
websubhub: Compression
Compression
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