Error

WebSub Subscriber Configuration for the service, indicating subscription related parameters.


SubscriberServiceConfig

SubscriberServiceConfiguration

Represents resource-discovery service which identify the `hub` and `topic` from `resource-URL`.


Invoked during the initialization of a `websub:DiscoveryService`



init

discoveryUrl

string

{@code http:ClientConfiguration} if present to be used to
initialize underlying {@code http:Client}


publisherClientConfig

ClientConfiguration

error

Discovers the hub and topic URLs defined by a resource URL.



discoverResourceUrls

The expected media types for the subscriber client


expectedMediaTypes

The expected language types for the subscriber client


expectedLanguageTypes

A `(hub, topic)` as a `(string, string)` if successful or else an `error` if not


DiscoveryService

The HTTP based client for WebSub subscription and unsubscription.


Initializes the `websub:SubscriptionClient`.



The URL at which the subscription should be changed


The `http:ClientConfiguration` for the underlying client or `()`


config

Sends a subscription request to a WebSub Hub.
```ballerina
websub:SubscriptionChangeResponse|error response = websubHubClientEP->subscribe(subscriptionRequest);
```



subscribe

The `SubscriptionChangeRequest` containing the subscription details


subscriptionRequest

SubscriptionChangeRequest

The `SubscriptionChangeResponse` indicating subscription details if the request was successful
or else an `error` if an error occurred with the subscription request


Sends an unsubscription request to a WebSub Hub.
```ballerina
websub:SubscriptionChangeResponse|error response = websubHubClientEP->unsubscribe(subscriptionRequest);
```


unsubscribe

The `SubscriptionChangeRequest` containing unsubscription details


unsubscriptionRequest

An unsubscription details if the request was successful or else an `error` if an error occurred
with the unsubscription request


SubscriptionClient

## Package Overview

This package contains an implementation of the W3C [**WebSub**](https://www.w3.org/TR/websub/) recommendation, which facilitates a push-based content delivery/notification mechanism between publishers and subscribers.

This implementation supports introducing WebSub Subscriber, A party interested in receiving update notifications for particular topics.
### 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 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 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](https://www.w3.org/TR/websub/#signing-content).
  
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 updates to the topic and the content to deliver is identified.

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

### Features

#### Subscriber

This package allows introducing a WebSub Subscriber Service with `onSubscriptionVerification`, which accepts HTTP GET requests for intent verification, `onSubscriptionValidationDenied` which accepts subscription denied response from hub and `onEventNotification`, which accepts HTTP POST requests for notifications. The WebSub Subscriber Service provides the following capabilities:
 - When the service is started a subscription request is sent for a hub/topic combination, either specified as annotations or discovered based on the resource URL specified as an annotation.
 - If `onSubscriptionVerification` is not specified, intent verification will be done automatically against the topic specified as an annotation or discovered based on the resource URL specified as an annotation.
 - If `onSubscriptionValidationDenied` is not specified, subscriber service will respond to the incoming request automatically.
 - If `target` is not specified the initial subscription will not happen on service startup.
 - If a `secret` is specified for the subscription, signature validation will be done for authenticated content distribution.

    ```ballerina
    websub:ListenerConfiguration listenerConfigs = {
        secureSocket: {
            key: {
                certFile: "../resource/path/to/public.crt",
                keyFile: "../resource/path/to/private.key"
            }
        }
    };

    listener websub:Listener sslEnabledListener = new(9095, listenerConfigs);

    @websub:SubscriberServiceConfig {
        target: ["<HUB_URL>", "<TOPIC_URL>"], 
        leaseSeconds: 36000,
        secret: "<SECRET>"
    } 
    service /subscriber on sslEnabledListener {
        remote function onSubscriptionValidationDenied(websub:SubscriptionDeniedError msg) returns websub:Acknowledgement? {
            // implement subscription validation denied logic here
            return websub:ACKNOWLEDGEMENT;
        }

        remote function onSubscriptionVerification(websub:SubscriptionVerification msg)
                        returns websub:SubscriptionVerificationSuccess|websub:SubscriptionVerificationError {
            // implement subscription intent verification logic here
            return websub:SUBSCRIPTION_VERIFICATION_SUCCESS;
        }

        remote function onEventNotification(websub:ContentDistributionMessage event) 
                        returns websub:Acknowledgement|websub:SubscriptionDeletedError? {
            // implement on event notification logic here
            return websub:ACKNOWLEDGEMENT;
        }
    }
    ```

Represents a Subscriber Service listener endpoint.


Invoked during the initialization of a `websub:Listener`. Either an `http:Listener` or a port number must be
provided to initialize the listener.



An `http:Listener` or a port number to listen for the service


listenTo

`websub:ListenerConfiguration` to be provided to underlying HTTP Listener


ListenerConfiguration

Attaches the provided Service to the Listener.



attach

The `websub:SubscriberService` object to attach


subscriberService

SubscriberService

name

An `error`, if an error occurred during the service attaching process


Setup the provided Service with given configurations and attaches it to the listener



attachWithConfig

`SubscriberServiceConfiguration` which should be incorporated into the provided Service 


configuration

Detaches the provided Service from the Listener.



detach

An `error`, if an error occurred during the service detaching process


'start

An `error`, if an error occurred during the listener starting process


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



gracefulStop

An `error`, if an error occurred during the listener stopping process


Stops the service listener immediately. It is not implemented yet.



immediateStop

Listener

Record representing the subscription-denial / content-distribution acknowledgement


headers

body

CommonResponse

Acknowledgement

Record representing the content-distribution request.



request headers retrieve from the original `http:Request`


content-type header value of the original `http:Request`


contentType

content

json

ContentDistributionMessage

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


host

http1Settings

secureSocket

httpVersion

timeout

server

requestLimits

Configuration for a WebSubSubscriber service.



The `string` resource URL for which discovery will be initiated to identify the hub and topic,
or a tuple `[hub, topic]` representing a discovered hub and a topic


target

The period for which the subscription is expected to be active


leaseSeconds

callback

The secret to be used for authenticated content distribution


secret

This flag notifies whether or not to append service-path to callback-url


appendServiceUrl

boolean

The configuration for the hub client used to interact with the discovered/specified hub


httpConfig

HTTP client configurations for resource discovery


discoveryConfig

    record {|
        string|string[] accept?;
        string|string[] acceptLanguage?;
        http:ClientConfiguration httpConfig?;
    |} 

Record representing a WebSub subscription change request-body.



The topic for which the subscription/unsubscription request is sent


topic

The callback which should be registered/unregistered for the subscription/unsubscription request sent


The lease period for which the subscription is expected to be active


The secret to be used for authenticated content distribution with this subscription


Record representing subscription/unsubscription details if a subscription/unsubscription request is successful.



The hub at which the subscription/unsubscription was successful


The topic for which the subscription/unsubscription was successful


The response from the hub to the subscription/unsubscription request


response

Response

SubscriptionChangeResponse

Record representing the subscription / unsubscription intent verification request-body.



current hub.mode parameter (subscribe / unsubscribe)


hubMode

hubTopic

hub.challenge parameter used for verification


hubChallenge

hub.lease_seconds parameter used to validate the expiration of subscription


hubLeaseSeconds

SubscriptionVerification

Record representing the subscription / unsubscription intent verification success.


SubscriptionVerificationSuccess

This package contains an implementation of the W3C "WebSub" (https://www.w3.org/TR/websub/) recommendation, which facilitates a push-based content delivery/notification mechanism between publishers and subscribers.
