Record representing the common-response to be returned.


Additional headers to be included in the `http:Response`

headers

Content to be included in the `http:Response` body

string

body

CommonResponse

Error

ListenerError

Represents a resource-discovery failed error.


ResourceDiscoveryFailedError

Represents a websub service execution error.


ServiceExecutionError

Represents the subscription-delete action from the `subscriber`.


SubscriptionDeletedError

SubscriptionDeniedError

Represents a subscription-initiation failed error.


SubscriptionInitiationError

Represents a subscription verificatation error.


SubscriptionVerificationError

Represents a unsubscription verificatation error.


UnsubscriptionVerificationError

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`.


Initiliazes the `websub:DiscoveryService` endpoint.
```ballerina
websub:DiscoveryService discoveryServiceEp = check new ("https://sample.discovery.com");
```



init

discoveryUrl

config

ClientConfiguration

The `websub:DiscoveryService` or an `websub:Error` if the initialization failed


Discovers the URLs of the hub and topic defined by a resource URL.
```ballerina
[string, string] discoveryDetails = check discoveryServiceEp->discoverResourceUrls(expectedMediaTypes, expectedLanguageTypes);
```



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 `websub:ResourceDiscoveryFailedError` if not


DiscoveryService

The HTTP based client for WebSub subscription and unsubscription.


Initializes the `websub:SubscriptionClient` instance.
```ballerina
websub:SubscriptionClient subscriptionClientEp = check new ("https://sample.hub.com");
```



The URL at which the subscription should be changed


Optional `http:ClientConfiguration` for the underlying client


The `websub:SubscriptionClient` or an `websub:Error` if the initialization failed


Sends a subscription request to the provided `hub`.
```ballerina
websub:SubscriptionChangeResponse response = check subscriberClientEp->subscribe(subscriptionRequest);
```



subscribe

The request payload containing the subscription details


subscriptionRequest

SubscriptionChangeRequest

The `websub:SubscriptionChangeResponse` indicating that the subscription initiation was successful
or else an `websub:SubscriptionInitiationError`


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


unsubscribe

The request payload containing the unsubscription details


unsubscriptionRequest

The `websub:SubscriptionChangeResponse` indicating that the unsubscription initiation was successful
or else an `websub:SubscriptionInitiationError`


SubscriptionClient

## Overview

This module provides APIs for a WebSub Subscriber Service.

[**WebSub**](https://www.w3.org/TR/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 request. Hubs then distribute new and updated content to subscribers when it becomes available. WebSub was previously known as PubSubHubbub.

[**WebSub Subscriber**](https://www.w3.org/TR/websub/#subscriber) is an implementation that discovers the `hub` and `topic URL` of a given `resource URL`, subscribes to updates at the hub, and accepts content distribution requests from the `hub`.

### 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 the 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 the [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 
the 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.

#### Subscribing

* The WebSub Subscriber provides the mechanism to subscribe in a `hub` to a given `topic URL`. 
```ballerina
@websub:SubscriberServiceConfig {
    target: ["<HUB_URL>", "<TOPIC_URL>"], 
    leaseSeconds: 36000
} 
service /subscriber on new websub:Listener(9090) {
    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 onUnsubscriptionVerification(websub:UnsubscriptionVerification msg)
                        returns websub:UnsubscriptionVerificationSuccess|websub:UnsubscriptionVerificationError {
        // implement unsubscription intent verification logic here
        return websub:UNSUBSCRIPTION_VERIFICATION_SUCCESS;
    }

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

#### Resource Discovery

* The WebSub Subscriber also provides the mechanism to discover the `hub` and `topic URL` resources dynamically via the provided `resource URL` and initiates the subscription.
```ballerina
@websub:SubscriberServiceConfig {
    target: "RESOURCE_URL", 
    leaseSeconds: 36000
} 
service /subscriber on new websub:Listener(9090) {
    remote function onEventNotification(websub:ContentDistributionMessage event) 
                        returns websub:Acknowledgement|websub:SubscriptionDeletedError? {
        // implement on event notification logic here
        return websub:ACKNOWLEDGEMENT;
    }

    // other remote methods are optional to be implemented
}
```

#### Dynamic URI Generation

* The service path for a WebSub Subscriber is optional. The WebSub Subscriber service has the capability to generate the service path dynamically.
```ballerina
@websub:SubscriberServiceConfig {
    target: "RESOURCE_URL", 
    leaseSeconds: 36000
} 
service on new websub:Listener(9090) {
    remote function onEventNotification(websub:ContentDistributionMessage event) 
                        returns websub:Acknowledgement|websub:SubscriptionDeletedError? {
        // implement on event notification logic here
        return websub:ACKNOWLEDGEMENT;
    }

    // other remote methods are optional to be implemented
}
```

#### Running Subscriber Service Locally

* [**ngrok**](https://ngrok.com/) is a TCP Tunneling software, which is used to expose services running locally in the public network.
* If you want to run the subscriber service in your local machine, you could use **ngrok** to expose it to the public network.
* First, [download and install](https://ngrok.com/download) **ngrok**.
* Run the following command to expose the local port `9090` to the public network via `HTTPS`. For information, see the [ngrok documentation](https://ngrok.com/docs#http-bind-tls)).
```bash
ngrok http -bind-tls=true 9090
```
* Extract the public URL provided by **ngrok** and provide it as the callback URL for the subscriber service.
```ballerina
@websub:SubscriberServiceConfig {
    target: "RESOURCE_URL", 
    leaseSeconds: 36000,
    callback: "<NGROK_PUBLIC_URL>",
    appendServicePath: true
} 
service on new websub:Listener(9090) {
    remote function onEventNotification(websub:ContentDistributionMessage event) 
                        returns websub:Acknowledgement|websub:SubscriptionDeletedError? {
        // implement on event notification logic here
        return websub:ACKNOWLEDGEMENT;
    }

    // other remote methods are optional to be implemented
}
```

#### Unsubscribing from the Hub

* The WebSub Subscriber has the capability to initiate unsubscription flow on Subscriber termination.
```ballerina
websub:ListenerConfiguration listenerConfigs = {
    gracefulShutdownPeriod: 15
};

@websub:SubscriberServiceConfig {
    target: ["https://sample.hub.com", "https://sample.topic1.com"], 
    leaseSeconds: 36000,
    // By default this is set to `false`, hence subscriber on default mode would not initiate unsubscription flow
    unsubscribeOnShutdown: true
}
service /subscriber on new websub:Listener(9090, listenerConfigs)  {
    isolated remote function onEventNotification(websub:ContentDistributionMessage event) 
                        returns websub:Acknowledgement {
        // implement logic here
        return websub:ACKNOWLEDGEMENT;
    }

    // other remote methods are optional to be implemented
}
``` 

# Returning Errors from Remote Methods

* Remote functions in `websub:SubscriberService` can return `error` type.
```ballerina
@websub:SubscriberServiceConfig {
    target: "RESOURCE_URL", 
    leaseSeconds: 36000,
    callback: "<NGROK_PUBLIC_URL>",
    appendServicePath: true
} 
service on new websub:Listener(9090) {
    remote function onEventNotification(websub:ContentDistributionMessage event) 
                        returns websub:Acknowledgement|websub:SubscriptionDeletedError|error? {
        boolean isValidRequest = check validateRequest(event);
        if isValidRequest {
            // implement on event notification logic here
            return websub:ACKNOWLEDGEMENT;
        }
    
    }

    // other remote methods are optional to be implemented
}

function validateRequest(websub:ContentDistributionMessage event) returns boolean|error {
    // validation logic 
}
```

* For each remote method `error` return has a different meaning. Following table depicts the meaning inferred from `error` returned from all available remote methods.

| Method        | Interpreted meaning for Error Return |
| ----------- | ---------------- |
| onSubscriptionValidationDenied | Successfull acknowledgement|
| onSubscriptionVerification | Subscription verification failure|
| onUnsubscriptionVerification | Unsubscription verification failure|
| onEventNotification | Successfull acknowledgement|


Returns the value of the specified header. If the specified header key maps to multiple values, the first of
these values is returned.



getHeader

Current `websub:ContentDistributionMessage` object


ContentDistributionMessage

headerName

The first header value for the specified header name or the `http:HeaderNotFoundError` if the header is not
found.


HeaderNotFoundError

Gets all the header values to which the specified header key maps to.



getHeaders

The header values the specified header key maps to or the `http:HeaderNotFoundError` if the header is not
found.


Represents a Subscriber Service listener endpoint.


Initiliazes `websub:Listener` instance.
```ballerina
listener websub:Listener websubListenerEp = check new (9090);
```



Port number or a `http:Listener` instance


listenTo

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


ListenerConfiguration

The `websub:Listener` or an `websub:Error` if the initialization failed


Attaches the provided `websub:SubscriberService` to the `websub:Listener`.
```ballerina
check websubListenerEp.attach('service, "/subscriber");
```



attach

'service

SubscriberService

name

An `websub:Error`, if an error occurred during the service attaching process or else `()`


Attaches the provided Service to the `websub:Listener` with custom `websub:SubscriberServiceConfiguration`.
```ballerina
check websubListenerEp.attachWithConfig('service, {
   target: "http://0.0.0.0:9191/common/discovery",
   leaseSeconds: 36000
}, "/subscriber");
```



attachWithConfig

Custom `websub:SubscriberServiceConfiguration` which should be incorporated into the provided Service 


configuration

Detaches the provided `websub:SubscriberService` from the `websub:Listener`.
```ballerina
check websubListenerEp.detach('service);
```



detach

An `websub:Error`, if an error occurred during the service detaching process or else `()`


Starts the registered service programmatically..
```ballerina
check websubListenerEp.'start();
```



'start

An `websub:Error`, if an error occurred during the listener starting process or else `()`


Stops the service listener gracefully. Already-accepted requests will be served before connection closure.
```ballerina
check websubListenerEp.gracefulStop();
```



gracefulStop

An `websub:Error`, if an error occurred during the listener stopping process or else `()`


Stops the service listener immediately.
```ballerina
check websubListenerEp.immediateStop();
```



immediateStop

Listener

Record representing the subscription-denial/content-distribution acknowledgement.


Acknowledgement

Record representing the content-distribution request.



Request headers retrieved from the original `HTTP Request`


Content-type header value of the original `HTTP Request`


contentType

content

json

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



Provides a set of configurations for HTTP service endpoints.


host

Configurations related to HTTP/1.x protocol

http1Settings

The SSL configurations for the service endpoint. This needs to be configured in order to
communicate through HTTPS.

secureSocket

Highest HTTP version supported by the endpoint

httpVersion

Period of time in seconds that a connection waits for a read/write operation. Use value 0 to
disable timeout

timeout

The server name which should appear as a response header

server

Configurations associated with inbound request size limits

requestLimits

interceptors

The time period in seconds to wait for unsubscription verification


gracefulShutdownPeriod

decimal

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


appendServicePath

boolean

This flag notifies whether or not to initiate unsubscription when the service is shutting down


unsubscribeOnShutdown

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


httpConfig

HTTP client configurations for resource discovery


discoveryConfig

accept

acceptLanguage

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 intent verification request-body.



The `hub.mode` parameter (subscribe / unsubscribe)


hubMode

hubTopic

The `hub.challenge` parameter used for verification


hubChallenge

The `hub.lease_seconds` parameter used to validate the expiration of subscription
