Skip to content

Choose a wire format

Settings.Format writes every event, request and reply this backend sends. Settings.Reads is the chain a received message is read with. Both backends use them, since JetStreamSettings embeds Settings.

What it writes and reads by default

  • Writes: CloudEvents in binary mode, for the NATS binding, which is what this adapter wrote before formats existed.
  • Reads: CloudEvents binary for the NATS binding, then CloudEvents structured. A consumer can therefore read structured before any producer writes it.

The formats are go/envelope-cloudevents's, cloudevents.Binary(cloudevents.NATS) and cloudevents.Structured().

NATS has no native content-type property. A format's content type travels as the content-type header (cloudevents.HeaderContentType), as the adapter has always sent it.

Write structured events

nats.Core(nats.Settings{Client: c, Format: cloudevents.Structured()})

Leave Reads unset and it reads binary and structured.

Move a deployment to structured

Upgrade the readers first and switch the writers after. The default chain already reads structured, so the order is: deploy every consumer on an adapter version with the default Reads; then set Format on the producers.

Exchange messages with .NET services

The MassTransit and NServiceBus formats work the same way, as a writer, in Reads beside the defaults, or both:

nats.Core(nats.Settings{
    Client: c,
    Format: masstransit.MassTransit(),
    Reads: []envelope.Format{
        cloudevents.Binary(cloudevents.NATS),
        cloudevents.Structured(),
        masstransit.MassTransit(),
    },
})

Reads replaces the default chain, so list the CloudEvents formats again if you still need them. MassTransit refuses at publish an ID that is not a UUID and a payload that is not JSON. Each format's rules are on its package: go/envelope-masstransit and go/envelope-nservicebus.

What the chain does with a message

  • Exactly one format must claim a message. One claimed by none, or by two, is unreadable. See What happens to an unreadable message.
  • A reply goes out in the format its request arrived in, whatever the backend's own Format is, so a structured caller gets a structured answer. A failure reply follows the same rule.
  • Headers no format takes, such as Nats-Msg-Id on a JetStream message or a tracing header, reach a handler through Delivery.Foreign(). They are never sent on.

The decisions are spec 0014.