The Hub

The Hub is an HTTP server that performs two major tasks:

• Handle Subscriptions.
• Receive and Publish notifications.

The hub maintains the list of subscribers and topics (channels) persistently and can accept both ResourceSync payloads (ResourceSync mode) and regular PubSubHubbub payloads (PubSubHubbub mode).

Subscription

A subscriber can send subscription requests to the hub so that it can receive notifications for a topic. The Hub's subscription handling is implemented in accordance to the latest version of the PubSubHubbub protocol. Please refer to the Subscribing and Unsubscribing section of the protocol for more details on the subscription mechanism.

NOTE: The hub does not support HTTPS protocol and hence does not understand the hub.secret parameter specified in the PuSH spec.

Storing Subscriptions

The subscribers and the topics they subscribed to are stored in a pickle file for persistence. By default, this file is installed in the resourcesync_push library in the python site-packages folder. It is very likely that the hub process will not have write permissions to write to this file. It is highly recommended that a path to a subscription file that will have write permissions be provided in the configuration file. Please refer to the parameter subscribers_file in the Configuration section below.

Note: For a production deployment, a pickle file is neither secure nor scalable and hence implementing support for an SQL or No-SQL data store should be considered.

Publishing

A Publisher can send a notification either in ResourceSync mode or in PubSubHubbub mode. The hub handles the payload differently depending on the type of notification provided by the publisher. The hub determines the type of payload by analyzing the value of the content-type HTTP header. The two modes are explained in detail below.

To prevent abuse by a rogue publisher, the hub provides the following configuration options:

• Accept notifications from only a list of trusted publishers while ignoring others.
• Filter notifications by a list of trusted topics.
• Limit the size of the POST request to 2MB and reject any request greater than that.

Instructions for enabling these parameters are provided in the Configuration section below.

ResourceSync Mode

The notification received by the hub in this mode must be of mime-type application/xml. The hub verifies this by checking the content-type HTTP header. Once that is verified, the hub checks for the presence of the HTTP link header as stipulated in this section of the ResourceSync notification specification. The hub retrieves the topic and hub URL from this link header and rejects any notification if they are not present.

The hub retrieves the list of subscribers registered for this topic URL and publishes the notification to all of them.

PubSubHubbub Mode

If the content-type header has the value application/x-www-form-urlencoded, the hub understands that the received notification is a traditional PubSubHubbub payload. It then expects the following two parameters to be present in the payload:

• hub.mode: [required] For now, this only supports the value publish.
• hub.url: [required] The HTTP URL from which the notification payload can be retrieved.

The hub will dereference the HTTP URL provided by the parameter hub.url and deliver it's body to the subscribers. The value of the parameter hub.url is also the topic (channel) URL for subscribers to register to.

In this mode, the hub can also accept payload directly from the publisher similar to the ResourceSync Mode above: it can accept the notification body in the payload itself rather than dereferencing a URL. The list of accepted mime-types must be provided in the configuration file for this to work.

Configuration

The following parameters need to be set in the [hub] section of resourcesync_push.ini.

• url: [required] The complete HTTP URL of the hub itself.
• trusted_publishers: [optional] One or more HTTP URLs of the publisher(s) that the hub must accept notifications from. Multiple publisher URLs must be separated by a comma.
• trusted_topics: [optional] One or more HTTP topic URLs, separated by a comma, that the hub must accept notifications for.
• mimetypes: [optional] One or more mime-types of the notifications that the hub should accept. This value should match the value of the content-type HTTP header e.g., application/xml.
• subscribers_file: [optional] The full path in the filesystem where the subscription pickle file should be saved. By default, this path is <path to python site-package/library>/db/subscriptions.pk.
• server_path: [optional] If the publisher is set up using a proxy server, the proxy path must be specified here.