What belongs in a message envelope that an intermediary must read without decoding the payload it wraps?

## Framing and envelope are different jobs Framing says **where the message ends**. The envelope says **what is inside it**. On the wire they usually stack, and separating them is the first thing to say in an interview: ``` [ frame header: marker | format id | total length ][ envelope ][ payload bytes ] ``` The framing header is read by the loop that cuts the stream. The envelope is read by everything downstream of that cut — routers, consumers, dead-letter handlers, audit trails — and none of them should have to decode the payload to do their job. ## Fields that earn their place **Identity** - **Message id** — unique per message, so a consumer can detect a redelivery and a duplicate. Without it, at-least-once delivery cannot be made effectively-once at the consumer. - **Producer or source identifier** — which writer emitted this, needed for quarantine and for attributing a bad batch. **Interpretation** - **Content type** — the class of encoding, expressed as a media type, so a consumer picks a decoder rather than guessing from the first byte. - **Schema or contract identifier, with a version** — which contract these bytes claim to satisfy. This is what makes a payload decodable at all when the encoding is schema-driven, and what lets a consumer reject cleanly instead of misreading. - **Message type or event name** — the semantic kind, on which subscriptions are usually built. **Integrity and size** - **Payload length** — lets a hop skip, forward or store the body without parsing it. - **Checksum** — computed over the raw payload bytes so corruption or truncation is caught **before** a decoder ever sees them. **Context** - **Timestamp** — when the fact occurred or the message was produced, used for ordering heuristics and age-based expiry. - **Correlation and causation ids, tracing context** — which request this belongs to and which message caused it, so a chain that spans several hops can be reconstructed from metadata alone. ## Who reads what | Envelope field | Who reads it without decoding | What breaks without it | |---|---|---| | Routing key / message type | The intermediary dispatching the message | Every hop must decode the body to route | | Content type | The consumer choosing a decoder | Format sniffing, and silent misreads | | Schema id and version | The consumer and the audit path | A payload that cannot be interpreted at all | | Message id | The consumer deduplicating redeliveries | Duplicate side effects on retry | | Correlation id | Tracing and the on-call engineer | A chain that cannot be reconstructed | | Payload length | Any hop forwarding or storing bytes | No way to skip or bound the body | | Checksum | The reader before decoding | Truncation surfaces as a confusing decode error | ## Why the envelope must be the cheaper contract The envelope is parsed by **every** participant, including ones that have never heard of the payload's schema. That forces three properties: 1. **Self-describing or fixed-layout**, so no separate lookup is needed to read it. 2. **Small and stable**, because a change to it is a change every hop must tolerate. Envelope fields are the hardest fields in the system to modify. 3. **Additive by design** — an unknown envelope header must be forwarded untouched, not dropped, or an intermediary silently strips metadata a later hop needed. An envelope is also the natural home for metadata about a payload that a hop *cannot* read: a payload that is compressed or encrypted still needs to be routed, and only envelope fields make that possible. ## Failure modes worth naming - **Duplicated facts.** The same field in both envelope and payload drifts; when they disagree, nothing on the wire says which is authoritative. - **Sensitive data in headers.** Envelope fields are visible to every hop and usually to logs and traces, so payload secrets must not be copied there for convenience. - **The envelope as a covert API.** Once consumers can act on rich headers, some stop decoding bodies entirely, and a field added for observability quietly becomes load-bearing. - **An envelope that cannot be read alone.** If reading a header requires the payload's schema, the envelope has failed at its only job. ## The interview answer Lead with the test rather than a list: *a fact belongs in the envelope when a component that cannot decode the body still needs it*. Everything above follows from that one sentence, and it is also what stops the envelope growing into a second copy of the schema.