feat(middleware): add BaggagePropagator for W3C Baggage

[yordis]

• W3C Trace Context and W3C Baggage are separate specifications with different lifetimes and risk profiles. Keeping them in distinct middleware modules lets each router declare propagation explicitly and keeps TraceContextPropagator's name accurate.
• Baggage entries persist in event metadata for the lifetime of the stream, so opting in must be a visible decision in the router rather than a silent config flag or default behavior.
• Updates the consumer-side extract_propagated_ctx/1 so a baggage-only metadata payload still produces a usable context, otherwise the new middleware would be a no-op for any handler not also receiving trace context.

[cursor]

PR Summary

Medium Risk
Adds a new OpenTelemetry propagation path that persists baggage into event metadata and changes context extraction behavior; misuse could inadvertently store sensitive or unbounded values and affect downstream handler context.

Overview
Adds opt-in W3C Baggage propagation alongside existing trace context propagation by introducing Commanded.Middleware.BaggagePropagator, which injects the baggage header into command/event metadata when present.

Updates Commanded.OpenTelemetry.Helpers.extract_propagated_ctx/1 to include baggage during extraction and to return a usable OpenTelemetry context even when only baggage (no traceparent) is provided; includes new tests and documentation describing usage and persistence implications.

^{Reviewed by Cursor Bugbot for commit 4a1dac1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Warning

Rate limit exceeded

@yordis has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 54 minutes and 20 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 31c96fcf-42bf-4edd-a58b-ca787bba247b

📥 Commits

Reviewing files that changed from the base of the PR and between 84df661 and 4a1dac1.

📒 Files selected for processing (1)

• guides/explanations/fork-differences.md

Walkthrough

This PR adds W3C baggage propagation to Commanded's OpenTelemetry instrumentation. It introduces a new BaggagePropagator middleware that injects baggage from the OpenTelemetry context into command metadata, and extends the helpers to extract and propagate baggage alongside span context.

Changes

W3C Baggage Propagation

Layer / File(s)	Summary
OpenTelemetry helpers baggage support lib/commanded/opentelemetry/helpers.ex, test/opentelemetry/helpers_test.exs	extract_propagated_ctx/1 now reads baggage from the extracted context and returns a context when baggage exists even if span context is missing; build_headers_from_metadata/1 includes baggage in propagated headers. Tests validate extraction and context behavior for baggage-only and combined traceparent+baggage metadata.
BaggagePropagator middleware implementation lib/commanded/middleware/baggage_propagator.ex, test/middleware/baggage_propagator_test.exs	New middleware reads W3C baggage from OpenTelemetry text-map propagator and injects it into pipeline metadata via before_dispatch/1; after_dispatch/1 and after_failure/1 are no-ops. Tests verify baggage capture, metadata preservation, round-trip W3C decoding, and no-op callbacks.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• straw-hat-team/commanded#90: Both PRs extend Commanded.OpenTelemetry.Helpers.extract_propagated_ctx/1 via metadata to influence OpenTelemetry context creation, with this PR adding W3C baggage support alongside the retrieved PR's traceparent/tracestate propagation.
• straw-hat-team/commanded#38: Both PRs add OpenTelemetry W3C context propagation into Commanded's pipeline metadata via before_dispatch/1 (traceparent/tracestate in TraceContextPropagator, baggage in BaggagePropagator) and extend the metadata→headers propagation path.

Poem

🐰 A rabbit hops with baggage in tow,
Through OpenTelemetry's W3C flow,
Context and traces now travel as one,
Metadata carries what once was done!
✨ bounces with delight

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a BaggagePropagator middleware for W3C Baggage support.
Description check	✅ Passed	The description is directly related to the changeset, explaining the rationale for separate middleware modules, persistence considerations, and required helper updates.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch yordis/feat-baggage-propagator-middleware

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

test/opentelemetry/helpers_test.exs (1)

87-87: 💤 Low value

Consider strengthening the link assertion for consistency.

The assertion assert [%{}] = links only verifies that one link exists but doesn't check its trace_id or span_id. Other tests in this file use more specific assertions (e.g., line 32). Consider matching against the expected trace_id for consistency:

-      assert [%{}] = links
+      assert [%{trace_id: ^expected_trace_id}] = links

However, if the focus is purely on baggage presence, the current assertion may be intentional.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/opentelemetry/helpers_test.exs` at line 87, Replace the weak pattern
match assert [%{}] = links with a stronger pattern that verifies the link's
trace_id (and optionally span_id) against the test's expected value — e.g.
assert [%{trace_id: ^expected_trace_id, span_id: _}] = links — so the test
checks the actual linked trace id (or keep the original if the intent truly is
only to assert presence of baggage).

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@test/opentelemetry/helpers_test.exs`:
- Line 87: Replace the weak pattern match assert [%{}] = links with a stronger
pattern that verifies the link's trace_id (and optionally span_id) against the
test's expected value — e.g. assert [%{trace_id: ^expected_trace_id, span_id:
_}] = links — so the test checks the actual linked trace id (or keep the
original if the intent truly is only to assert presence of baggage).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7d5d35c6-eb87-4f9b-9efd-2ebfad109410

📥 Commits

Reviewing files that changed from the base of the PR and between a64580b and 84df661.

📒 Files selected for processing (4)

• lib/commanded/middleware/baggage_propagator.ex
• lib/commanded/opentelemetry/helpers.ex
• test/middleware/baggage_propagator_test.exs
• test/opentelemetry/helpers_test.exs