feat: send Upstash-Workflow-CreatedAt so runs with the same id aren't deduplicated

[CahidArda]

Why

upstash/qstash-server#1129 (QSTH-1101) adds Upstash-Workflow-CreatedAt to the deduplication hash of workflow requests. The server forces content deduplication on every workflow request, and the hash only covered url, body, headers and run id. So a run started again with the same run id and the same data within the 10 minute window was deduplicated against the previous run. It either couldn't start, or got stuck on its first repeated step. This breaks singleton workflows (discussion #192) and invoked workflows that reuse a run id.

The server only adds the header to the hash when it is sent. Old SDKs therefore keep the old behaviour, and this SDK has to send it. The same PR updates the Go workflow SDK in qstash-server/workflow/. This PR does the same for workflow-js.

What changed

WorkflowConfig gets an optional workflowRunCreatedAt. getHeaders (src/qstash/headers.ts) adds Upstash-Workflow-CreatedAt as a raw header when it is set and non-zero. Everything else passes context.workflowRunCreatedAt into it. The context already reads it from the incoming request (src/serve/index.ts). This is the one-helper approach the Go SDK uses with populateWorkflowHeaders.

Mapping to the Go SDK (qstash-server#1129)

Request	workflow-js (this PR)	Go SDK counterpart
Header builder	WorkflowHeaders.addBaseHeaders() sets Upstash-Workflow-CreatedAt when workflowConfig.workflowRunCreatedAt is set (src/qstash/headers.ts)	populateWorkflowHeaders() sets CreatedAtHeader when meta.workflowCreatedAt != 0 (workflow/workflow.go)
Reading it from the incoming request	already there: workflowRunCreatedAt from the header in src/serve/index.ts	new: parseIncomingRequestMeta() reads it into meta.workflowCreatedAt
Next step	BaseLazyStep.getHeaders() (src/context/steps.ts)	callPublishForNextStep() → populateWorkflowHeaders(..., meta)
Parallel steps	submitParallelSteps() (src/qstash/submit-steps.ts)	same populateWorkflowHeaders path
waitForEvent + its timeout message	LazyWaitEventStep uses the step headers for the /v2/wait request, and timeoutHeaders is built from them	waitnotify.go: populateWorkflowHeaders on both the wait headers and timeoutHeaders
context.call	LazyCallStep inherits the step headers, so the call publish carries it	callCallbackForNextStep() → populateWorkflowHeaders(..., meta)
context.call result	Normal path: QStash builds the result step and now sets the header itself (worker/workflow_call.go); nothing needed in the SDK. Legacy fallback handleThirdPartyCallResult() copies the incoming header onto the result it publishes (src/workflow-requests.ts)	No SDK counterpart: Go always relies on the server-side conversion, which sets the header "so that the SDKs do not need to send it as a callback header"
Trigger (run doesn't exist yet)	triggerFirstInvocation() sends workflowRunCreatedAt || Date.now(). client.trigger already sets Date.now() once per call, so retries of the same request carry the same value and are still deduplicated	populateWorkflowHeadersTrigger(): options.workflowCreatedAt, or time.Now().UnixMilli() when 0
Second phase of the unknown SDK trigger	triggerFirstInvocation({ unknownSdk: true }) gets the run's creation time from the incoming request through the context	TriggerOptions{..., workflowCreatedAt: meta.workflowCreatedAt} on the meta.unknownSdk path
Invoke: triggering the invoked run	LazyInvokeStep.getHeaders() sends the invoker's context.workflowRunCreatedAt	callInvokeWorkflow() → populateWorkflowHeaders(upstashHeader, newWorkflowRunId, ..., meta), with the invoker's meta
Invoke: headers the invoked run reports back with	LazyInvokeStep.getBody() invokerHeaders carry it (the body already had workflowRunCreatedAt)	originHeader via populateWorkflowHeaders(..., meta) in invoke.go (body has WorkflowCreatedAt)
Delete at the end of a run / context.cancel()	triggerWorkflowDelete() sends the header when known. QStash then deletes/cancels the run only if its creation time matches, so a late delete of a previous run can't delete a new run with the same id	deleteWorkflowRun(workflowRunId, meta.workflowCreatedAt, ...)
Notify, webhooks, sleep, failure callbacks	unchanged	unchanged

Differences from Go

• handleThirdPartyCallResult is a JS-only legacy path; Go has no SDK-side call-result publish. The server now converts context.call results itself, so this path is mostly a fallback. It forwards the header so it can't reintroduce the deduplication problem.
• Direct first invocation (the endpoint called without QStash workflow headers) has no Go equivalent. It goes through triggerFirstInvocation, and when the context has no creation time it falls back to Date.now(), the same rule Go uses for triggers. The fallback lives in the trigger rather than in serve, so context.workflowRunCreatedAt is never made up for a non-first request. Otherwise every retry of a step would send a different value and stop being deduplicated.
• client.cancel() (the user API) is unchanged. The server's createdAt guard is only for an SDK deleting its own run.

Compatibility

The header is only sent when the creation time is known and non-zero. The server only includes it in the hash when present, so older servers still get the same requests. It should still be released after qstash-server#1129 is deployed.

Tests

New src/workflow-created-at.test.ts (14 tests):

• getHeaders adds the header when set, and omits it when undefined, 0 or NaN
• step, waitForEvent (request and timeout headers), context.call, and parallel steps (/v2/batch) carry it
• trigger sends the run's creation time when known, and the trigger time (Date.now mocked) when not
• delete and cancel send it, and omit it when unknown
• the legacy third-party call result forwards it
• serve end to end: an incoming request with the header → next step publish carries it; the finished workflow → delete carries it

Existing exact-header expectations were updated for trigger requests (client, serve, receiver, workflow-requests) and invoke requests (serve-many). The invoke tests now assert the invoked run is triggered with the invoker's creation time.

I checked the new tests against the source change reverted: 12 of 14 fail. The remaining 2 assert that the header is omitted.

bun test src: 419 pass. The 24 failures are the live tests that need QSTASH_TOKEN; they fail identically on main without a token. tsc, eslint, prettier --check and bun run build pass.

Worth verifying

In the server PR's singleton test, a new trigger for a run id that is still in progress returns 400 "a workflow already exists" (via /v2/trigger). Before this change, an identical client.trigger for an in-progress run could be deduplicated. With a fresh Date.now() per call it now reaches that check, and it may throw instead of returning "workflow-run-already-exists". client.trigger goes through /v2/batch, which the server tests don't cover, so this is worth checking against a server with #1129 deployed.

🤖 Generated with Claude Code

https://claude.ai/code/session_017dm7F4hg2khgYDqBwP9nx5