Skip to main content

Context Propagation

SandboxMesh routes traffic by inspecting a selector header (defaulting to the W3C baggage header). To keep a request tied to your preview environment as it travels through your architecture, that header needs to travel with it.

If your request hits a service that drops the header, subsequent downstream calls will fall back to your baseline environment.

Use this guide to ensure your sandbox context survives:

  • Service-to-service HTTP calls
  • Asynchronous queues and background jobs
  • Outbound HTTP calls made by workers

The Golden Rule: Use baggage​

We strongly recommend sticking with the default baggage header. Because it is a W3C standard, it plugs directly into modern tracing and context-propagation tools (like OpenTelemetry).

When you use baggage:

  • Inbound requests already carry your sandbox selector in a standardized format.
  • Context flows naturally through service-to-service calls.
  • OpenTelemetry handles propagation automatically for most modern frameworks.

HTTP Request Propagation​

For synchronous, request-to-request traffic, the pattern is straightforward:

  1. Read the incoming selector context.
  2. Attach it to the current request's context.
  3. Copy it onto any outbound HTTP calls heading to internal services.
Browser ──> API Service ──> Downstream Service ──> Downstream Service

Every internal hop must carry the baggage header to remain sandbox-aware.

Async Jobs & Background Workers​

When dealing with queues, the goal is usually to ensure that when a worker picks up a job, any outbound HTTP calls it makes still land in your sandboxed services.

  1. An HTTP request enters your API with baggage: sandbox=sbx-123.
  2. The API enqueues a job. Crucially, it copies the baggage value into the job's metadata or message attributes.
  3. The background worker picks up the job and extracts the sandbox context.
  4. The worker applies that context to any outbound HTTP requests it makes.

Implementing Message Contracts​

You have two clean paths for passing this context:

  • Explicit Metadata: Store the raw baggage string directly in your message payload or headers. This is simple, explicit, and easy to debug.
  • OpenTelemetry Propagators: If your stack uses OpenTelemetry, use its propagators to inject the context into your message carrier and extract it on the worker side.

What if the worker logic itself is under test?​

If you need to test a new version of the worker code itself (not just where it sends outbound requests), context propagation alone isn't enough. You need the sandboxed worker to actually consume the message.

We recommend using:

  • A dedicated queue specifically for the sandboxed worker.
  • A shared topic utilizing a sandbox attribute and a filtered subscription.

Anti-pattern to avoid: Do not use a shared queue where non-matching workers constantly NACK or requeue sandbox-tagged messages. It creates noisy retry loops and unpredictable behavior.

Checklist for Success​

  • Propagate the baggage header on all internal outgoing HTTP calls.
  • At enqueue time, copy the baggage context into your message metadata.
  • At dequeue time, restore the context before making outbound HTTP calls.
  • Strip the sandbox context before making external egress calls to third-party APIs (unless you explicitly need them to receive it).
  • If testing worker logic directly, use sandbox-aware queue routing or dedicated topics.