HTTP Based client for WebSub content publishing to subscribers


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



init

Original subscription details for 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|SubscriptionDeletedError|error? publishUpdate = websubHubClientEP->notifyContentDistribution(
  { 
      content: "This is sample content" 
  }
);
```



notifyContentDistribution

Content to be distributed to the topic subscriber 


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

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 websubHubClientEP = new("http://localhost:9191/websub/publish");
```



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
error? registerTopic = websubHubClientEP->registerTopic("http://websubpubtopic.com");
```



registerTopic

topic

An `error` if an error occurred registering the topic or else `()`


Deregisters a topic in a Ballerina WebSub Hub.
```ballerina
error? deregisterTopic = websubHubClientEP->deregisterTopic("http://websubpubtopic.com");
```



deregisterTopic

An `error`if an error occurred un registering the topic or else `()`


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



publishUpdate

payload

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


contentType

An `error`if an error occurred with the update or else `()`


Notifies a remote WebSubHub from which an update is available to fetch for hubs that require publishing.
```ballerina
 error? notifyUpdate = websubHubClientEP->notifyUpdate("http://websubpubtopic.com");
```



notifyUpdate

An `error`if an error occurred with the notification or else `()`


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

#### Using Hub Client

* **WebSub HubClient** can be used to distribute the published content among the `subscriber base`. The current implementation is based on
a `ballerina HTTP Client`.

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

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

```ballerina
    type HubService service object {
        remote function onSubscriptionIntentVerified(websubhub:Subscription msg) {

            // you can pass client config if you want 
            // say maybe retry config
            websub:HubClient hubclient = new(msg);
            check start 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"
                });
            }   
        }
    }
```

#### Using Publisher Client

* 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 = new ("http://localhost:9191/websub/hub");

    check publisherClient->registerTopic("http://websubpubtopic.com");
   
    var publishResponse = publisherClient->publishUpdate(
                "http://websubpubtopic.com",
                {
                    "action": "publish", 
                    "mode": "remote-hub"
                });
```

# Returning 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

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. It is not implemented yet.
```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.


mediaType

headers

body

Acknowledgement

Record to represent client configuration for 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

json

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.


host

server

requestLimits

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.



redirectUrls

SubscriptionRedirect

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

Record to represent the successful topic registration.


TopicRegistrationSuccess

Record to represent the unsubscription request body.



Callback URL for subscriber to received distributed content


Topic from which subscriber wants to unsubscribe


Unsubscription

Record to represent the unsubscription acceptance.


UnsubscriptionAccepted

Record to represent the content update message.



msgType

Topic of which the content should be updated


UpdateMessage

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


Client: HubClient

Constructor

Remote Methods

notifyContentDistribution

Parameters

Return Type