Home

Awesome

Ballerina WebSubHub Library

Build codecov Trivy GraalVM Check
GitHub Last Commit Github issues

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

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 is an implementation that handles subscription requests and distributes the content to subscribers when the corresponding topic URL has been updated.

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

type HubClient client object {
    remote function notifyContentDistribution(websubhub:ContentDistributionMessage msg)
                returns websubhub:ContentDistributionSuccess|websubhub:SubscriptionDeletedError|error?;
};
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

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

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
}
MethodInterpreted meaning for Error Return
onRegisterTopicTopic registration failure
onDeregisterTopicTopic de-registration failure
onUpdateMessageUpdate message error
onSubscriptionSubscription internal server error
onSubscriptionValidationSubscription validation failure
onSubscriptionIntentVerifiedSubscription intent verification failure
onUnsubscriptionUnsubscription internal server error
onUnsubscriptionValidationUnsubscription validation failure
onUnsubscriptionIntentVerifiedUnsubscription intent verification failure

Issues and projects

Issues and Projects tabs are disabled for this repository as this is part of the Ballerina Standard Library. To report bugs, request new features, start new discussions, view project boards, etc. please visit Ballerina Standard Library parent repository.

This repository only contains the source code for the package.

Build from the source

Set up the prerequisites

  1. Download and install Java SE Development Kit (JDK) version 21 (from one of the following locations).

    • Oracle

    • OpenJDK

      Note: Set the JAVA_HOME environment variable to the path name of the directory into which you installed JDK.

  2. Generate a Github access token with read package permissions, then set the following env variables:

    export packageUser=<Your GitHub Username>
    export packagePAT=<GitHub Personal Access Token>
    

Build the source

Execute the commands below to build from source.

  1. To build the package:

     ./gradlew clean build
    
  2. To build the package without the tests:

        ./gradlew clean build -x test
  1. To debug the package tests:

  2. To debug the package tests:

     ./gradlew clean build -Pdebug=<port>
    
  3. To run a group of tests

    ./gradlew clean test -Pgroups=<test_group_names>
    
  4. To debug with Ballerina language:

    ./gradlew clean build -PbalJavaDebug=<port>
    
  5. Publish the generated artifacts to the local Ballerina central repository:

    ./gradlew clean build -PpublishToLocalCentral=true
    
  6. Publish the generated artifacts to the Ballerina central repository:

    ./gradlew clean build -PpublishToCentral=true
    

Contribute to Ballerina

As an open source project, Ballerina welcomes contributions from the community.

For more information, go to the contribution guidelines.

Code of conduct

All contributors are encouraged to read the Ballerina Code of Conduct.

Useful links