.. _publishing:

==========
Publishing
==========

Overview
========

Publishing messages is simple. Messages are made up of a topic, some optional
headers, and a body. Messages are encapsulated in a
:class:`fedora_messaging.message.Message` object. For details on defining
messages, see the :ref:`messages` documentation. For details on the publishing
API, see the :ref:`pub-api` API documentation.

Topics
------

`Topics`_ are strings of words separated by the ``.`` character, up to 255
characters. Topics are used by clients to filter messages, so choosing a good
topic helps reduce the number of messages sent to a client. Topics should start
broadly and become more specific.


Headers
-------

Headers are key-value pairs attached that are useful for storing information
about the message itself. This library adds a header to every message with the
``fedora_messaging_schema`` key, pointing to the message schema used.

You should not use any key starting with ``fedora_messaging`` for yourself.

You can write :ref:`header-schema` for your messages to enforce a particular
schema.


Body
----

The only restrictions on the message body is that it must be serializable to a
JSON object. You should write a :ref:`body-schema` for your messages to ensure
you don't change your message format unintentionally.


Introduction
============

To publish a message, first create a :class:`fedora_messaging.message.Message`
object, then pass it to the :func:`fedora_messaging.api.publish` function::

    from fedora_messaging import api, message

    msg = message.Message(topic=u'nice.message', headers={u'niceness': u'very'},
                          body={u'encouragement': u"You're doing great!"})
    api.publish(msg)

The API relies on the :ref:`config` you've provided to connect to the message
broker and publish the message to an exchange.


Handling Errors
===============

Your message might fail to publish for a number of reasons, so you should be
prepared to see (and potentially handle) some errors.


Validation
----------

The message you create may not be successfully validated against its schema.
This is not an error you should catch, since it must be fixed by the developer
and cannot be recovered from.


Connection Errors
-----------------

The publish API will attempt to reconnect to the broker several times before an
exception is raised. Once this occurs it is up to the application to decide what
to do.


Rejected Messages
-----------------

The broker may reject a message. This could occur because the message is too
large, or because the publisher does not have permission to publish messages
with a particular topic, or some other reason.


.. _topics: https://www.rabbitmq.com/amqp-0-9-1-reference.html#queue.bind.routing-key