[V0_FILE]typescriptreact:file="app/components/retryable-rate-limit-code-workbench.tsx" "use client"; import { useEffect, useMemo, useRef, useState } from "react"; type HighlightTone = "amber" | "cyan" | "green" | "red"; type CopyState = "idle" | "copied" | "failed"; type HighlightStyle = { border: string; bg: string; text: string; }; const HIGHLIGHT_STYLES: Record = { amber: { border: "border-amber-700", bg: "bg-amber-700/15", text: "text-amber-700", }, cyan: { border: "border-cyan-700", bg: "bg-cyan-700/15", text: "text-cyan-700", }, green: { border: "border-green-700", bg: "bg-green-700/15", text: "text-green-700", }, red: { border: "border-red-700", bg: "bg-red-700/15", text: "text-red-700", }, }; const CHECKMARK_POINTS = "3,8.5 7,12.5 14,4.5"; type GutterMarkKind = "success" | "fail"; type CodePaneProps = { code: string; htmlLines: string[]; activeLines: number[]; gutterMarks: Record; filename: string; subtitle: string; tone: HighlightTone; }; function CodePane({ code, htmlLines, activeLines, gutterMarks, filename, subtitle, tone, }: CodePaneProps) { const [copyState, setCopyState] = useState("idle"); const activeLineSet = useMemo(() => new Set(activeLines), [activeLines]); const gutterMarkMap = useMemo(() => new Map(Object.entries(gutterMarks).map(([k, v]) => [Number(k), v])), [gutterMarks]); const prevMarkRef = useRef>(new Map()); const isFullReset = gutterMarkMap.size === 0 && activeLines.length === 0; useEffect(() => { if (isFullReset) { prevMarkRef.current.clear(); return; } gutterMarkMap.forEach((kind, line) => { prevMarkRef.current.set(line, kind); }); }, [gutterMarkMap, isFullReset]); const highlightStyle = HIGHLIGHT_STYLES[tone]; const handleCopy = async () => { try { await navigator.clipboard.writeText(code); setCopyState("copied"); window.setTimeout(() => setCopyState("idle"), 1200); } catch { setCopyState("failed"); window.setTimeout(() => setCopyState("idle"), 1200); } }; return (

{filename}

{subtitle}

          
            {htmlLines.map((lineHtml, index) => {
              const lineNumber = index + 1;
              const isActive = activeLineSet.has(lineNumber);
              const markKind = gutterMarkMap.get(lineNumber);
              const displayKind = isFullReset
                ? undefined
                : markKind ?? prevMarkRef.current.get(lineNumber);

              return (
                
                  
                    
                  
                  
                    {lineNumber}
                  
                   0 ? lineHtml : " ",
                    }}
                  />
                
              );
            })}

); } export type RateLimitCodeWorkbenchProps = { workflowCode: string; workflowHtmlLines: string[]; workflowActiveLines: number[]; workflowGutterMarks: Record; stepCode: string; stepHtmlLines: string[]; stepActiveLines: number[]; stepGutterMarks: Record; tone: HighlightTone; }; export function RateLimitCodeWorkbench({ workflowCode, workflowHtmlLines, workflowActiveLines, workflowGutterMarks, stepCode, stepHtmlLines, stepActiveLines, stepGutterMarks, tone, }: RateLimitCodeWorkbenchProps) { return (

); } [V0_FILE]typescriptreact:file="app/components/demo.tsx" "use client"; import { useCallback, useEffect, useMemo, useRef, useState } from "react"; import type { AttemptSnapshot, MockRateLimitSnapshot, RetryLogEvent, } from "@/app/api/mock/store"; import { RateLimitCodeWorkbench } from "./retryable-rate-limit-code-workbench"; type LifecycleState = "idle" | "running" | "completed" | "failed"; type HighlightTone = "amber" | "cyan" | "green" | "red"; type StartResponse = { runId: string; status: "running" | "completed" | "failed"; snapshot: MockRateLimitSnapshot; }; type WorkflowLineMap = { fetchCall: number[]; upsertCall: number[]; successReturn: number[]; }; type StepLineMap = { fetchCall: number[]; retryableErrorThrow: number[]; serverErrorThrow: number[]; returnJson: number[]; }; type RateLimitDemoProps = { workflowCode: string; workflowHtmlLines: string[]; workflowLineMap: WorkflowLineMap; stepCode: string; stepHtmlLines: string[]; stepLineMap: StepLineMap; }; const POLL_INTERVAL_MS = 120; const DEFAULT_CONTACT_ID = "contact-42"; const DEFAULT_FAIL_FIRST = 2; const FAIL_FIRST_MIN = 0; const FAIL_FIRST_MAX = 4; const FAIL_FIRST_OPTIONS = Array.from( { length: FAIL_FIRST_MAX - FAIL_FIRST_MIN + 1 }, (_, index) => FAIL_FIRST_MIN + index ); function formatDurationLabel(durationMs: number): string { if (durationMs >= 1000 && durationMs % 1000 === 0) { return `${durationMs / 1000}s`; } return `${durationMs}ms`; } function formatElapsedLabel(durationMs: number): string { const seconds = (durationMs / 1000).toFixed(2); return `${seconds}s`; } async function postJson( url: string, body: Record, signal: AbortSignal ): Promise { const response = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify(body), signal, }); const payload = (await response .json() .catch(() => ({ error: "Failed to parse JSON response" }))) as | T | { error?: string }; if (signal.aborted) { throw new DOMException("Request aborted", "AbortError"); } if (!response.ok) { const message = typeof payload === "object" && payload && "error" in payload ? (payload.error ?? `Request failed (${response.status})`) : `Request failed (${response.status})`; throw new Error(message); } return payload as T; } export function RateLimitDemo({ workflowCode, workflowHtmlLines, workflowLineMap, stepCode, stepHtmlLines, stepLineMap, }: RateLimitDemoProps) { const [contactId, setContactId] = useState(DEFAULT_CONTACT_ID); const [failFirst, setFailFirst] = useState(DEFAULT_FAIL_FIRST); const [lifecycle, setLifecycle] = useState("idle"); const [runId, setRunId] = useState(null); const [snapshot, setSnapshot] = useState(null); const [error, setError] = useState(null); const pollTimerRef = useRef | null>(null); const inFlightRef = useRef(false); const abortRef = useRef(null); const startButtonRef = useRef(null); const stopPolling = useCallback(() => { if (pollTimerRef.current) { clearInterval(pollTimerRef.current); pollTimerRef.current = null; } inFlightRef.current = false; }, []); const ensureAbortController = useCallback((): AbortController => { if (!abortRef.current || abortRef.current.signal.aborted) { abortRef.current = new AbortController(); } return abortRef.current; }, []); useEffect(() => { return () => { stopPolling(); abortRef.current?.abort(); abortRef.current = null; }; }, [stopPolling]); const fetchStatusSnapshot = useCallback(async (targetRunId: string, signal: AbortSignal) => { const response = await fetch( `/api/mock/status?runId=${encodeURIComponent(targetRunId)}`, { cache: "no-store", signal, } ); const payload = (await response .json() .catch(() => ({ error: "Failed to parse status response" }))) as | MockRateLimitSnapshot | { error?: string }; if (signal.aborted) { throw new DOMException("Request aborted", "AbortError"); } if (!response.ok) { const message = typeof payload === "object" && payload && "error" in payload ? payload.error ?? `Status request failed (${response.status})` : `Status request failed (${response.status})`; throw new Error(message); } return payload as MockRateLimitSnapshot; }, []); const beginPolling = useCallback( (targetRunId: string) => { stopPolling(); const poll = async () => { if (inFlightRef.current) { return; } inFlightRef.current = true; let signal: AbortSignal | null = null; try { const controller = ensureAbortController(); signal = controller.signal; const nextSnapshot = await fetchStatusSnapshot(targetRunId, signal); if (signal.aborted) { return; } setSnapshot(nextSnapshot); if (nextSnapshot.status === "completed") { if (signal.aborted) { return; } setLifecycle("completed"); stopPolling(); return; } if (nextSnapshot.status === "failed") { if (signal.aborted) { return; } setLifecycle("failed"); stopPolling(); return; } if (signal.aborted) { return; } setLifecycle("running"); } catch (pollError) { if ((signal && signal.aborted) || (pollError instanceof Error && pollError.name === "AbortError")) { return; } stopPolling(); setLifecycle("failed"); const message = pollError instanceof Error ? pollError.message : "Failed to read status"; setError(message); } finally { inFlightRef.current = false; } }; void poll(); pollTimerRef.current = setInterval(() => { void poll(); }, POLL_INTERVAL_MS); }, [ensureAbortController, fetchStatusSnapshot, stopPolling] ); const hasScrolledRef = useRef(false); useEffect(() => { if (lifecycle !== "idle" && !hasScrolledRef.current) { hasScrolledRef.current = true; const heading = document.getElementById("try-it-heading"); if (heading) { const top = heading.getBoundingClientRect().top + window.scrollY; window.scrollTo({ top, behavior: "smooth" }); } } if (lifecycle === "idle") { hasScrolledRef.current = false; } }, [lifecycle]); const handleStart = useCallback(async () => { setError(null); stopPolling(); abortRef.current?.abort(); abortRef.current = null; const controller = ensureAbortController(); const signal = controller.signal; try { const payload = await postJson("/api/mock/start", { contactId: contactId.trim() || DEFAULT_CONTACT_ID, failuresBeforeSuccess: failFirst, }, signal); if (signal.aborted) { return; } setRunId(payload.runId); if (signal.aborted) { return; } setSnapshot(payload.snapshot); if (signal.aborted) { return; } setLifecycle(payload.status === "running" ? "running" : payload.status); if (payload.status === "running") { if (signal.aborted) { return; } beginPolling(payload.runId); } } catch (startError) { if (signal.aborted || (startError instanceof Error && startError.name === "AbortError")) { return; } const message = startError instanceof Error ? startError.message : "Failed to start mock run"; setError(message); setLifecycle("idle"); } }, [beginPolling, contactId, ensureAbortController, failFirst, stopPolling]); const handleReset = useCallback(() => { stopPolling(); abortRef.current?.abort(); abortRef.current = null; setLifecycle("idle"); setRunId(null); setSnapshot(null); setError(null); setTimeout(() => { startButtonRef.current?.focus(); }, 0); }, [stopPolling]); const isRunning = lifecycle === "running"; const phaseExplainer = useMemo(() => { if (!snapshot) { return "Waiting to start a CRM sync."; } if (snapshot.status === "running" && snapshot.currentPhase.phase === "attempt") { return `Attempt ${snapshot.currentPhase.attempt} — fetching from CRM API...`; } if (snapshot.status === "running" && snapshot.currentPhase.phase === "waiting-retry") { return `RetryableError thrown — runtime will retry after ${formatDurationLabel(snapshot.currentPhase.retryAfterMs ?? 0)}`; } if (snapshot.status === "running" && snapshot.currentPhase.phase === "upsert") { return `Contact fetched — running upsertIntoWarehouse() step...`; } if (snapshot.status === "completed") { return `Sync completed on attempt ${snapshot.result?.attempt}. Contact upserted to warehouse.`; } if (snapshot.status === "failed") { return `Sync failed after attempt ${snapshot.result?.attempt}.`; } return "Run is active."; }, [snapshot]); type GutterMarkKind = "success" | "fail"; const codeState = useMemo(() => { const wfMarks: Record = {}; const stepMarks: Record = {}; if (snapshot) { const lastSuccess = [...snapshot.executionLog].reverse().find((e) => e.kind === "success"); const lastRateLimited = [...snapshot.executionLog].reverse().find( (e) => e.kind === "rate-limited" || e.kind === "server-error" ); const lastAttempt = [...snapshot.executionLog].reverse().find((e) => e.kind === "attempt"); // Show fail marks for rate-limited/server-error if (lastRateLimited && lastAttempt && snapshot.executionLog.indexOf(lastRateLimited) > snapshot.executionLog.indexOf(lastAttempt)) { for (const ln of stepLineMap.fetchCall) stepMarks[ln] = "fail"; if (lastRateLimited.kind === "rate-limited") { for (const ln of stepLineMap.retryableErrorThrow) stepMarks[ln] = "fail"; } else { for (const ln of stepLineMap.serverErrorThrow) stepMarks[ln] = "fail"; } } // Show success marks on fetch + return if (lastSuccess) { for (const ln of workflowLineMap.fetchCall) wfMarks[ln] = "success"; for (const ln of stepLineMap.fetchCall) stepMarks[ln] = "success"; for (const ln of stepLineMap.returnJson) stepMarks[ln] = "success"; } // Upsert done const upsertDone = snapshot.executionLog.some((e) => e.kind === "upsert-done"); if (upsertDone) { for (const ln of workflowLineMap.upsertCall) wfMarks[ln] = "success"; } // Final success if (snapshot.status === "completed") { for (const ln of workflowLineMap.successReturn) wfMarks[ln] = "success"; } } if (!snapshot) { return { tone: "amber" as HighlightTone, workflowActiveLines: [] as number[], stepActiveLines: [] as number[], workflowGutterMarks: wfMarks, stepGutterMarks: stepMarks, }; } if (snapshot.status === "running" && snapshot.currentPhase.phase === "attempt") { return { tone: "amber" as HighlightTone, workflowActiveLines: workflowLineMap.fetchCall, stepActiveLines: stepLineMap.fetchCall, workflowGutterMarks: wfMarks, stepGutterMarks: stepMarks, }; } if (snapshot.status === "running" && snapshot.currentPhase.phase === "waiting-retry") { // Find the last error kind to highlight the right throw line const lastError = [...snapshot.executionLog].reverse().find( (e) => e.kind === "rate-limited" || e.kind === "server-error" ); const throwLines = lastError?.kind === "server-error" ? stepLineMap.serverErrorThrow : stepLineMap.retryableErrorThrow; return { tone: "red" as HighlightTone, workflowActiveLines: [] as number[], stepActiveLines: throwLines, workflowGutterMarks: wfMarks, stepGutterMarks: stepMarks, }; } if (snapshot.status === "running" && snapshot.currentPhase.phase === "upsert") { return { tone: "amber" as HighlightTone, workflowActiveLines: workflowLineMap.upsertCall, stepActiveLines: [] as number[], workflowGutterMarks: wfMarks, stepGutterMarks: stepMarks, }; } if (snapshot.status === "completed") { return { tone: "green" as HighlightTone, workflowActiveLines: workflowLineMap.successReturn, stepActiveLines: [] as number[], workflowGutterMarks: wfMarks, stepGutterMarks: stepMarks, }; } return { tone: "red" as HighlightTone, workflowActiveLines: [] as number[], stepActiveLines: [] as number[], workflowGutterMarks: wfMarks, stepGutterMarks: stepMarks, }; }, [snapshot, stepLineMap, workflowLineMap]); return (

{error && (

{error}

)}

{lifecycle !== "idle" && ( )} ID setContactId(e.target.value)} disabled={isRunning} className="h-8 w-24 rounded border border-gray-400 bg-background-100 px-2 text-sm font-mono text-gray-1000 transition-colors focus:border-gray-300 focus:outline-none disabled:cursor-not-allowed disabled:opacity-50" /> 429s first

{phaseExplainer}

{runId && ( run: {runId} )}

RetryableError tells the runtime when to retry — no manual sleep loops needed

); } function AttemptLadder({ attempts, currentPhase, contactId, }: { attempts: AttemptSnapshot[]; currentPhase: MockRateLimitSnapshot["currentPhase"]["phase"] | null; contactId: string; }) { if (attempts.length === 0) { return (

No attempts yet.

); } return (

{attempts.map((attempt) => { const statusTone = attemptTone(attempt.state); const retryLabel = attempt.retryAfterMs > 0 ? `Retry-After: ${formatDurationLabel(attempt.retryAfterMs)}` : ""; const remainingLabel = attempt.state === "waiting-retry" && attempt.remainingRetryMs > 0 ? ` (${formatDurationLabel(attempt.remainingRetryMs)} left)` : ""; return (

#{attempt.attempt}

{attempt.httpStatus} {attempt.idempotencyKey} {retryLabel && (

{retryLabel} {remainingLabel} {attempt.state === "waiting-retry" && currentPhase === "waiting-retry" ? " *" : ""}

)}

); })}

); } function ExecutionLog({ events, elapsedMs, }: { events: RetryLogEvent[]; elapsedMs: number; }) { const scrollRef = useRef(null); useEffect(() => { const el = scrollRef.current; if (el) { el.scrollTop = el.scrollHeight; } }, [events.length]); return (

Execution log

{formatElapsedLabel(elapsedMs)}

{events.length === 0 && (

No events yet.

)} {events.map((event, index) => { const tone = eventTone(event.kind); return (

); })}

); } function attemptTone(state: AttemptSnapshot["state"]): { dotClass: string; badgeClass: string; cardClass: string; } { switch (state) { case "requesting": return { dotClass: "bg-amber-700 animate-pulse", badgeClass: "border-amber-700/40 bg-amber-700/10 text-amber-700", cardClass: "border-amber-700/40 bg-amber-700/10", }; case "waiting-retry": return { dotClass: "bg-cyan-700 animate-pulse", badgeClass: "border-cyan-700/40 bg-cyan-700/10 text-cyan-700", cardClass: "border-cyan-700/40 bg-cyan-700/10", }; case "rate-limited": return { dotClass: "bg-red-700", badgeClass: "border-red-700/40 bg-red-700/10 text-red-700", cardClass: "border-red-700/40 bg-red-700/10", }; case "server-error": return { dotClass: "bg-red-700", badgeClass: "border-red-700/40 bg-red-700/10 text-red-700", cardClass: "border-red-700/40 bg-red-700/10", }; case "succeeded": return { dotClass: "bg-green-700", badgeClass: "border-green-700/40 bg-green-700/10 text-green-700", cardClass: "border-green-700/40 bg-green-700/10", }; case "pending": default: return { dotClass: "bg-gray-500", badgeClass: "border-gray-400/70 bg-background-100 text-gray-900", cardClass: "border-gray-400/40 bg-background-100", }; } } function eventTone(kind: RetryLogEvent["kind"]): { dotClass: string; labelClass: string; } { switch (kind) { case "attempt": return { dotClass: "bg-blue-700", labelClass: "text-blue-700", }; case "rate-limited": return { dotClass: "bg-red-700", labelClass: "text-red-700", }; case "server-error": return { dotClass: "bg-red-700", labelClass: "text-red-700", }; case "retry-scheduled": return { dotClass: "bg-cyan-700", labelClass: "text-cyan-700", }; case "retry-wakeup": return { dotClass: "bg-amber-700", labelClass: "text-amber-700", }; case "success": return { dotClass: "bg-green-700", labelClass: "text-green-700", }; case "upsert": return { dotClass: "bg-violet-700", labelClass: "text-violet-700", }; case "upsert-done": return { dotClass: "bg-green-700", labelClass: "text-green-700", }; default: return { dotClass: "bg-gray-500", labelClass: "text-gray-900", }; } } [V0_FILE]typescript:file="app/components/code-highlight-server.ts" import { highlight } from "sugar-high"; export function highlightCodeToHtmlLines(code: string): string[] { return highlight(code).split("\n"); } [V0_FILE]typescriptreact:file="app/layout.tsx" import type { Metadata } from "next"; import { Geist, Geist_Mono } from "next/font/google"; import "./globals.css"; const geistSans = Geist({ variable: "--font-geist-sans", subsets: ["latin"], }); const geistMono = Geist_Mono({ variable: "--font-geist-mono", subsets: ["latin"], }); export const metadata: Metadata = { title: "Rate Limit Retry - Workflow DevKit Example", description: "Demonstrates RetryableError with retryAfter and getStepMetadata() for handling 429 rate limits in Workflow DevKit", }; export default function RootLayout({ children, }: Readonly<{ children: React.ReactNode; }>) { return ( Skip to main content {children} ); } [V0_FILE]typescript:file="app/api/mock/start/route.ts" import { createApiErrorResponse, createApiSuccessResponse } from "../api"; import { buildMockRateLimitSnapshot, createMockRateLimitRun, } from "../store"; type StartRequestBody = { contactId?: unknown; failuresBeforeSuccess?: unknown; }; const DEFAULT_CONTACT_ID = "contact-42"; const DEFAULT_FAILURES_BEFORE_SUCCESS = 2; function generateRunId(): string { return `rl_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`; } function parseContactId(value: unknown): { value: string } | { error: string } { if (value === undefined) { return { value: DEFAULT_CONTACT_ID }; } if (typeof value !== "string") { return { error: "contactId must be a string" }; } const normalized = value.trim(); if (!normalized) { return { error: "contactId cannot be empty" }; } return { value: normalized }; } function parseFailuresBeforeSuccess( value: unknown ): { value: number } | { error: string } { if (value === undefined) { return { value: DEFAULT_FAILURES_BEFORE_SUCCESS }; } if ( typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) ) { return { error: "failuresBeforeSuccess must be an integer between 0 and 6", }; } if (value < 0 || value > 6) { return { error: "failuresBeforeSuccess must be between 0 and 6", }; } return { value }; } export async function POST(request: Request): Promise { let body: StartRequestBody; try { body = (await request.json()) as StartRequestBody; } catch { return createApiErrorResponse( { code: "INVALID_REQUEST", message: "Invalid JSON body", }, { status: 400 } ); } const contactIdResult = parseContactId(body.contactId); if ("error" in contactIdResult) { return createApiErrorResponse( { code: "INVALID_REQUEST", message: contactIdResult.error, }, { status: 400 } ); } const failuresResult = parseFailuresBeforeSuccess(body.failuresBeforeSuccess); if ("error" in failuresResult) { return createApiErrorResponse( { code: "INVALID_REQUEST", message: failuresResult.error, }, { status: 400 } ); } const run = createMockRateLimitRun({ runId: generateRunId(), contactId: contactIdResult.value, failuresBeforeSuccess: failuresResult.value, }); const snapshot = buildMockRateLimitSnapshot(run, run.startedAtMs); return createApiSuccessResponse({ runId: run.id, contactId: run.contactId, status: snapshot.status, failuresBeforeSuccess: run.failuresBeforeSuccess, snapshot, }); } [V0_FILE]typescript:file="app/api/mock/api.ts" import { NextResponse } from "next/server"; type ApiError = { code: string; message: string; }; export function createApiSuccessResponse>( fields: T, init?: ResponseInit ) { return NextResponse.json( { ok: true, ...fields, }, init ); } export function createApiErrorResponse(error: ApiError, init?: ResponseInit) { return NextResponse.json( { ok: false, error, }, init ); } [V0_FILE]typescript:file="app/api/mock/status/route.ts" import { createApiErrorResponse, createApiSuccessResponse } from "../api"; import { buildMockRateLimitSnapshot, getMockRateLimitRun } from "../store"; export async function GET(request: Request): Promise { const searchParams = new URL(request.url).searchParams; const runId = searchParams.get("runId"); if (!runId) { return createApiErrorResponse( { code: "INVALID_REQUEST", message: "runId is required", }, { status: 400 } ); } const run = getMockRateLimitRun(runId); if (!run) { console.warn("[mock-retryable-rate-limit] status_lookup_failed", { attempted: "mock_rate_limit_status_lookup", reason: "run_not_found", runId, }); return createApiErrorResponse( { code: "NOT_FOUND", message: "Run not found", }, { status: 404 } ); } return createApiSuccessResponse({ ...buildMockRateLimitSnapshot(run) }); } [V0_FILE]typescript:file="app/api/mock/store.ts" export const ATTEMPT_WORK_MS = 600; export type MockRunStatus = "running" | "completed" | "failed"; export type AttemptOutcome = "rate-limited" | "server-error" | "success"; export type AttemptRuntimeState = | "pending" | "requesting" | "rate-limited" | "server-error" | "waiting-retry" | "succeeded"; export type RetryPhaseKind = "attempt" | "waiting-retry" | "upsert" | "done"; export interface AttemptPlan { attempt: number; startMs: number; endMs: number; retryAfterMs: number; outcome: AttemptOutcome; httpStatus: number; idempotencyKey: string; } export interface MockRateLimitRun { id: string; contactId: string; failuresBeforeSuccess: number; startedAt: string; startedAtMs: number; status: MockRunStatus; plan: AttemptPlan[]; upsertStartMs: number; upsertEndMs: number; } export interface AttemptSnapshot extends AttemptPlan { state: AttemptRuntimeState; remainingRetryMs: number; } export interface RetryPhase { phase: RetryPhaseKind; attempt: number | null; retryAfterMs: number | null; } export type RetryLogEventKind = | "attempt" | "rate-limited" | "server-error" | "retry-scheduled" | "retry-wakeup" | "success" | "upsert" | "upsert-done"; export interface RetryLogEvent { atMs: number; attempt: number; kind: RetryLogEventKind; message: string; } export interface MockRateLimitSnapshot { runId: string; contactId: string; status: MockRunStatus; failuresBeforeSuccess: number; attemptWorkMs: number; startedAt: string; startedAtMs: number; elapsedMs: number; totalDurationMs: number; attempts: AttemptSnapshot[]; currentPhase: RetryPhase; executionLog: RetryLogEvent[]; result: | { attempt: number; outcome: "success" | "failed"; } | null; } declare global { // eslint-disable-next-line no-var var __mockRateLimitRuns: Map | undefined; } function toIso(timestampMs: number): string { return new Date(timestampMs).toISOString(); } export function getRunStore(): Map { return ( globalThis.__mockRateLimitRuns ?? (globalThis.__mockRateLimitRuns = new Map()) ); } function runStatusTransition( run: MockRateLimitRun, nextStatus: MockRunStatus, reason: string, context: Record ): void { if (run.status === nextStatus) { return; } console.info("[mock-retryable-rate-limit] run_status_transition", { runId: run.id, from: run.status, to: nextStatus, reason, ...context, }); run.status = nextStatus; } /** * Retry-After values the "server" returns per attempt. * Attempt 1 → 3s, Attempt 2 → 2s, Attempt 3+ → 1s */ function retryAfterForAttempt(attempt: number): number { if (attempt === 1) return 3000; if (attempt === 2) return 2000; return 1000; } /** * Determine the HTTP status for a given attempt. * Most failures are 429 (rate limit), but we alternate with 503 for variety. */ function httpStatusForFailure(attempt: number): number { return attempt % 3 === 0 ? 503 : 429; } export function buildAttemptPlan(input: { contactId: string; failuresBeforeSuccess: number; }): AttemptPlan[] { const { contactId, failuresBeforeSuccess } = input; const plan: AttemptPlan[] = []; const totalAttempts = failuresBeforeSuccess + 1; let cursorMs = 0; for (let attempt = 1; attempt <= totalAttempts; attempt += 1) { const startMs = cursorMs; const endMs = startMs + ATTEMPT_WORK_MS; const isLast = attempt === totalAttempts; const outcome: AttemptOutcome = isLast ? "success" : httpStatusForFailure(attempt) === 503 ? "server-error" : "rate-limited"; const httpStatus = isLast ? 200 : httpStatusForFailure(attempt); const retryAfterMs = isLast ? 0 : retryAfterForAttempt(attempt); const idempotencyKey = `crm-sync:${contactId}:fetchContactFromCrm`; plan.push({ attempt, startMs, endMs, retryAfterMs, outcome, httpStatus, idempotencyKey, }); cursorMs = endMs + retryAfterMs; } return plan; } export function createMockRateLimitRun(input: { runId: string; contactId: string; failuresBeforeSuccess: number; nowMs?: number; }): MockRateLimitRun { const nowMs = input.nowMs ?? Date.now(); const plan = buildAttemptPlan({ contactId: input.contactId, failuresBeforeSuccess: input.failuresBeforeSuccess, }); const lastAttempt = plan[plan.length - 1]; const upsertStartMs = lastAttempt.endMs; const upsertEndMs = upsertStartMs + ATTEMPT_WORK_MS; const run: MockRateLimitRun = { id: input.runId, contactId: input.contactId, failuresBeforeSuccess: input.failuresBeforeSuccess, startedAt: toIso(nowMs), startedAtMs: nowMs, status: "running", plan, upsertStartMs, upsertEndMs, }; console.info("[mock-retryable-rate-limit] run_created", { runId: run.id, contactId: run.contactId, failuresBeforeSuccess: run.failuresBeforeSuccess, planLength: run.plan.length, totalDurationMs: run.upsertEndMs, }); getRunStore().set(run.id, run); return run; } export function getMockRateLimitRun(runId: string): MockRateLimitRun | undefined { return getRunStore().get(runId); } function buildExecutionTimeline(plan: AttemptPlan[], upsertStartMs: number, upsertEndMs: number): RetryLogEvent[] { const events: RetryLogEvent[] = []; for (const attempt of plan) { events.push({ atMs: attempt.startMs, attempt: attempt.attempt, kind: "attempt", message: `Attempt ${attempt.attempt} — fetch(crm.example.com) [key: ${attempt.idempotencyKey}]`, }); if (attempt.outcome === "success") { events.push({ atMs: attempt.endMs, attempt: attempt.attempt, kind: "success", message: `HTTP 200 OK — contact data returned`, }); continue; } const errorKind: RetryLogEventKind = attempt.outcome === "rate-limited" ? "rate-limited" : "server-error"; const errorLabel = attempt.outcome === "rate-limited" ? `HTTP 429 — RetryableError { retryAfter: ${attempt.retryAfterMs} }` : `HTTP 503 — RetryableError { retryAfter: ${attempt.retryAfterMs} }`; events.push({ atMs: attempt.endMs, attempt: attempt.attempt, kind: errorKind, message: errorLabel, }); if (attempt.retryAfterMs > 0) { events.push({ atMs: attempt.endMs, attempt: attempt.attempt, kind: "retry-scheduled", message: `Runtime scheduling retry after ${attempt.retryAfterMs}ms`, }); events.push({ atMs: attempt.endMs + attempt.retryAfterMs, attempt: attempt.attempt, kind: "retry-wakeup", message: `Woke up after ${attempt.retryAfterMs}ms`, }); } } // Upsert step events.push({ atMs: upsertStartMs, attempt: plan[plan.length - 1].attempt, kind: "upsert", message: `upsertIntoWarehouse() started`, }); events.push({ atMs: upsertEndMs, attempt: plan[plan.length - 1].attempt, kind: "upsert-done", message: `upsertIntoWarehouse() completed`, }); return events.sort((left, right) => left.atMs - right.atMs); } export function buildMockRateLimitSnapshot( run: MockRateLimitRun, nowMs: number = Date.now() ): MockRateLimitSnapshot { const elapsedMs = Math.max(0, nowMs - run.startedAtMs); const attempts: AttemptSnapshot[] = run.plan.map((attempt) => ({ ...attempt, state: "pending" as AttemptRuntimeState, remainingRetryMs: 0, })); let status: MockRunStatus = "running"; let currentPhase: RetryPhase = { phase: "done", attempt: null, retryAfterMs: null, }; let result: MockRateLimitSnapshot["result"] = null; for (let index = 0; index < attempts.length; index += 1) { const attempt = attempts[index]; const retryEndMs = attempt.endMs + attempt.retryAfterMs; // Still in the request phase if (elapsedMs < attempt.endMs) { attempt.state = "requesting"; currentPhase = { phase: "attempt", attempt: attempt.attempt, retryAfterMs: attempt.retryAfterMs > 0 ? attempt.retryAfterMs : null, }; break; } // Request finished — determine outcome if (attempt.outcome === "success") { attempt.state = "succeeded"; // Check if we're in upsert phase if (elapsedMs < run.upsertEndMs) { currentPhase = { phase: "upsert", attempt: attempt.attempt, retryAfterMs: null, }; break; } // Upsert complete status = "completed"; currentPhase = { phase: "done", attempt: attempt.attempt, retryAfterMs: null, }; result = { attempt: attempt.attempt, outcome: "success" }; break; } // Failed — check if we're in the retry-after wait period if (attempt.retryAfterMs > 0 && elapsedMs < retryEndMs) { attempt.state = "waiting-retry"; attempt.remainingRetryMs = Math.max(0, retryEndMs - elapsedMs); currentPhase = { phase: "waiting-retry", attempt: attempt.attempt, retryAfterMs: attempt.retryAfterMs, }; break; } // Failed and retry wait expired attempt.state = attempt.outcome === "rate-limited" ? "rate-limited" : "server-error"; } runStatusTransition(run, status, "snapshot_recomputed", { elapsedMs, currentPhase, }); return { runId: run.id, contactId: run.contactId, status, failuresBeforeSuccess: run.failuresBeforeSuccess, attemptWorkMs: ATTEMPT_WORK_MS, startedAt: run.startedAt, startedAtMs: run.startedAtMs, elapsedMs, totalDurationMs: run.upsertEndMs, attempts, currentPhase, executionLog: buildExecutionTimeline(run.plan, run.upsertStartMs, run.upsertEndMs).filter( (event) => event.atMs <= elapsedMs ), result, }; } [V0_FILE]typescript:file="app/api/start/route.ts" import { NextResponse } from "next/server"; import { start } from "workflow/api"; import { syncCrmContact } from "@/workflows/retryable-rate-limit"; export async function POST(request: Request) { const { contactId } = await request.json(); if (!contactId || typeof contactId !== "string") { return NextResponse.json({ error: "contactId required" }, { status: 400 }); } const run = await start(syncCrmContact, [contactId]); return NextResponse.json({ runId: run.runId }); } [V0_FILE]typescriptreact:file="app/page.tsx" import { highlightCodeToHtmlLines } from "./components/code-highlight-server"; import { RateLimitDemo } from "./components/demo"; const directiveUseWorkflow = `"use ${"workflow"}"`; const directiveUseStep = `"use ${"step"}"`; const workflowCode = `import { RetryableError, getStepMetadata, fetch } from "workflow"; export async function syncCrmContact(contactId: string) { ${directiveUseWorkflow}; const contact = await fetchContactFromCrm(contactId); await upsertIntoWarehouse(contactId, contact); return { contactId, status: "synced" }; }`; const stepCode = `async function fetchContactFromCrm(contactId: string) { ${directiveUseStep}; const { stepId, attempt } = getStepMetadata(); const res = await fetch(\`https://crm.example.com/api/contacts/\${contactId}\`, { headers: { "Idempotency-Key": \`crm-sync:\${contactId}:\${stepId}\`, "X-Attempt": String(attempt), }, }); if (res.status === 429) { const retryAfterSec = Number(res.headers.get("Retry-After") || "3"); throw new RetryableError("CRM rate-limited", { retryAfter: retryAfterSec * 1000, }); } if (res.status >= 500) { throw new RetryableError("CRM temporarily unavailable", { retryAfter: 2000, }); } if (!res.ok) { throw new Error(\`CRM request failed: \${res.status}\`); } return res.json(); }`; function buildWorkflowLineMap(code: string) { const lines = code.split("\n"); const fetchCall = lines .map((line, index) => line.includes("await fetchContactFromCrm(") ? index + 1 : null ) .filter((line): line is number => line !== null); const upsertCall = lines .map((line, index) => line.includes("await upsertIntoWarehouse(") ? index + 1 : null ) .filter((line): line is number => line !== null); const successReturn = lines .map((line, index) => line.includes('status: "synced"') ? index + 1 : null ) .filter((line): line is number => line !== null); return { fetchCall, upsertCall, successReturn, }; } function buildStepLineMap(code: string) { const lines = code.split("\n"); const fetchCall = lines .map((line, index) => line.includes("const res = await fetch(") ? index + 1 : null ) .filter((line): line is number => line !== null); const retryableErrorThrow = lines .map((line, index) => line.includes('throw new RetryableError("CRM rate-limited"') ? index + 1 : null ) .filter((line): line is number => line !== null); const serverErrorThrow = lines .map((line, index) => line.includes('throw new RetryableError("CRM temporarily unavailable"') ? index + 1 : null ) .filter((line): line is number => line !== null); const returnJson = lines .map((line, index) => line.includes("return res.json()") ? index + 1 : null ) .filter((line): line is number => line !== null); return { fetchCall, retryableErrorThrow, serverErrorThrow, returnJson }; } const workflowHtmlLines = highlightCodeToHtmlLines(workflowCode); const stepHtmlLines = highlightCodeToHtmlLines(stepCode); const workflowLineMap = buildWorkflowLineMap(workflowCode); const stepLineMap = buildStepLineMap(stepCode); export default function Home() { return (

Workflow DevKit Example

Rate Limit Retry

CRM APIs return{" "} 429 Too Many Requests{" "} with a{" "} Retry-After{" "} header. Instead of building a retry queue, a database table, and a cron sweeper, throw a{" "} RetryableError{" "} and let the runtime handle scheduling. Use{" "} getStepMetadata(){" "} for idempotency keys and attempt tracking.

Try It

Why Not Just Build a Retry Queue?

Traditional

You need a delayed-job queue, a database retry table tracking attempt counts and next-retry timestamps, and a{" "} cron sweeper that periodically polls the table to re-enqueue jobs. Parsing{" "} Retry-After{" "} headers means custom scheduling logic scattered across three services.

RetryableError

Throw{" "} new RetryableError("msg", {"{"} retryAfter: ms {"}"}){" "} and the runtime schedules the retry for you. No queue, no database, no cron.{" "} getStepMetadata(){" "} gives you a stable stepId{" "} for idempotency keys and the current{" "} attempt{" "} number for observability.

The step function reads the{" "} Retry-After{" "} header and passes it straight to{" "} RetryableError. The runtime does the rest.

); } [V0_FILE]css:file="app/globals.css" @import "tailwindcss"; @theme { --color-background-100: #0a0a0a; --color-background-200: #171717; --color-gray-100: #1a1a1a; --color-gray-200: #1f1f1f; --color-gray-300: #292929; --color-gray-400: #737373; --color-gray-500: #525252; --color-gray-600: #404040; --color-gray-700: #262626; --color-gray-800: #171717; --color-gray-900: #a1a1a1; --color-gray-1000: #ededed; --color-blue-700: #0070F3; --color-red-700: #E5484D; --color-amber-700: #FFB224; --color-green-700: #46A758; --color-violet-700: #8B5CF6; --color-cyan-700: #06B6D4; --font-sans: var(--font-geist-sans); --font-mono: var(--font-geist-mono); } body { background: #0a0a0a; color: #ededed; font-family: var(--font-sans), -apple-system, BlinkMacSystemFont, sans-serif; } /* sugar-high syntax tokens */ :root, .dark { --sh-class: #52a8ff; --sh-identifier: #ededed; --sh-sign: #a1a1a1; --sh-property: #ff6166; --sh-entity: #62c073; --sh-jsxliterals: #ededed; --sh-string: #62c073; --sh-keyword: #f75f8f; --sh-comment: #a1a1a1; } /* Prism token colors - Geist dark-mode palette */ .token.keyword, .token.keyword.control-flow { color: #f75f8f; } .token.plain, .token.parameter, .token.punctuation, .token.plain-text, .token.property-access, .token.operator, .token.tag.punctuation { color: #ededed; } .token.function, .token.function.maybe-class-name { color: #bf7af0; } .token.tag { color: #62c073; } .token.literal-property.property { color: #ff6166; } .token.string, .token.boolean { color: #62c073; } .token.comment { color: #a1a1a1; } .token.class-name { color: #52a8ff; } .token.number { color: #62c073; } .token.attr-name { color: #ff6166; } .token.attr-value { color: #62c073; } .token.builtin { color: #52a8ff; } .token.template-string { color: #62c073; } .token.interpolation { color: #ededed; } [V0_FILE]javascript:file="postcss.config.mjs" export default { plugins: { "@tailwindcss/postcss": {}, }, }; [V0_FILE]typescript:file="workflows/retryable-rate-limit.ts" import { RetryableError, getStepMetadata, fetch } from "workflow"; export type SyncResult = { contactId: string; status: "synced" | "failed"; attempts?: number; }; export async function syncCrmContact(contactId: string): Promise { "use workflow"; const contact = await fetchContactFromCrm(contactId); await upsertIntoWarehouse(contactId, contact); return { contactId, status: "synced" }; } async function fetchContactFromCrm(contactId: string) { "use step"; const { stepId, attempt } = getStepMetadata(); const res = await fetch(`https://crm.example.com/api/contacts/${contactId}`, { headers: { "Idempotency-Key": `crm-sync:${contactId}:${stepId}`, "X-Attempt": String(attempt), }, }); if (res.status === 429) { const retryAfterSec = Number(res.headers.get("Retry-After") || "3"); throw new RetryableError("CRM rate-limited", { retryAfter: retryAfterSec * 1000, }); } if (res.status >= 500) { throw new RetryableError("CRM temporarily unavailable", { retryAfter: 2000, }); } if (!res.ok) { throw new Error(`CRM request failed: ${res.status}`); } return res.json(); } async function upsertIntoWarehouse(contactId: string, contact: unknown) { "use step"; const { stepId } = getStepMetadata(); console.info("[retryable-rate-limit] upsert", { contactId, stepId, contact }); } [V0_FILE]json:file="package.json" { "name": "retryable-rate-limit", "version": "0.1.0", "private": true, "scripts": { "dev": "next dev", "build": "next build", "start": "next start", "lint": "next lint" }, "dependencies": { "next": "16.0.10", "react": "19.2.3", "react-dom": "19.2.3", "sugar-high": "^0.9.5", "workflow": "4.1.0-beta.53" }, "devDependencies": { "@tailwindcss/postcss": "^4", "@types/node": "^20", "@types/react": "^19", "@types/react-dom": "^19", "tailwindcss": "^4", "typescript": "^5" } } [V0_FILE]json:file="tsconfig.json" { "compilerOptions": { "target": "ES2017", "lib": ["dom", "dom.iterable", "esnext"], "allowJs": true, "skipLibCheck": true, "strict": true, "noEmit": true, "esModuleInterop": true, "module": "esnext", "moduleResolution": "bundler", "resolveJsonModule": true, "isolatedModules": true, "jsx": "react-jsx", "incremental": true, "plugins": [ { "name": "next" }, { "name": "workflow" } ], "paths": { "@/*": ["./*"] } }, "include": [ "next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts", ".next/dev/types/**/*.ts", "**/*.mts" ], "exclude": ["node_modules"] } [V0_FILE]typescript:file="next.config.ts" import { withWorkflow } from "workflow/next"; import type { NextConfig } from "next"; const nextConfig: NextConfig = {}; export default withWorkflow(nextConfig);