Thorn

=====
:release-date: 2016-10-20 11:08 A.M PDT
:release-by: Ask Solem

- New API for :class:`~thorn.ModelEvent`.

After having used Thorn for a while, there was a realization
that passing lots of arguments to a decorator looks very messy
when there are many events for a model.

We have come up with a new way to add webhooks to models,
that we believe is more tidy.

The new API moves declaration of webhooks related things into a
nested class:

.. code-block:: python

webhook_model
class Article(models.Model):
uuid = models.UUIDField()
title = models.CharField(max_length=128)
state = models.CharField(max_length=128, default='PENDING')
body = models.TextField()
user = models.ForeignKey(settings.AUTH_USER_MODEL)

class webhooks:
on_create = ModelEvent('article.created')
on_change = ModelEvent('article.changed')
on_delete = ModelEvent('article.removed')
on_publish = ModelEvent(
'article.published', state__now_eq='PUBLISHED',
).dispatches_on_change()

def payload(self, article):
return {
'title': article.title,
}

def headers(self, article):
return {
'Authorization':
'Bearer {}'.format(article.user.access_token),
}

.. note::

The old API is still supported, and there's no current plans
of deprecating the arguments to the decorator itself.

- Adds support for buffering events - moving dispatch out of signal handlers.

See :ref:`event-buffering` for more information.

- Models can now define additional headers to be passed on to webhooks.

See :ref:`events-model-header`.

Contributed by **Flavio Curella**.

- Django: :class:`~thorn.ModelEvent` now takes advantage of
``Model.get_absolute_url()``.

Instead of defining a reverser you can now simply have your model
define a ``get_absolute_url`` method (which is a convention already):

.. code-block:: python

from django.urls import reverse

class Article(models.Model):

def get_absolute_url(self):
return reverse('article:detail', kwargs={'slug': self.slug})

For more information on defining this method, refer to the
Django documentation:
https://docs.djangoproject.com/en/stable/ref/models/instances/#get-absolute-url

- New :setting:`THORN_SIGNAL_HONORS_TRANSACTION` setting.

If enabled the Django model events will dispatch only after
the transaction is committed, and should the transaction be rolled back
the events are discarded.

You can also enable this setting on individual events:

.. code-block:: python

ModelEvent(..., signal_honors_transaction=True)

Disabled by default.

To be enabled by default in Thorn 2.0.

- :class:`~thorn.ModelEvent` now logs errors instead of propagating them.

``ModelEvent(propagate_errors=True)`` may be set to revert to the old
behavior.

- URLs now ordered by scheme,host,port (was host,port,scheme).

- Documentation improvements by:

- Flavio Curella

.. _version-1.4.2:

=====
:release-date: 2016-07-28 11:45 A.M PDT

- Serialize uuid as string when calling Celery tasks.

.. _version-1.4.1:

=====
:release-date: 2016-07-26 01:06 P.M PDT
:release-by: Ask Solem

- Fixed webhook dispatch crash where validator was deserialized twice.

- Celery dispatcher did not properly forward the `Hook-Subscription`
HTTP header.

- Source code now using Google-style docstrings.

.. _version-1.4.0:

=====
:release-date: 2016-07-11 04:27 P.M PDT
:release-by: Ask Solem

- New HTTP header now sent with events: ``Hook-Subscription``

This contains the UUID of the subscription, which means
a webhook consumer may now react by cancelling or modifying the subscription.

- Fixed missing default value for the :setting:`THORN_SUBSCRIBER_MODEL`
setting.

- Fixed HMAC signing wrong message value.

.. _version-1.3.0:

=====
:release-date: 2016-07-07 07:40 P.M PDT
:release-by: Ask Solem

- New and improved method for HMAC signing.

The new method must be enabled manually by setting:

.. code-block:: python

THORN_HMAC_SIGNER = 'thorn.utils.hmac:sign'

It turns out itsdangerous did not do what we expected it to,
instead it does this:

- The secret key is transformed into:

.. code-block:: python

key = hashlib.sha256(salt + 'signer' + HMAC_SECRET)
strip = from beginning and end of the base64 string
key = key.strip('=')

- If you don’t specify a salt, which we don’t, there is a
default salt(!) which is:

.. code-block:: text

“itsdangerous.Signer”

- The extra "signer" in the key transformation is there as the default
key_derivation method is called “django-concat”.

- The final signature is encoded using “urlsafe_b64encode"

So in Python to recreate the signature using the built-in hmac
library you would have to do:

.. code-block:: python

import hashlib
import hmac
from base64 import urlsafe_b64encode

everything hardcoded to SHA256 here

def create_signature(secret_key, message):
key = hashlib.sha256(
'itsdangerous.Signer' + 'signer' + secret_key).digest()
digest = hmac.new(key, message, digestmod=hashlib.sha256).digest()
return urlsafe_b64encode(digest).replace('=')

which is much more complicated than what we can expect of users.

You're highly encouraged to enable the new HMAC method, but sadly
it's not backwards compatible.

We have also included new examples for verifying HMAC signatures
in Django, Ruby, and PHP in the documentation.

- New :setting:`THORN_SUBSCRIBER_MODEL` setting.

- New :setting:`THORN_HMAC_SIGNER` setting.

- Requirements: Tests now depends on :pypi:`case` 1.2.2

- JSON: Make sure simplejson does not convert :class:`~decimal.Decimal`
to :class:`float`.

- class:`~thorn.events.ModelEvent`: name can now be a string format.

Contributed by Flavio Curella.

The format expands using the model instance affected, e.g:

.. code-block:: python

on_created=ModelEvent('created.{.occasion}')

means the format will expand into ``instance.occasion``.

Subclasses of :class:`~thorn.events.ModelEvent` can override how the name is
expanded by defining the ``_get_name`` method.

.. _version-1.2.1:

=====
:release-date: 2016-06-06 06:30 P.M PDT
:release-by: Ask Solem

- Celery: Forward event signal context to the tasks.

.. _version-1.2.0: