withRetry helper for durable operations

[ParidelPooya]

[Feedback wanted] New withRetry helper for retrying callbacks, invokes, and other durable operations

We are exploring a new SDK helper called withRetry and would love your feedback before we lock the API. Draft PR is here: https://github.com/aws/aws-durable-execution-sdk-js/pull/new/feat/sdk-retry-operation

The problem

context.step() already has a great retryStrategy option — you get exponential backoff, jitter, error-type filtering, and per-attempt decisions for free via createRetryStrategy. But that only works for step.

For other durable operations (waitForCallback, invoke, waitForCondition, etc.) there's no equivalent — and they can't be nested inside a step, so you end up hand-rolling something like:

let attempt = 0;
while (attempt < 3) {
  attempt++;
  try {
    return await context.waitForCallback(`approval-${attempt}`, submitter, {
      timeout: { hours: 24 },
    });
  } catch (err) {
    if (attempt >= 3) throw err;
    await context.wait(`backoff-${attempt}`, { seconds: 2 ** attempt });
  }
}

Every team I've talked to has written some variant of this. The pattern isn't hard, but it's easy to get subtly wrong (forgetting context.wait for backoff, using setTimeout, accidentally nesting durable ops inside a step, etc.).

The proposal

A single helper that uses the same retryStrategy shape you already know from StepConfig:

import {
  retryOperation,
  createRetryStrategy,
} from "@aws/durable-execution-sdk-js";

const decision = await withRetry(
  context,
  "approval",
  (ctx, attempt) =>
    ctx.waitForCallback<"APPROVED" | "REJECTED">(
      `approval-${attempt}`,
      (callbackId) => sendApprovalEmail(event.email, callbackId),
      { timeout: { hours: 24 } },
    ),
  {
    retryStrategy: createRetryStrategy({
      maxAttempts: 3,
      initialDelay: { seconds: 2 },
      backoffRate: 2,
    }),
  },
);

Works with any durable primitive — here it is retrying an invoke:

const result = await withRetry(
  context,
  "charge",
  (ctx, attempt) => ctx.invoke(`charge-${attempt}`, paymentFnArn, { orderId }),
  {
    retryStrategy: (err, attempt) => ({
      shouldRetry: attempt < 3 && !err.message.includes("CARD_DECLINED"),
      delay: { seconds: 2 ** attempt },
    }),
  },
);

Links

• Draft PR: https://github.com/aws/aws-durable-execution-sdk-js/pull/new/feat/sdk-retry-operation

Appreciate any and all feedback.

[embano1]

NICE! Question, the type definition is incompatible with the existing retries we have on steps, right? I was thinking if this would be an opportunity to also discuss "global" retry strategies which will be used as default for all operations, unless overwritten? Perhaps too much to cramp into one PR, but worth keeping in mind as we discuss this feature here.

[ParidelPooya]

The signature of retryStrategy is deliberately identical to StepConfig.retryStrategy, so createRetryStrategy and retryPresets work with both — that's the reuse I care about. I
made the field required (vs. optional on StepConfig) because a retryOperation without a retry policy is just runInChildContext with extra steps — there's no useful fallback behavior.

[embano1]

I made the field required

Just to check: which field? Is this a breaking change?

[SilanHe]

I think ParidelPooya is referring to the retryStrategy field on the withRetry helper's withRetryConfig parameter. This is not a breaking change since we aren't changing any existing operations, only composing existing operations together under the withRetry helper.

[embano1]

Ah, yeah of course that makes sense.

[ParidelPooya]

2026-04-23 Update:Based on some internal feedback we changed the name to withRetry

[jasonm4130]

+1 on the motivation, we hit this daily.

We use durable functions to orchestrate AI pipelines that route between real-time inference and batch based on priority/volume. The 3,000 op limit forces us to coarsen pretty aggressively — we wrap ~100 ops worth of ML compute into single invokes via orchestration lambdas. We've hand-rolled retry around those invokes already so withRetry would clean things up a lot.

Two things I'd push on:

Partial failure. Our main failure mode is k-of-N — a batch invoke processes 100 items and 2 fail. withRetry at the invoke boundary retries all 100 at full inference cost. Is there a planned story for retrying with memoised per-item success, where the callback gets prior attempt results and can branch to only reprocess failures? Or is that the caller's job via return-value threading?

Attempt identity. The examples thread attempt into ids manually (approval-${attempt} etc). This extends beyond op names — any side-effecting keyspace (S3 claim-check keys, external idempotency tokens) needs the same treatment. Since withRetry owns the attempt counter, could the SDK auto-suffix durable op names and expose attempt as a first-class context property rather than a callback arg callers have to remember to plumb everywhere?

[ParidelPooya]

Partial failure.

I think the clean answer is composition — withRetry inside context.map per item, not around the batch:

    context.map(items, (ctx, item, index) =>
      withRetry(ctx, `classify-${index}`, (retryCtx, attempt) =>
        retryCtx.invoke(`classify-${index}-${attempt}`, classifierFn, { item }),
        { retryStrategy: ... },
      ),
      { maxConcurrency: 10 },
    );
   

This gives you exactly the behavior you want for k-of-N:

• Each item has its own retry policy.
• Already-successful items are checkpointed and not re-run (no duplicate inference cost).
• context.map's CompletionConfig (minSuccessful, toleratedFailureCount) still governs when to fail the batch.
• Concurrency is respected across all in-flight retries.

This is also a nice validation of keeping withRetry small and composable — it slots into map/parallel without any additional SDK machinery.

[ParidelPooya]

Attempt identity

The auto-suffix piece we can probably drop — the SDK identifies ops by call-site position, not name, so attempt suffixes are actually just for readability today.
The ambient-attempt question is more interesting. I'm nervous about putting currentAttempt on the context because it raises hard questions once you nest things:

• What's ctx.currentAttempt inside withRetry(withRetry(...))?
• Or inside a context.step (which has its own retry counter) inside a withRetry?

If we later find that several real workloads want ambient attempt and we can nail down nesting semantics, we can add it non-breakingly.

[jasonm4130]

On context.map composition: on re-read I'd missed that withRetry nests cleanly inside it. Each item gets its own retry policy, successful items checkpoint, batch completion governed by MapConfig. Thank you!

On attempt identity: we use an external claim-check pattern for context size limits (large results land in S3, key threaded through). ctx.step('gen-key', () => uuid()) inside the withRetry callback gives a fresh key per attempt, checkpointed for that attempt's replays. Covers it. No ambient attempt needed.