Skip to content

Carrier helpers: pass operation context into queue jobs, headers and SQS messages - #53

Merged
sagnik11 merged 1 commit into
mainfrom
feat/carrier-helpers
Nov 15, 2026
Merged

sagnik11 merged 1 commit into
mainfrom
feat/carrier-helpers

Conversation

@sagnik11

@sagnik11 sagnik11 commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

What users saw

Operation context did not cross processes or queues. A job enqueued inside a request ran in the worker as an unrelated operation: no parent operation, no request id, nothing tying the worker's errors to the request that caused them.

Cause

The mechanism already existed (runtimeContext.carrier() on the producer, withRuntimeOperation(name, fn, attrs, { from }) on the consumer), but there was no helper to put the carrier into a job payload, HTTP headers or an SQS message, from only accepted the bare carrier, and there were no recipes.

What changes

  • @autter/runtime-core (private, bundled): CARRIER_KEY = "autter", injectCarrier(target, carrier, format = "payload") and extractCarrier(source), thin wrappers over parseCarrier.
    • "payload": { ...data, autter: carrier }; "headers": header autter: <carrier JSON> (a differently-cased old one is replaced; a Headers instance is always treated as headers and comes back as a new Headers); "sqs": { autter: { DataType: "String", StringValue: <carrier JSON> } }.
    • injectCarrier never mutates its input: plain objects come back as shallow copies. With no valid carrier, or a target that cannot hold a key (array, primitive, class instance), it returns the target unchanged.
    • extractCarrier reads the carrier itself (object or JSON string), a payload with the autter key (the key wins over carrier-looking fields of the payload), headers (any case, Node's single-entry list too), SQS MessageAttributes (SDK StringValue/DataType and Lambda stringValue/dataType) or a whole SQS message. It applies parseCarrier's limits, returns undefined for anything missing, malformed or oversized, and never throws (a hostile Proxy is tested).
    • Carrier v1 is unchanged: { v: 1, op, req?, traceparent? }. Injection re-validates the carrier, so only those four fields are ever written: no attributes, user context or baggage.
  • @autter/runtime-node: runtimeContext.inject(target, format?) returns a copy carrying the current operation's carrier. Outside an operation it returns the target itself, unchanged, and never throws. withRuntimeOperation's from now takes a carrier, a JSON string, or a payload/headers/attributes object (or SQS message) that contains the key. A malformed from starts the operation unlinked, as before.
  • @autter/runtime-next: the root's browser and edge stand-ins get runtimeContext.inject (returns the target), because the compile-time export-parity check types the stand-ins against the server's runtimeContext.
  • docs/OPERATION-LOGGING.md: a "Queues, workers and other processes" section with BullMQ, SQS and Celery recipes. It says the consumer's trace is linked rather than continued, and that the request id is what joins them. For Celery it says OpenTelemetry's instrumentation already continues the trace and no Autter helper is needed. BullMQ and the AWS SDK are not dependencies; the recipes are documentation only.

CHANGELOG.md is left to the docs/changelog PR that follows this one.

Tests

  • runtime-core/test/core.test.mjs: round trips for each shape (payload, JSON-serialised payload, header map in any case, Headers, SQS attributes, SDK and Lambda SQS messages), no mutation, only carrier fields written, malformed/oversized/hostile input, targets that cannot hold a key.
  • runtime-node/test/operations.test.mjs: end to end, an operation inside a request injects into a job payload, the payload goes through JSON, and the consumer started with { from: job.data } has the producer's parent operation id, request id and parent trace id, plus an exported span link to the producer trace with its own trace id. The test also covers headers and SQS, and inject outside an operation returning the target unchanged. No fixed sleeps.
  • Checked locally: npm run build; runtime-core, runtime-edge (bundles runtime-core) and runtime-next tests; runtime-node operations.test.mjs; the browser size gate (npm run size -w @autter/runtime-browser; runtime-browser does not import runtime-core).

🤖 Generated with Claude Code


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.

…SQS messages

runtime-core gains CARRIER_KEY ("autter"), injectCarrier(target, carrier,
format?) and extractCarrier(source): thin wrappers over parseCarrier for a
job payload, HTTP headers (case-insensitive name) and SQS MessageAttributes.
injectCarrier returns a copy and never mutates; extractCarrier returns
undefined for anything malformed or oversized and never throws. Carrier v1
is unchanged: ids only, no attributes, user context or baggage.

runtime-node: runtimeContext.inject(target, format?) returns a copy carrying
the current operation's carrier, and the target unchanged outside an
operation. withRuntimeOperation's `from` now also accepts a payload,
headers, MessageAttributes or a whole SQS message that contains the key.
runtime-next's browser/edge root stand-ins get a matching inject.

Docs: BullMQ, SQS and Celery recipes in docs/OPERATION-LOGGING.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sagnik11
sagnik11 merged commit 27fa8d9 into main Nov 15, 2026
18 checks passed
sagnik11 added a commit that referenced this pull request Nov 15, 2026
…ommit detection, test environments and queue helpers (#57)

- @autter/runtime-next/client: initAutterBrowser turns on same-origin
  trace propagation by default (tracePropagation: false opts out;
  tracePropagationTargets adds cross-origin APIs). Third-party origins and
  the tracker's own endpoint never get a traceparent. Does nothing outside a
  browser. An enableTracePropagation/disableTracePropagation call made before
  initAutterBrowser keeps its effect. Plain @autter/runtime-browser stays
  opt-in; its dist is unchanged.
- runtime-cli: `sourcemaps setup` prints the trace propagation step (with
  the CORS note) for browser setups.
- runtime-node: log records' resource carries deployment.commit, like the
  trace resource, for initAutterServer and initAutterLogging. Added in the
  OTLP log sink, so runtime-core's encoder (shared with runtime-edge) and
  runtime-edge's dist stay unchanged.
- Docs: Getting started (release/commit defaults, enableTracePropagation,
  test runs), Integrations (FastAPI and Django CORS, Python detection and
  opt-outs), Requests and errors, Architecture (sink `commit`), package
  READMEs. CHANGELOG [Unreleased] for #53-#56 and this change.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant