Structures

A Baggage is a heterogeneous storage type with value semantics for keyed values in a type-safe fashion.

Its values are uniquely identified via Baggage.Keys (by type identity). These keys also dictate the type of value allowed for a specific key-value pair through their associated type Value.

Defining keys and accessing values

Baggage keys are defined as types, most commonly case-less enums (as no actual instances are actually required) which conform to the Baggage.Key protocol:

private enum TestIDKey: Baggage.Key {
  typealias Value = String
}

While defining a key, one should also immediately declare an extension on Baggage, to allow convenient and discoverable ways to interact with the baggage item, the extension should take the form of:

extension Baggage {
  var testID: String? {
    get {
      self[TestIDKey.self]
    } set {
      self[TestIDKey.self] = newValue
    }
  }
}

For consistency, it is recommended to name key types with the ...Key suffix (e.g. SomethingKey) and the property used to access a value identifier by such key the prefix of the key (e.g. something). Please also observe the usual Swift naming conventions, e.g. prefer ID to Id etc.

Usage

Using a baggage container is fairly straight forward, as it boils down to using the prepared computed properties:

var baggage = Baggage.topLevel
// set a new value
baggage.testID = "abc"
// retrieve a stored value
let testID = baggage.testID ?? "default"
// remove a stored value
baggage.testIDKey = nil

Note that normally a baggage should not be “created” ad-hoc by user code, but rather it should be passed to it from a runtime. For example, when working in an HTTP server framework, it is most likely that the baggage is already passed directly or indirectly (e.g. in a FrameworkContext)

Accessing all values

The only way to access “all” values in a baggage context is by using the forEach function. The baggage container on purpose does not expose more functions to prevent abuse and treating it as too much of an arbitrary value smuggling container, but only make it convenient for tracing and instrumentation systems which need to access either specific or all items carried inside a baggage.

See more

public struct Baggage

extension Baggage: CustomStringConvertible

Carried automatically by a “to do” baggage. It can be used to track where a context originated and which “to do” context must be fixed into a real one to avoid this.

See more

public struct TODOLocation

A type-erased BaggageKey used when iterating through the Baggage using its forEach method.

See more

public struct AnyBaggageKey

extension AnyBaggageKey: Hashable