Module websub
ballerina/websub Ballerina library
Functions
getHeader
function getHeader(ContentDistributionMessage msg, string headerName) returns string|HeaderNotFoundErrorReturns the value of the specified header. If the specified header key maps to multiple values, the first of these values is returned.
Parameters
- msg ContentDistributionMessage - Current
websub:ContentDistributionMessageobject
- headerName string - The header name
Return Type
- string|HeaderNotFoundError - The first header value for the specified header name or the
http:HeaderNotFoundErrorif the header is not found.
getHeaders
function getHeaders(ContentDistributionMessage msg, string headerName) returns string[]|HeaderNotFoundErrorGets all the header values to which the specified header key maps to.
Parameters
- msg ContentDistributionMessage - Current
websub:ContentDistributionMessageobject
- headerName string - The header name
Return Type
- string[]|HeaderNotFoundError - The header values the specified header key maps to or the
http:HeaderNotFoundErrorif the header is not found.
Clients
websub: DiscoveryService
Represents resource-discovery service which identify the hub and topic from resource-URL.
Constructor
Initiliazes the websub:DiscoveryService endpoint.
websub:DiscoveryService discoveryServiceEp = check new ("https://sample.discovery.com");
init (string discoveryUrl, *ClientConfiguration config)- discoveryUrl string -
- config *ClientConfiguration -
discoverResourceUrls
function discoverResourceUrls(string?|string[] expectedMediaTypes, string?|string[] expectedLanguageTypes) returns [string, string]|ResourceDiscoveryFailedErrorDiscovers the URLs of the hub and topic defined by a resource URL.
[string, string] discoveryDetails = check discoveryServiceEp->discoverResourceUrls(expectedMediaTypes, expectedLanguageTypes);
Parameters
Return Type
- [string, string]|ResourceDiscoveryFailedError - A
(hub, topic)as a(string, string)if successful or else anwebsub:ResourceDiscoveryFailedErrorif not
websub: SubscriptionClient
The HTTP based client for WebSub subscription and unsubscription.
Constructor
Initializes the websub:SubscriptionClient instance.
websub:SubscriptionClient subscriptionClientEp = check new ("https://sample.hub.com");
init (string url, *ClientConfiguration config)- url string - The URL at which the subscription should be changed
- config *ClientConfiguration - Optional
ClientConfigurationfor the underlying client
subscribe
function subscribe(SubscriptionChangeRequest subscriptionRequest) returns SubscriptionChangeResponse|SubscriptionInitiationErrorSends a subscription request to the provided hub.
websub:SubscriptionChangeResponse response = check subscriberClientEp->subscribe(subscriptionRequest);
Parameters
- subscriptionRequest SubscriptionChangeRequest - The request payload containing the subscription details
Return Type
- SubscriptionChangeResponse|SubscriptionInitiationError - The
websub:SubscriptionChangeResponseindicating that the subscription initiation was successful or else anwebsub:SubscriptionInitiationError
unsubscribe
function unsubscribe(SubscriptionChangeRequest unsubscriptionRequest) returns SubscriptionChangeResponse|SubscriptionInitiationErrorSends an unsubscription request to a WebSub Hub.
websub:SubscriptionChangeResponse response = check subscriberClientEp->unsubscribe(subscriptionRequest);
Parameters
- unsubscriptionRequest SubscriptionChangeRequest - The request payload containing the unsubscription details
Return Type
- SubscriptionChangeResponse|SubscriptionInitiationError - The
websub:SubscriptionChangeResponseindicating that the unsubscription initiation was successful or else anwebsub:SubscriptionInitiationError
Service types
websub: SubscriberService
The WebSub service type.
Variables
websub: ACKNOWLEDGEMENT
Common response, which could be used for websub:Acknowledgement.
websub: SUBSCRIPTION_VERIFICATION_SUCCESS
Common response, which could be used for websub:SubscriptionVerificationSuccess.
websub: SUBSCRIPTION_VERIFICATION_ERROR
Common response, which could be used for websub:SubscriptionVerificationError.
websub: UNSUBSCRIPTION_VERIFICATION_SUCCESS
Common response, which could be used for websub:UnsubscriptionVerificationSuccess.
websub: UNSUBSCRIPTION_VERIFICATION_ERROR
Common response, which could be used for websub:UnsubscriptionVerificationError.
websub: SUBSCRIPTION_DELETED_ERROR
Common response, which could be used for websub:SubscriptionDeletedError.
Listeners
websub: Listener
Represents a Subscriber Service listener endpoint.
Constructor
Initiliazes websub:Listener instance.
listener websub:Listener websubListenerEp = check new (9090);
init (int|Listener listenTo, *ListenerConfiguration config)- listenTo int|Listener - Port number or a
http:Listenerinstance
- config *ListenerConfiguration - Custom
websub:ListenerConfigurationto be provided to underlying HTTP Listener
attach
function attach(SubscriberService 'service, string[]|string? name) returns Error?Attaches the provided websub:SubscriberService to the websub:Listener.
check websubListenerEp.attach('service, "/subscriber");
Parameters
- 'service SubscriberService -
Return Type
- Error? - An
websub:Error, if an error occurred during the service attaching process or else()
attachWithConfig
function attachWithConfig(SubscriberService 'service, SubscriberServiceConfiguration configuration, string[]|string? name) returns Error?Attaches the provided Service to the websub:Listener with custom websub:SubscriberServiceConfiguration.
check websubListenerEp.attachWithConfig('service, { target: "http://0.0.0.0:9191/common/discovery", leaseSeconds: 36000 }, "/subscriber");
Parameters
- 'service SubscriberService -
- configuration SubscriberServiceConfiguration - Custom
websub:SubscriberServiceConfigurationwhich should be incorporated into the provided Service
Return Type
- Error? - An
websub:Error, if an error occurred during the service attaching process or else()
detach
function detach(SubscriberService 'service) returns Error?Detaches the provided websub:SubscriberService from the websub:Listener.
check websubListenerEp.detach('service);
Parameters
- 'service SubscriberService -
Return Type
- Error? - An
websub:Error, if an error occurred during the service detaching process or else()
'start
function 'start() returns Error?Starts the registered service programmatically..
check websubListenerEp.'start();
Return Type
- Error? - An
websub:Error, if an error occurred during the listener starting process or else()
gracefulStop
function gracefulStop() returns Error?Stops the service listener gracefully. Already-accepted requests will be served before connection closure.
check websubListenerEp.gracefulStop();
Return Type
- Error? - An
websub:Error, if an error occurred during the listener stopping process or else()
immediateStop
function immediateStop() returns Error?Stops the service listener immediately.
check websubListenerEp.immediateStop();
Return Type
- Error? - An
websub:Error, if an error occurred during the listener stopping process or else()
Annotations
websub: SubscriberServiceConfig
serviceWebSub Subscriber Configuration for the service, indicating subscription related parameters.
Records
websub: Acknowledgement
Record representing the subscription-denial/content-distribution acknowledgement.
Fields
websub: ClientConfiguration
Record to represent the client configuration for the SubscriptionClient/DiscoveryService.
Fields
- httpVersion HttpVersion(default http:HTTP_2_0) - 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
- followRedirects? FollowRedirects - Configurations associated with Redirection
- 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
websub: ContentDistributionMessage
Record representing the content-distribution request.
Fields
- contentType string?(default ()) - Content-type header value of the original
HTTP Request
websub: ListenerConfiguration
Provides a set of configurations for configure the underlying HTTP listener of the WebSub listener.
Fields
- gracefulShutdownPeriod decimal(default 20) - The time period in seconds to wait for unsubscription verification
websub: SubscriberServiceConfiguration
Configuration for a WebSubSubscriber service.
Fields
- leaseSeconds? int - The period for which the subscription is expected to be active
- callback? string - The callback URL for subscriber-service
- secret? string - The secret to be used for authenticated content distribution
- appendServicePath boolean(default false) - This flag notifies whether or not to append service-path to callback-url
- unsubscribeOnShutdown boolean(default false) - This flag notifies whether or not to initiate unsubscription when the service is shutting down
- httpConfig? ClientConfiguration - The configuration for the subscriber client used to interact with the discovered/specified hub
- discoveryConfig? record {| accept string|string[], acceptLanguage string|string[], httpConfig ClientConfiguration |} - HTTP client configurations for resource discovery
- servicePathreadonly byte[](default []) - The generated service-path if the service-path is not provided. This is auto-generated at the compile-time.
websub: SubscriptionChangeRequest
Record representing a WebSub subscription change request-body.
Fields
- topic string(default "") - The topic for which the subscription/unsubscription request is sent
- callback string(default "") - The callback which should be registered/unregistered for the subscription/unsubscription request sent
- leaseSeconds int(default 0) - The lease period for which the subscription is expected to be active
- secret string(default "") - The secret to be used for authenticated content distribution with this subscription
websub: SubscriptionChangeResponse
Record representing subscription/unsubscription details if a subscription/unsubscription request is successful.
Fields
- hub string(default "") - The hub at which the subscription/unsubscription was successful
- topic string(default "") - The topic for which the subscription/unsubscription was successful
- response Response - The response from the hub to the subscription/unsubscription request
websub: SubscriptionVerification
Record representing the subscription intent verification request-body.
Fields
- hubMode string - The
hub.modeparameter (subscribe / unsubscribe)
- hubTopic string - The topic URL
- hubChallenge string - The
hub.challengeparameter used for verification
- hubLeaseSeconds string? - The
hub.lease_secondsparameter used to validate the expiration of subscription
websub: SubscriptionVerificationSuccess
Record representing the subscription intent verification success.
Fields
websub: UnsubscriptionVerification
Record representing the unsubscription intent verification request-body.
Fields
- hubMode string - The
hub.modeparameter (subscribe / unsubscribe)
- hubTopic string - The topic URL
- hubChallenge string - The
hub.challengeparameter used for verification
- hubLeaseSeconds string? - The
hub.lease_secondsparameter used to validate the expiration of subscription
websub: UnsubscriptionVerificationSuccess
Record representing the unsubscription intent verification success.
Fields
Errors
websub: Error
Represents a webSub distinct error.
websub: ListenerError
Represents a listener errors.
websub: ResourceDiscoveryFailedError
Represents a resource-discovery failed error.
websub: ServiceExecutionError
Represents a websub service execution error.
websub: SubscriptionDeletedError
Represents the subscription-delete action from the subscriber.
websub: SubscriptionDeniedError
Represents a subscription-denied error.
websub: SubscriptionInitiationError
Represents a subscription-initiation failed error.
websub: SubscriptionVerificationError
Represents a subscription verificatation error.
websub: UnsubscriptionVerificationError
Represents a unsubscription verificatation error.