racketmq-2017/README.md

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

  [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 <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][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 <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/>.