Skip to content

Read what arrived with an event

Decode and Read return an envelope.Foreign beside the event. It holds what arrived with the event but is not part of it.

e, foreign, format, err := envelope.Read(w, readers...)

Look a header up

Foreign.Headers is a map[string][]string. A broker's own headers, a gateway's tracing header and, for an interop format, the fields of a foreign envelope that have no CloudEvents equivalent all land here, under the name they arrived with:

if ids := foreign.Headers["Nats-Msg-Id"]; len(ids) > 0 {
    logger.Debug("broker id", "id", ids[0])
}

Which names appear depends on the format, and the keys keep the case they arrived in. The adapter sections list them: MassTransit, NServiceBus.

Check for a conflict

Foreign.Conflicts names the keys an envelope set that the transport also carried with another value. The envelope's value is in the event, and the transport's is in Headers under the same key:

for _, key := range foreign.Conflicts {
    logger.Warn("transport and envelope disagree", "key", key, "transport", foreign.Headers[key])
}

Only the interop formats can produce one, because only their envelopes have fields that transport headers can shadow. Binary and structured CloudEvents never do.

Do not send it on

Nothing in go/envelope sends a Foreign. A reply built from the event carries none of it, and Encode takes an Event, not a Foreign. If a header has to travel on, copy it into an extension deliberately, with a name envelope.ValidExtensionName accepts, and with a value that is safe to log: see Add an extension attribute.

With go/messaging

go/messaging hands the same value to a handler as Delivery.Foreign(), a copy that is read-only and never sent on.