Why the NServiceBus headers are the envelope¶
Note
NServiceBus licensing. NServiceBus is dual-licensed: the Reciprocal Public License 1.5, or Particular Software's commercial agreement (particular.net/LicenseAgreement). This format was captured from NServiceBus 10.2.9, and only the module's own .NET test programs use it. The Go module itself does not depend on NServiceBus.
An NServiceBus message is a body and a set of headers. There is no JSON wrapper, as MassTransit has, and no second place to put metadata. Almost everything this format does follows from that.
Nothing is refused on the way out¶
NServiceBus's message IDs are strings, so any event ID is carried. The payload is the body and
NServiceBus picks its deserializer by the content type, so the format does not constrain the payload
either. The only exception the design needed, a format may lower time precision to its own, is
TimeSent's microseconds. That is why Encode adds no refusal beyond Validate, where MassTransit's
adds two.
Extensions are headers, so headers are extensions¶
With no envelope member for them, the format writes each extension as a header of its own name. To read them back, it has to treat any header with an extension name, lower-case letters and digits that are not an attribute's, as an extension. There is no way to tell, on the wire, an extension this format wrote from a lower-case header a broker or another producer added.
So priority or tenant set by a producer arrives as an extension, not in Foreign, and
traceparent is promoted by the same rule. This was revised from the first design, which promoted
traceparent as a special case. A header with a capital, a hyphen or a dot cannot be an extension
name, which is why every header NServiceBus writes itself stays foreign.
The cost is that the extension rule decides what a lower-case header is. A foreign header that happens
to be valid as an extension name is an extension, and Validate then applies to its value.
Headers are matched in any case¶
A header map may or may not fold case. An HTTP-style map canonicalises NServiceBus.MessageId to
Nservicebus.Messageid. So the format reads NServiceBus's headers in any case. Two spellings of one
header with different values cannot be resolved, and neither can be taken as the one the producer
meant, so that is ErrAmbiguousHeader and not a guess. The same value under two spellings is fine.
The exception is traceparent, whose case variants are not promoted: it is an extension, and an
extension's name must be lower case.
A conflict is only the content type¶
MassTransit has fields that transport headers can shadow. NServiceBus's headers are the transport's
headers, so the only value that can be set in two places is the content type: NServiceBus.ContentType
and the transport's own. The NServiceBus one is the producer's statement about its own message, so it
is the event's, and the transport's is kept as foreign content-type and listed in Conflicts.
The design is go/messaging spec 0014, D2, D9 and D10.