Message Format¶
This documentation covers the format of AMQP messages sent by this library. If you are interested in using a language other than Python to send or receive messages sent by Fedora applications, this document is for you.
Messages are AMQP Basic content. Basic messages have the content type, content encoding, a table of headers, delivery mode, priority, correlation ID, reply-to, expiration, message ID, timestamp, type, user ID, and app ID fields.
Content Type¶
Your messages MUST have a content-type of application/json
and they must
be JSON objects. Consult the Message Schemas documentation for details on
message format.
Content Encoding¶
Your message MUST have the content-encoding property set to utf-8
and they
must be encoding with UTF-8.
Message ID¶
The message ID field MUST be a version 4 UUID as a standard hexadecimal digit string (e.g. f81d4fae-7dec-11d0-a765-00a0c91e6bf6).
Delivery Mode¶
The delivery mode of your message SHOULD be 2 (persistent) unless you know what you are doing and have a very good reason for setting it to 1 (transient).
Headers¶
The headers field of AMQP message allows you to set a dictionary (map) of arbitrary strings. Several header keys are used by Fedora’s applications to determine the message schema, the importance of the message for human beings, when it was originally sent by the application, what packages or users it relates to, and more.
Required¶
Messages must have, at a minimum, the fedora_messaging_severity
,
fedora_messaging_schema
, and sent-at
keys.
The fedora_messaging_severity
key should be set to an integer that
indicates the importance of the message to an end user, with 10 being
debug-level information, 20 being informational, 30 being warning-level, and 40
being critically important.
The fedora_messaging_schema
key should be set to a string that uniquely
identifies the type of message. In the Python library this is the entry point
name, which is mapped to a class containing the schema and a Python API to
interact with the message object.
The sent-at
key should be a ISO8601 date time that should include the UTC
offset and should not include microseconds. For example:
2019-07-30T19:12:22+00:00
.
The header’s json-schema is:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Schema for message headers",
"type": "object",
"properties": {
"fedora_messaging_severity": {
"type": "number",
"enum": [10, 20, 30, 40],
},
"fedora_messaging_schema": {"type": "string"},
"sent-at": {"type": "string"},
},
}
Optional¶
In addition to the required headers, there are a number of optional headers you
can set that have special meaning. The general format of these headers is
fedora_messaging_<object>_<id>
where the <object>
is one of user
,
rpm
, container
, module
, or flatpak
and <id>
uniquely
identifies the object. Set these headers when the message pertains to the
referenced object.
For example, if the user jcline
submitted a build for the python-requests
RPM, the message about that event would have fedora_messaging_user_jcline
and fedora_messaging_rpm_python-requests
set.
At this time the value of the header key is not used and should always be set to a Boolean value of true.
Body¶
The message body must match the content-type and content-encoding. That is, it must be UTF-8 encoded JSON. Additionally, it must be a JSON Object. Beyond that, there are no restrictions. Messages should be validated using their JSON schema. If you are publishing a new message type, please write a json-schema for it and provide it to the Fedora infrastructure team. It will be distributed to applications that wish to consume the message.