@spec default_getter(carrier :: [{String.t(), String.t()}], key :: String.t()) ::
  String.t() | nil

Application (W3C header parsing) — Getter for [{String.t(), String.t()}] carriers (api-propagators.md §Get L221-L230 + §GetAll L232-L249).

Case-insensitive key lookup. Returns nil when no matching entry exists; for a single match, returns the value as-is; for multiple matching entries, returns their values joined with ",".

Intentional divergence from spec §Get L223

Spec L223: "The Get function MUST return the first value of the given propagation key or return null if the key doesn't exist." Strictly read, our behaviour on multiple matches violates this MUST — we combine instead of returning the first.

We diverge because the spec's §Get vs §GetAll split is the wrong abstraction for HTTP carriers:

• Per RFC 9110 §5.3 "a recipient MAY combine multiple instances of a list-based field into one field-value, by appending each subsequent value to the combined value using a comma". Combination is the canonical recipient operation for list-based fields.
• Both W3C Baggage L6 ("Multiple baggage headers are allowed. Values can be combined in a single header according to RFC 7230") and W3C TraceContext §3.3.1.5 ("multiple tracestate headers ... combined into one") are list-based fields that REQUIRE combination for correct extraction.
• Returning only the first value here would silently drop list-members from any carrier that preserved the raw split form (e.g. :cowboy_req:headers/1), corrupting downstream W3C parsing.

In other words, the spec's §Get-only contract is wrong for HTTP list-field extraction; honouring it strictly would break tracestate / baggage interop. The combined-result behaviour is decoded correctly by downstream parsers regardless of OWS per the W3C grammars (list-member 0*179( OWS "," OWS list-member )) and matches what encode_baggage/1 would emit on inject.

Callers needing strict §Get semantics (first-only) can supply a custom getter to extract/3. We keep the default combined-result behaviour because it is what the in-tree W3C propagators (text_map/baggage.ex, text_map/trace_context.ex) need.

Spec L230 mandates case-insensitive matching for HTTP-like carriers; that part is honoured.

@spec default_setter(
  key :: String.t(),
  value :: String.t(),
  carrier :: [{String.t(), String.t()}]
) :: [{String.t(), String.t()}]

Application (W3C header serialization) — Setter.Set (api-propagators.md L174-L186) for [{String.t(), String.t()}] carriers.

Implements spec's "Replaces a propagated field with the given value" (L178) together with the casing rule at L186. Two behaviours to notice:

• Matching existing entries — the carrier is scanned case-insensitively and any entry whose key matches the supplied key is removed before the new pair is appended. Spec §Setter.Set does not literally mandate case-insensitive matching, but HTTP header names are case-insensitive per RFC 9110 and [{String.t(), String.t()}] carriers are HTTP-like, so matching case-insensitively is the only way to honour spec's "Replaces" without leaving duplicate headers behind.

• Casing preservation on write — the supplied key is written to the carrier as-is, satisfying spec L186 "The implementation SHOULD preserve casing" for case-insensitive protocols (MUST for case-sensitive ones).

@spec extract(ctx :: Otel.API.Ctx.t(), carrier :: carrier(), getter :: getter()) ::
  Otel.API.Ctx.t()

Application (OTel API SHOULD) — extract via the global propagator (api-propagators.md L310-L313).

Dispatches to get_propagator/0's current value. When no propagator is installed the Noop default returns the context unchanged (spec L322-L325).

getter defaults to default_getter/2 for [{String.t(), String.t()}] carriers.

@spec get_propagator() :: {module(), term()} | module()

Application (OTel API MUST) — "Get Global Propagator" (api-propagators.md L334-L338).

Returns the globally registered TextMap propagator. When no propagator has been installed via set_propagator/1, returns Otel.API.Propagator.TextMap.Noop, satisfying spec L322-L325 "MUST use no-op propagators unless explicitly configured otherwise".

Callers can pass the result directly to inject_with/4 / extract_with/4 without nil-checking — the Noop implementation is spec-conformant and always present.

@spec inject(ctx :: Otel.API.Ctx.t(), carrier :: carrier(), setter :: setter()) ::
  carrier()

Application (OTel API SHOULD) — inject via the global propagator (api-propagators.md L310-L313 "Instrumentation libraries SHOULD call propagators to extract and inject the context on all remote calls").

Dispatches to get_propagator/0's current value. When no propagator is installed the Noop default returns the carrier unchanged (spec L322-L325).

setter defaults to default_setter/3 for [{String.t(), String.t()}] carriers.

@spec set_propagator(propagator :: {module(), term()} | module()) :: :ok

Application (OTel API MUST) — "Set Global Propagator" (api-propagators.md L340-L346).

Registers a propagator as the global TextMap propagator. Accepts either an atom module (for single-header propagators like TextMap.TraceContext) or a {module, opts} tuple (for configured propagators like TextMap.Composite produced by Otel.API.Propagator.TextMap.Composite.new/1).