Vercel News

Workflow SDK adds idempotent starts

8.5内容质量

TL;DR · AI 摘要

Vercel Workflow SDK 新增原子化 start() 函数,通过 token 实现幂等性,消除工作流重复启动问题。

核心要点

  • 原子化 start() 函数合并了 run 和 claim hook 操作,消除 duplicate-start race 条件
  • token 作为幂等性键,可使用订单号、发票号等业务标识符实现无额外代码的幂等控制
  • HookConflictError 异常处理机制可将重复请求的负载路由至已有 run

结构提纲

按章节快速跳转。

  1. 宣布 Workflow SDK 新增原子化 start() 函数,解决 duplicate-start race 问题

  2. 新 start() 函数在单个原子步骤中完成 run 和 hook claim 操作

  3. 展示如何在 API 路由中使用 start() 和 resumeHook 处理冲突

  4. 通过 token 实现无额外代码的幂等控制,保证唯一 run 拥有 token

  5. createHook 与 start() 时声明的 token 绑定,确保无冲突

  6. experimental_minRetention 参数控制 token 在 run 结束后的不可用时间

思维导图

用一张图看清主题之间的关系。

查看大纲文本(无障碍 / 无 JS 友好)
  • Workflow SDK 原子化 start
    • 核心机制
      • 原子操作合并 run 和 hook claim
      • 消除 duplicate-start race
    • 幂等性实现
      • token 作为幂等键
      • HookConflictError 处理
    • 实验性配置
      • experimental_minRetention 参数

金句 / Highlights

值得收藏与分享的关键句。

  • 原子化 start() 函数在单个步骤中执行 run 和 claim hook,消除 duplicate-start race

    — 第 1 段

    ⬇︎ 下载 PNG𝕏 分享到 X
  • token 作为幂等性键,保证 Exactly one run owns it,duplicate start() 抛出 HookConflictError

    — 第 3 段

    ⬇︎ 下载 PNG𝕏 分享到 X
  • createHook 与 start() 时声明的 token 绑定,无冲突可能且无需新增步骤

    — 代码示例 2

    ⬇︎ 下载 PNG𝕏 分享到 X
#Workflow SDK#幂等性#Vercel#前端开发
打开原文

The Workflow SDK's start() function can now admit a run and claim a hook in one atomic step. Duplicate workflow starts fail safely. The atomic start replaces the previous getHookByToken()-then-start() pattern, whose gap between the lookup and the start left a documented duplicate-start race.

app/api/orders/route.ts

import { resumeHook, start } from "workflow/api";import { HookConflictError } from "workflow/errors";import { processOrder } from "./workflows/process-order";export async function POST(request: Request) { const { orderId, note } = await request.json(); const token = order:${orderId}; try { const run = await start(processOrder, [orderId, note], { experimental_hook: { token }, }); return Response.json({ runId: run.runId, started: true }); } catch (error) { if (!HookConflictError.is(error)) throw error; // Route the duplicate's payload to the run that owns the token const hook = await resumeHook(token, { note }); return Response.json({ runId: hook.runId, started: false }); }}

Starting a run idempotently and routing a duplicate's payload to the run that already owns the token

[Copy link to heading](https://vercel.com/changelog/atomic-start-hooks-in-the-workflow-sdk#subscribe-to-messages-inside-the-run)Subscribe to messages inside the run

The claimed Hook exists from the moment the run is admitted, so resumeHook works even before the run begins executing, and early payloads are buffered and delivered in order. Inside the workflow, createHook({ token }) with the same token binds to the already-claimed hook: guaranteed, registering nothing new, adding no step, and resolving getConflict() to null.

workflows/process-order.ts

import { createHook } from "workflow";type OrderUpdate = { note: string };export async function processOrder(orderId: string, note: string) { "use workflow"; await recordNote(orderId, note); // Binds to the hook claimed at start: no conflict possible, no extra step const updates = createHook<OrderUpdate>({ token: order:${orderId} }); for await (const update of updates) { await recordNote(orderId, update.note); }}

Binding to the start Hook inside the run to consume payloads in order

[Copy link to heading](https://vercel.com/changelog/atomic-start-hooks-in-the-workflow-sdk#idempotency-with-no-extra-code)Idempotency with no extra code

The token is the idempotency key, and it comes from your own domain: an order ID, an invoice ID, an import ID, or a request ID. The token alone guarantees idempotency. Exactly one run owns it, and a duplicate start() throws HookConflictError carrying the owner's conflictingRunId and never becomes a run. The workflow doesn't have to open the hook at all, and if it never does, the token was only an idempotency key and the run completes normally.

Setting experimental_minRetention keeps the token unavailable after the run ends, counted from start(), so late duplicates are still refused.

Upgrade to workflow5.4.0 and read the idempotency documentation to get started.