docs(api): clarify `TextMapPropagator` API requirements

[chancancode]

trafficstars

Non-breaking parts from #5368

Which problem is this PR solving?

The current interface places the generic paramter on the interface itself. This implies that the implementors of TextMapPropagator can specify what carrier types it accepts (and that each implementor only work with one specific type of carrier).

interface TextMapPropagator<Carrier> {
  inject(context: Context, carrier: Carrier, setter: TextMapSetter<Carrier>): void;
  extract(context: Context, carrier: Carrier, getter: TextMapGetter<Carrier>): void;
}

In reality, this is not the case.

The propagator API is designed to be called by participating code around the various transport layers (such as the fetch inst on the browser, or integration with the HTTP server library on the backend), and it is these callers that ultimately controls what carrier type the currently configured propagator is called with.

Therefore, a correct implementation of this interface must treat the carrier as an opaque value, and only work with it using the provided getter/setter.

Ideally, the interface should look like this instead:

interface TextMapPropagator {
  inject<Carrier>(context: Context, carrier: Carrier, setter: TextMapSetter<Carrier>): void;
  extract<Carrier>(context: Context, carrier: Carrier, getter: TextMapGetter<Carrier>): void;
}

This communicates and enforces the contract. Unfortunately, that would be a breking change we are not currently prepared to make (see #5368).

Short description of the changes

Instead, this commit updates the documentation to explicitly document the discrapancy and advice implemntors the correct way forward.

It also updates our own implementations to follow the recommended pattern, as well as updating the tests to be more well-behaved around this, as some of them are written to rely on this exact behavior that would be problematic in the real world.

Ref #5365 Ref #5368

Type of change

Please delete options that are not relevant.

• [ ] Bug fix (non-breaking change which fixes an issue)
• [ ] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
• [x] This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration

• [ ] Test A

Checklist:

• [x] Followed the style guidelines of this project
• [x] Unit tests have been ~~added~~ updated
• [x] Documentation has been updated