websubsub 0.9.3

Installation

pip install websubsub

Add websubsub.apps.WebsubsubConfig to the list of INSTALLED_APPS in your settings.py:

INSTALLED_APPS = [
    ...,
    'websubsub.apps.WebsubsubConfig'
]

Set the WEBSUBSUB_OWN_ROOTURL setting in your settings.py to the full url of your project site, e.g. https://example.com/. It will be used to build full callback urls.

Set DUMBLOCK_REDIS_URL settings in your settings.py. Redis locks are used to ensure subscription/unsubscription tasks are consistent with hub and local database.

WEBSUBSUB_OWN_ROOTURL = 'http://example.com/'
DUMBLOCK_REDIS_URL= 'redis://redishost:6379'

Add websubsub.tasks.refresh_subscriptions and websubsub.tasks.retry_failed to celerybeat schedule. If you define it in settings.py:

CELERY_BEAT_SCHEDULE = {
    'websub_refresh': {
        'task': 'websubsub.tasks.refresh_subscriptions',
        'schedule': 3600  # Hourly
    },
    'websub_retry': {
        'task': 'websubsub.tasks.retry_failed',
        'schedule': 600  # Every 10 minutes
    },
}

Usage

from celery import shared_task

@shared_task
def news_task(data):
    print('got news!')

from websubsub.views import WssView
from .tasks import news_task, reports_task

urlpatterns = [
    path('/websubcallback/news/<uuid:id>', WssView.as_view(news_task), name='webnews')
    path('/websubcallback/reports/<uuid:id>', WssView.as_view(reports_task), name='webreports')
]

from websubsub.models import Subscription
Subscription.create(topic='mytopic', urlname='webnews', hub='http://example.com')

WEBSUBSUB_HUBS = {
    'http://example.com': {
        'subscriptions': [
            {'topic': 'mytopic', 'callback_urlname': 'webnews'},
            ...
        ]
    }
}

from websubsub.models import Subscription
Subscription.objects.get(pk=4).unsubscribe()

Settings

WEBSUBSUB_OWN_ROOTURL - ex.: https://example.com/. Required. Will be used to build full callback urls.

DUMBLOCK_REDIS_URL - ex.: redis://redishost:6379. Required. Will be used to lock atomic tasks.

WEBSUBSUB_AUTOFIX_URLS - If True, then websubsub.tasks.subscribe() task will be allowed to ovewrite subscription.callback_url, resolving its callback_urlname. If False, it will print an error and exit. Default: True

WEBSUBSUB_DEFAULT_HUB_URL

WEBSUBSUB_MAX_CONNECT_RETRIES

WEBSUBSUB_MAX_HUB_ERROR_RETRIES

WEBSUBSUB_MAX_VERIFY_RETRIES

WEBSUBSUB_VERIFY_WAIT_TIME - How many seconds should pass before unverified subscription is considered failed. After that time, websubsub.tasks.retry_failed() task will be able to retry subscription process again.

Management commands

./manage.py websub_static_subscribe - Materialize static subscriptions from settings. Optional arguments:

• --purge-orphans - delete old static subscriptions from database

• -y, --yes - answer yes to all

• --reset-counters - reset retry counters

• --force - send new subscription request to hub even if already subscribed or explicitly unsubscribed

./manage.py websub_purge_unresolvable - Delete all subscriptions with unresolvable urlname from database.

./manage.py websub_purge_all - Delete all subscriptions from database.

./manage.py websub_reset_counters - Reset retry counters for all subscriptions in database.

./manage.py websub_handle_url_changes - Guess changed urlnames for subscriptions from current callback_url. Also detect changed url patterns and schedule resubscribe with new url.

./manage.py dumpdata websubsub --indent 2 - Show all subscriptions.

Testing

pip install -r tests/requirements.txt
py.test