# RacketMQ: An implementation of W3C WebSub
This is an implementation of a W3C WebSub Hub in Racket, using the
actor-style research language [Syndicate](http://syndicate-lang.org/).
## 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
(and track its development at
).
**N.B.: These URLs will eventually have `websub` in place of `pubsub`.**
[w3cspec]: https://www.w3.org/TR/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 .
## Bug Reports
Please report issues using this project's Github issues page,
.
## 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][w3cspec]. 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 `POST`ed 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
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 .