Skip to content

Choose a wire format

Settings.Format is the writer for every event the backend publishes. Settings.Reads is the chain a received message is read with, and exactly one format in it must claim a message. Unset, the writer is CloudEvents binary for the AMQP binding, and the chain is binary then structured. The mapping onto AMQP is in Wire format.

Write structured CloudEvents

import cloudevents "gitlab.com/phpboyscout/go/envelope-cloudevents"

backend, err := amqp.New(ctx, amqp.Settings{
    URL:    url,
    Format: cloudevents.Structured(),
}, amqp.Artemis{})

content-type becomes application/cloudevents+json and the attributes travel in the body. Reads is left unset: the default chain already reads structured.

Exchange messages with .NET services

MassTransit and NServiceBus work the same way, as a writer, in Reads beside the defaults, or both. The suite runs under each.

import (
    "gitlab.com/phpboyscout/go/envelope"
    cloudevents "gitlab.com/phpboyscout/go/envelope-cloudevents"
    masstransit "gitlab.com/phpboyscout/go/envelope-masstransit"
)

settings.Format = masstransit.MassTransit()
settings.Reads = []envelope.Format{
    cloudevents.Binary(cloudevents.AMQP),
    cloudevents.Structured(),
    masstransit.MassTransit(),
}

Setting Reads replaces the default chain, so list the CloudEvents formats again if you still want to read them. For NServiceBus use nservicebus.NServiceBus() from gitlab.com/phpboyscout/go/envelope-nservicebus in the same positions.

MassTransit refuses at publish an ID that is not a UUID and a payload that is not JSON. Publish then returns messaging-amqp: encoding the event wrapping the format's error. Each format's own rules are on its package: envelope-masstransit and envelope-nservicebus.

Move a deployment to another format

A consumer can read a format before any producer writes it. So:

  1. Upgrade every reader with the new format in Reads.
  2. Only then switch the writers' Format.

Switch in the other order and a reader that does not yet claim the new format sees unreadable messages: see Find messages no format could read. Under AtLeastOnce those are dead-lettered after MaxDeliver attempts.

Keep an eye on what two formats both claim

The reader refuses to guess. A message that two formats in Reads both claim is unreadable. Putting two formats in the chain that claim overlapping messages is the way to get it. The suite's interop runs keep the CloudEvents formats ahead of the interop one to show the formats tell each other apart.

Properties no format takes

String application properties that no format takes reach a handler through Delivery.Foreign(). A tracing header is one, and so is Artemis's _AMQ_DUPL_ID. They are never sent on by a publish.