RacketMQ: An implementation of W3C WebSub

This is an implementation of a W3C WebSub Hub in Racket, using the actor-style research language Syndicate.

What is WebSub?

On the 20th of October 2016, the W3C released a First Public Working Draft of (what was called at the time) PubSub, later renamed to WebSub.

See the specification of the W3C WebSub protocol at https://www.w3.org/TR/pubsub/ (and track its development at https://github.com/w3c/pubsub). N.B.: These URLs will eventually have websub in place of pubsub.

Features

• Offers both local topics, topics whose canonical hub is this hub, and remote topics, topics whose canonical hub is some other ("upstream") hub

• Support for polling and push-notification for remote topics, with configurable poll interval

• Uses HTTP Link headers when retrieving a topic to determine canonical hub and topic URLs; does not extract link elements from any kind of XML or HTML document, nor does it implement .host-meta discovery

• Support for hub.secret and hub.lease_seconds protocol parameters

Conformance

At the time of writing, no official list of conformance criteria exists; however, there is a draft list of Candidate Recommendation implementation criteria at https://github.com/w3c/pubsub/issues/56.

Bug Reports

Please report issues using this project's Github issues page, https://github.com/tonyg/racketmq/issues.

Hub URL layout

• /hub — Local subscription management; main Hub URL.

  This is the main URL for creating and deleting subscriptions to (local or remote) topics.

  • method POST: create or delete a subscription, following the specification. Supply hub.mode, hub.topic, hub.callback and other relevant parameters to manage subscriptions.

• /topic/topic — Local topic endpoint.

  A local topic is a topic managed by this hub. Publishers POST their content to the local topic endpoint, and subscribers are notified of the change. Local topics may be managed explicitly or implicitly; any subscription to a local topic will automatically cause it to be created, even if it has not been previously explicitly PUT into existence.

  • method PUT: create a local topic explicitly
  • method DELETE: delete an explicitly-created local topic
  • method HEAD: get headers associated with the most recent topic value
  • method GET: get the most recent topic value
  • method POST: update the topic value with the post body

• /sub/sub-id — Upstream subscription endpoint.

  When a subscription to a remote topic is created, if the remote topic has an advertised hub, this hub subscribes to the remote hub, and content distribution requests are POSTed to a fresh upstream subscription endpoint URL.

  • method GET: for verification-of-intent requests from upstream.
  • method POST: for content distribution requests from upstream.

• /path/to/file/in/htdocs — Static resource.

  The racketmq/htdocs subdirectory contains static resources to be served by the hub.

  • method GET: retrieve a static resource.

License

Copyright © 2016 Tony Garnock-Jones tonyg@leastfixedpoint.com

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program (see the files "lgpl.txt" and "gpl.txt"). If not, see http://www.gnu.org/licenses/.