HTTP Based client for WebSub content publishing to subscribers


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



init

Original `websubhub:Subscription` record, which contains the details of the `subscriber`


subscription

Subscription

The `websubhub:ClientConfiguration` for the underlying client


config

ClientConfiguration

The `websubhub:HubClient` or an `websubhub:Error` if the initialization failed


Error

Distributes the published content to the subscribers.
```ballerina
ContentDistributionSuccess publishUpdate = check websubHubClientEP->notifyContentDistribution({ content: "This is sample content" });
```



notifyContentDistribution

Content to be distributed to the topic subscriber 


message

ContentDistributionMessage

An `websubhub:Error` if an exception occurred, a `websubhub:SubscriptionDeletedError` if the subscriber responded with `HTTP 410`,
or else a `websubhub:ContentDistributionSuccess` for successful content delivery


ContentDistributionSuccess

SubscriptionDeletedError

HubClient

WebSub Hub Configuration for the service.


ServiceConfig

ServiceConfiguration

code

STATUS_OK

StatusOK

STATUS_PERMANENT_REDIRECT

StatusPermanentRedirect

STATUS_TEMPORARY_REDIRECT

StatusTemporaryRedirect

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


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



string

The `websubhub:ClientConfiguration` for the underlying client or else `()`


The `websubhub:PublisherClient` or an `websubhub:Error` if the initialization failed


Registers a topic in a Ballerina WebSub Hub to which the subscribers can subscribe and the publisher will publish updates.
```ballerina
websubhub:TopicRegistrationSuccess response = check publisherClient->registerTopic("http://websubpubtopic.com");
```



registerTopic

topic

A `websubhub:TopicRegistrationError` if an error occurred registering the topic or else `websubhub:TopicRegistrationSuccess`


Deregisters a topic in a Ballerina WebSub Hub.
```ballerina
websubhub:TopicDeregistrationSuccess response = check publisherClient->deregisterTopic("http://websubpubtopic.com");
```



deregisterTopic

A `websubhub:TopicDeregistrationError` if an error occurred un registering the topic or else `websubhub:TopicDeregistrationSuccess`


Publishes an update to a remote Ballerina WebSub Hub.
```ballerina
websubhub:Acknowledgement response = check publisherClient->publishUpdate("http://websubpubtopic.com",{"action": "publish",
"mode": "remote-hub"});
```



publishUpdate

payload

The type of the update content to set as the `ContentType` header


contentType

A `websubhub:UpdateMessageError`if an error occurred with the update or else `websubhub:Acknowledgement`


Notifies a remote WebSubHub from which an update is available to fetch for hubs that require publishing.
```ballerina
 websubhub:Acknowledgement|websubhub:UpdateMessageError response = check publisherClient->notifyUpdate("http://websubpubtopic.com");
```



notifyUpdate

A `websubhub:UpdateMessageError` if an error occurred with the notification or else `websubhub:Acknowledgement`


PublisherClient

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


COMPRESSION_ALWAYS

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.


COMPRESSION_AUTO

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


COMPRESSION_NEVER

## Overview

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

