Transport-specific metadata associated with a message.

The semantics of the metadata are not defined in this protocol, but rather, depend on the transport on which a particular instance of the metadata maps to. What keys or values are allowed or disallowed, whether duplicate values for the same key are allowed and how they are handled, and whether key names are case sensitive or not, are all undefined in the context of the Kalix protocol.

If a metadata entry associated with a message can't be expressed in an underlying transport, for example, due to invalid characters in a key or value, the behavior of the proxy is undefined. This is because metadata is transport specific, so if the user service chooses to use metadata, it is choosing to be specific to a particular transport, which is beyond the scope of the Kalix protocol, and it's therefore the user services's responsibility to adhere to the semantics of that transport. The proxy MAY decide to drop metadata entries if it knows they are invalid or unsupported. If a metadata entry is dropped, the proxy MAY inform the user service that the entry was dropped by sending an error message to the Discovery.ReportError gRPC call.

The metadata MAY also contain CloudEvent metadata. If a message comes from an Kalix event source, the Kalix proxy MUST attach CloudEvent metadata to it if the event doesn't already have CloudEvent metadata attached to it. This metadata SHALL be encoded according to the binary mode of the CloudEvent HTTP protocol binding, which can be found here:

https://github.com/cloudevents/spec/blob/master/http-protocol-binding.md

The Kalix proxy MAY synthesize appropriate values for Kalix metadata if no equivalent metadata exists in the event source, for example, if there is no type, the Kalix proxy MAY use the name of the gRPC message as the CloudEvent type, and if there is no source, the Kalix proxy MAY use the name of the topic as the source.

If an incoming message does have CloudEvent metadata attached to it, the Kalix proxy MUST transcode that CloudEvent metadata to the HTTP protocol binding as described above.

Messages sent from the user service to an event destination MAY include CloudEvent metadata. If they include any CloudEvent metadata, they MUST include all required CloudEvent attributes, including id, source, specversion and type. The behavior of the proxy is undefined if some of these attributes, but not others, are included - the proxy MAY ignore them all, or MAY generate values itself, but SHOULD NOT fail sending the message. If the destination for the message is an event destination, the Kalix proxy MUST transcode the supplied Kalix metadata to a binding appropriate for the underlying transport for that event destination, it MUST NOT pass the CloudEvent metadata as is unless the transport uses the same binding rules.