Skip to content

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.