Choose a wire format¶
Settings.Format is the one format the backend writes. Settings.Reads is the chain it reads
with. Unset, it writes CloudEvents binary with the ce- prefix and reads binary then structured.
The formats are go/envelope's, the CloudEvents ones
are go/envelope-cloudevents's, and the
design is
spec 0014.
Wire format and SNS limits has the attributes and caps.
Write structured¶
import cloudevents "gitlab.com/phpboyscout/go/envelope-cloudevents"
backend := sqs.Standard(sqs.Settings{AWS: src, Format: cloudevents.Structured()})
Structured moves every attribute into the message body. Only content-type stays an SNS attribute.
It buys two things binary cannot do:
- More than ten attributes. SNS carries at most ten message attributes. Binary spends four on the
required attributes, one on the content type when the event has a data content type, and one on each
optional attribute and extension the event sets. An event over ten is refused at
Publish. - A payload that is not UTF-8. SNS takes a message as UTF-8 text. Structured carries such a
payload base64-encoded as
data_base64. Binary refuses it atPublish.
It costs one thing. A subscription filter policy on an attribute has to move to the body. In
binary, a policy on ce-type, ce-source or an extension filters on message attributes. In
structured those values are in the body, so the policy needs
FilterPolicyScope: MessageBody.
A deployment that cannot change its policies stays on binary.
Move a deployment to structured¶
Readers first, writers second. The default Reads already takes structured, so:
- Upgrade every consumer to a version of the adapter that reads structured, leaving
Formatunset. - Rewrite any attribute-based filter policies for message-body scope.
- Set
Format: cloudevents.Structured()on the producers.
Read another format beside the defaults¶
Exactly one format in Reads must claim a message. List the defaults and add yours:
sqs.Standard(sqs.Settings{
AWS: src,
Format: masstransit.MassTransit(),
Reads: []envelope.Format{cloudevents.Binary(cloudevents.HTTP), cloudevents.Structured(), masstransit.MassTransit()},
})
Reads replaces the default chain when it has any entry. An empty or nil Reads takes the default.
Format is separate: setting it does not add it to Reads.
The MassTransit and NServiceBus formats (go/envelope-masstransit, go/envelope-nservicebus) work this way. MassTransit puts the whole event in the body, so like structured it spends one SNS attribute, its content type. NServiceBus writes its own headers as SNS attributes, which count toward the ten. Each format's rules are on its package, and the adapter's suite runs under both.
What a message nobody claims becomes¶
A message no format claims, one two formats both claim, and one a format claims but cannot decode are unreadable. They never reach a handler.
Attributes no format takes¶
An attribute no format takes, such as one added by another producer, reaches a handler through
Delivery.Foreign(). It is never sent on.