Publishing

Overview

Publishing messages is simple. Messages are made up of a topic, some optional headers, and a body. Messages are encapsulated in a fedora_messaging.message.Message object. For details on defining messages, see the Message Schemas documentation. For details on the publishing API, see the Publishing 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 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 Body Schema for your messages to ensure you don’t change your message format unintentionally.

Introduction

To publish a message, first create a fedora_messaging.message.Message object, then pass it to the 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 Configuration 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.