[**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 requests. Hubs then distribute new and updated content to subscribers when it becomes available. WebSub was previously known as PubSubHubbub.

[**WebSub Hub**](https://www.w3.org/TR/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**](https://www.w3.org/TR/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](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 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`.

```ballerina
type HubClient client object {
    remote function notifyContentDistribution(websubhub:ContentDistributionMessage msg)
                returns websubhub:ContentDistributionSuccess|websubhub:SubscriptionDeletedError|error?;
};
```

* The following is a sample usage for **WebSub HubClient**.

```ballerina
websubhub:Service hubService = service object {
    remote function onSubscriptionIntentVerified(websubhub:Subscription msg) returns error? {

        // you can pass client config if you want 
        // say maybe retry config
        websubhub:HubClient hubclient = check new (msg);
        _ = start self.notifySubscriber(hubclient);
    }

    function notifySubscriber(websubhub:HubClient hubclient) returns error? {
        while true {
            // fetch the message from MB
            _ = check hubclient->notifyContentDistribution({
                content: "This is sample content delivery"
            });
        }
    }
};
```

#### 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**.

```ballerina
websubhub:PublisherClient publisherClient = check new ("http://localhost:9191/websub/hub");
websubhub:TopicDeregistrationSuccess topicRegResponse = check publisherClient->registerTopic("http://websubpubtopic.com");
json payload = {
    "action": "publish",
    "mode": "remote-hub"
};
websubhub:Acknowledgement publishResponse = check publisherClient->publishUpdate("http://websubpubtopic.com", payload);
```

#### Return errors from remote methods

* Remote functions in `websubhub:Service` can return `error` type.
```ballerina
service /websubhub on new websubhub:Listener(9090) {

    isolated remote function onRegisterTopic(websubhub:TopicRegistration message)
                                returns websubhub:TopicRegistrationSuccess|websubhub:TopicRegistrationError|error {
        boolean validationSuccessfull = check validateRegistration(message);
        if validationSuccessfull {
            websubhub:TOPIC_REGISTRATION_SUCCESS;
        } else {
            return websubhub:TOPIC_REGISTRATION_ERROR;
        }
    }

    // implement other remote methods
}

function validateRegistration(websubhub:TopicRegistration message) returns boolean|error {
   // implement validation
}
```

* 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 |
| ----------- | ---------------- |
| onRegisterTopic | Topic registration failure |
| onDeregisterTopic | Topic de-registration failure |
| onUpdateMessage | Update message error |
| onSubscription | Subscription internal server error |
| onSubscriptionValidation | Subscription validation failure |
| onSubscriptionIntentVerified | Subscription intent verification failure |
| onUnsubscription | Unsubscription internal server error |
| onUnsubscriptionValidation | Unsubscription validation failure |
| onUnsubscriptionIntentVerified | Unsubscription intent verification failure |


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



EVENT

PUBLISH

MessageType

Error type representing the errors in the subscription request.


BadSubscriptionError

Error type representing the errors in the unsubscription request.


BadUnsubscriptionError

Error type representing the internal errors in the content distribution.


ContentDeliveryError

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


mediaType

Additional request headers received to be included in the request

headers

body

CommonResponse

Error type representing the internal errors in the subscription action.


InternalSubscriptionError

Error type representing the internal errors in the unsubscription action.


InternalUnsubscriptionError

Represents a websubhub service execution error.


ServiceExecutionError

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


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


SubscriptionDeniedError

Error type representing the errors in the topic unregistration action.


TopicDeregistrationError

Error type representing the errors in the topic registration action.


TopicRegistrationError

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


UnsubscriptionDeniedError

Error type representing the errors in the content update request.


UpdateMessageError

Initiliazes the `websubhub:Listener` instance.
```ballerina
listener websubhub:Listener hubListenerEp = check new (9090);
```



Port number or an `http:Listener` instance


listenTo

Custom `websubhub:ListenerConfiguration` to be provided to the underlying HTTP listener


ListenerConfiguration

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


Attaches the provided `websubhub:Service` to the `websubhub:Listener`.
```ballerina
check hubListenerEp.attach('service, "/hub");
```



attach

The `websubhub:Service` object to attach


'service

Service

name

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


Detaches the provided `websubhub:Service` from the `websubhub:Listener`.
```ballerina
check hubListenerEp.detach('service);
```



detach

The `websubhub:Service` object to be detached


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


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



'start

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


Gracefully stops the hub listener. Already-accepted requests will be served before the connection closure.
```ballerina
check hubListenerEp.gracefulStop();
```



gracefulStop

An `websubhub:Error` if an error occurred during the listener-stopping process


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



immediateStop

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


Listener

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


json

Acknowledgement

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



The HTTP version understood by the client


httpVersion

Configurations related to HTTP/1.x protocol


http1Settings

ClientHttp1Settings

Configurations related to HTTP/2 protocol


http2Settings

ClientHttp2Settings

The maximum time to wait (in seconds) for a response before closing the connection


timeout

decimal

Configurations associated with request pooling


poolConfig

PoolConfiguration

Configurations related to client authentication


auth

ClientAuthConfig

retryConfig

RetryConfig

Configurations associated with inbound response size limits


responseLimits

ResponseLimitConfigs

secureSocket

ClientSecureSocket

Configurations associated with the behaviour of the Circuit Breaker


circuitBreaker

CircuitBreakerConfig

Record to represent a WebSub content delivery.



Additional Request headers to include when distributing content


content

Record to represent the successful WebSub content delivery.



Status of the request processing. This is `200 OK` by default since
this is a successful response


status

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


Provides a set of configurations for HTTP service endpoints.


host

Configurations related to HTTP/1.x protocol

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

Highest HTTP version supported by the endpoint

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

The server name which should appear as a response header

server

Configurations associated with inbound request size limits

requestLimits

interceptors

Configuration for a WebSub Hub service.



The period for which the subscription is expected to be active in the `hub`


leaseSeconds

HTTP client configurations for subscription/unsubscription intent verification


webHookConfig

Record to represent the subscription request body.



URL of the `hub` to which the subscriber has subscribed


hubMode

Callback URL for subscriber to receive distributed content


hubCallback

Topic to which subscriber has subscribed


hubTopic

Amount of time in seconds during when the subscription is valid


hubLeaseSeconds

Secret Key to sign the distributed content


hubSecret

Record to represent the subscription accepted by the `hub`.


SubscriptionAccepted

Record to represent the permanent subscription redirects.



URLs to which the subscription has been redirected

redirectUrls

anydata

SubscriptionPermanentRedirect

Record to represent temporary subscription redirects.



SubscriptionTemporaryRedirect

Record to represent the topic-deregistration request body.



`Topic`, which should be unregistered from the `hub`


TopicDeregistration

Record to represent the successful topic deregistration.


TopicDeregistrationSuccess

Record to represent the topic-registration request body.



`Topic`, which should be registered in the `hub`


TopicRegistration

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


Client: HubClient

Constructor

Remote Methods

notifyContentDistribution

Parameters

Return Type