Step¶

import { DurableContext, StepConfig, StepFunc } from "@aws/durable-execution-sdk-js";

// Sync signature (unnamed)
context.step(fn: StepFunc<T>, config?: StepConfig<T>): DurablePromise<T>

// Named signature
context.step(name: string | undefined, fn: StepFunc<T>, config?: StepConfig<T>): DurablePromise<T>

Parameters:

• name (optional) A name for the step. Pass undefined to omit.
• fn A function that receives a StepContext and returns a Promise<T>.
• config (optional) A StepConfig<T> object.

Returns: DurablePromise<T>. Use await to get the result.

Throws: StepError (a DurableOperationError subclass) wrapping the original error after retries are exhausted. For an at-most-once step that Lambda interrupted before the SDK checkpointed the result, the SDK throws a StepError whose cause.name equals "StepInterruptedError".

from aws_durable_execution_sdk_python import StepContext
from aws_durable_execution_sdk_python.config import StepConfig


def step(
    func: Callable[[StepContext], T],
    name: str | None = None,
    config: StepConfig | None = None,
) -> T: ...

Parameters:

• func A callable that receives a StepContext and returns T.
• name (optional) A name for the step. Defaults to the function's name when using @durable_step.
• config (optional) A StepConfig object.

Returns: T, the return value of func.

Raises: StepError (a DurableOperationError subclass) wrapping the original exception after retries are exhausted. An at-most-once step interrupted before it checkpointed also surfaces as StepError, with error_type recording StepInterruptedError. A permanent serializer failure raises SerDesError.

// Sync (blocks until complete)
<T> T step(String name, Class<T> resultType, Function<StepContext, T> func)
<T> T step(String name, Class<T> resultType, Function<StepContext, T> func, StepConfig config)

// Async (returns a DurableFuture)
<T> DurableFuture<T> stepAsync(String name, Class<T> resultType, Function<StepContext, T> func)
<T> DurableFuture<T> stepAsync(String name, Class<T> resultType, Function<StepContext, T> func, StepConfig config)

Parameters:

• name (required) A name for the step.
• resultType The Class<T> or TypeToken<T> for deserialization.
• func A Function<StepContext, T> to execute.
• config (optional) A StepConfig object.

Returns: T (sync) or DurableFuture<T> (async via stepAsync()).

Throws: The original exception re-thrown after deserialization if possible, otherwise StepFailedException. StepInterruptedException if an at-most-once step was interrupted.

// Sync
func Step[O any](ctx Context, name string, fn func(StepContext) (O, error), opts ...StepOption) (O, error)

// Async
func StepAsync[O any](ctx Context, name string, fn func(StepContext) (O, error), opts ...StepOption) *Future[O]

Parameters:

• ctx (required) The durable Context, always the first argument.
• name (required) A name for the step. Pass "" to omit it.
• fn A func(durable.StepContext) (O, error) to execute. The result type O is inferred from its return value.
• opts (optional) Zero or more StepOption values.

Returns: (O, error) from Step, or *durable.Future[O] from StepAsync. Read the async result with fut.Result(ctx).

Errors: *durable.StepError when the step body fails and the retry strategy stops. Its Err field is a stand-in rebuilt from ErrorType and Message, the same on the first run and on replay. So match on ErrorType, not with errors.As against the body's own error type. An interrupted AtMostOncePerRetry step that the retry strategy stops returns a *durable.StepError whose ErrorType is "StepInterruptedError". errors.As reaches a *durable.StepInterruptedError through it. A result the serializer cannot convert fails the step at once, without a retry. The *durable.StepError then has ErrorType "SerdesError". An invalid WithStepSubType value returns a plain error before the step runs.

// Returns a value
Task<T> StepAsync<T>(
    Func<IStepContext, CancellationToken, Task<T>> func,
    string? name = null,
    StepConfig? config = null,
    CancellationToken cancellationToken = default);

// Returns no value
Task StepAsync(
    Func<IStepContext, CancellationToken, Task> func,
    string? name = null,
    StepConfig? config = null,
    CancellationToken cancellationToken = default);

Parameters:

• func A function that receives an IStepContext and a CancellationToken and returns a Task<T> (or Task for the no-value overload).
• name (optional) A name for the step. Omit it to infer one from the call site.
• config (optional) A StepConfig object.
• cancellationToken (optional) A token linked with the SDK's workflow-shutdown signal, forwarded to func.

Returns: Task<T>, or Task for the no-value overload. Use await to get the result.

Throws: The exception thrown by the step body after retries are exhausted. An OperationCanceledException that propagates via the linked token is treated as cancellation, not a step failure. See Cancellation.

interface StepConfig<T> {
  retryStrategy?: (error: Error, attemptCount: number) => RetryDecision;
  semantics?: StepSemantics;
  serdes?: Serdes<T>;
}

Parameters:

• retryStrategy (optional) A function returning a RetryDecision. Use createRetryStrategy() to build one. See Retry strategies.
• semantics (optional) StepSemantics.AtLeastOncePerRetry (default) or StepSemantics.AtMostOncePerRetry.
• serdes (optional) Custom Serdes<T> for the step result. See Serialization.

@dataclass(frozen=True)
class StepConfig:
    retry_strategy: Callable[[Exception, int], RetryDecision] | None = None
    step_semantics: StepSemantics = StepSemantics.AT_LEAST_ONCE_PER_RETRY
    serdes: SerDes | None = None

Parameters:

• retry_strategy (optional) A callable returning a RetryDecision. Use create_retry_strategy() to build one. See Retry strategies.
• step_semantics (optional) StepSemantics.AT_LEAST_ONCE_PER_RETRY (default) or StepSemantics.AT_MOST_ONCE_PER_RETRY.
• serdes (optional) Custom SerDes for the step result. See Serialization.

StepConfig.builder()
    .retryStrategy(RetryStrategy)          // optional
    .semanticsPerRetry(StepSemantics)      // optional
    .serDes(SerDes)                        // optional
    .build()

Parameters:

• retryStrategy (optional) A RetryStrategy instance. Use RetryStrategies.exponentialBackoff() to build one. See Retry strategies.
• semanticsPerRetry (optional) StepSemantics.AT_LEAST_ONCE_PER_RETRY (default) or StepSemantics.AT_MOST_ONCE_PER_RETRY.
• serDes (optional) Custom SerDes for the step result. See Serialization.

Pass options to Step.

func WithRetry(s RetryStrategy) StepOption
func WithSemantics(s StepSemantics) StepOption
func WithStepSerdes(s Serdes) StepOption
func WithStepSubType(subType string) StepOption

Parameters:

• WithRetry (optional) A RetryStrategy. Build one with durable.NewRetryStrategy, durable.ExponentialBackoff, or durable.LinearBackoff. The default is durable.ExponentialBackoff(). It makes 6 attempts in total, with a 5-second first delay that doubles on each retry up to 60 seconds, and full jitter. So a step retries unless you pass durable.NoRetry(). See Retry strategies.
• WithSemantics (optional) durable.AtLeastOncePerRetry (default) or durable.AtMostOncePerRetry.
• WithStepSerdes (optional) A custom Serdes for the step result. The default is the handler-level serializer, which is JSON unless you set durable.WithSerdes or call durable.ConfigureSerdes. See Serialization.
• WithStepSubType (optional) The operation subtype the step records in the checkpoint. The default is "Step", and an empty string selects it. A subtype has 1 to 32 characters from A-Z, a-z, 0-9, hyphen, and underscore. The subtypes the SDK records for its own operations are reserved. An invalid value makes Step return an error. The subtype is part of the step's replay identity, so a different subtype on replay returns a *durable.NonDeterministicExecutionError.

public sealed class StepConfig
{
    public IRetryStrategy? RetryStrategy { get; set; }  // null = no retry
    public StepSemantics Semantics { get; set; }        // default AtLeastOncePerRetry
}

Parameters:

• RetryStrategy (optional) An IRetryStrategy. When null (default), failures are not retried. Use the RetryStrategy factory (for example RetryStrategy.Exponential(...)) to build one. See Retry strategies.
• Semantics (optional) StepSemantics.AtLeastOncePerRetry (default) or StepSemantics.AtMostOncePerRetry.

The step result is serialized with the ILambdaSerializer registered on ILambdaContext.Serializer; there is no per-step serializer. See Serialization.

interface StepContext {
  logger: DurableContextLogger;
}

• logger A logger enriched with execution context metadata. See Logging.

@dataclass(frozen=True)
class StepContext:
    logger: LoggerInterface
    attempt: int          # current attempt, 1-based

• logger A logger enriched with execution context metadata. See Logging.
• attempt The current attempt number, starting at 1 for the first execution.

interface StepContext {
    DurableLogger getLogger();
    int getAttempt();      // current retry attempt, 1-based
}

• getLogger() A logger enriched with execution context metadata. See Logging.
• getAttempt() The current retry attempt number (1-based).

Java StepContext does not expose replay state. Use DurableContext.isReplaying() in orchestration code outside the step function.

type StepContext interface {
    context.Context
    Logger() *slog.Logger
    Attempt() int
}

• Logger() Returns the step's *slog.Logger from the standard library log/slog. See Logging.
• Attempt() The 1-based attempt number of the current execution.

StepContext embeds context.Context, so you can pass it directly to AWS SDK calls. It exposes no durable operations and no operation ID.

public interface IStepContext
{
    ILogger Logger { get; }
    int AttemptNumber { get; }   // current retry attempt, 1-based
    string OperationId { get; }
}

• Logger A logger enriched with execution context metadata. See Logging.
• AttemptNumber The current retry attempt number (1-based).
• OperationId The deterministic operation ID for this step.

enum StepSemantics {
  AtLeastOncePerRetry = "AT_LEAST_ONCE_PER_RETRY",
  AtMostOncePerRetry  = "AT_MOST_ONCE_PER_RETRY",
}

• AtLeastOncePerRetry (default) Re-executes the step if the function replays before the SDK checkpoints the result. Safe for idempotent operations.
• AtMostOncePerRetry Executes the step at most once per retry attempt. If the function replays before the SDK checkpoints the result, the SDK skips the step and throws a StepError whose cause.name equals "StepInterruptedError". Use for operations with side effects.

class StepSemantics(Enum):
    AT_LEAST_ONCE_PER_RETRY = "AT_LEAST_ONCE_PER_RETRY"
    AT_MOST_ONCE_PER_RETRY  = "AT_MOST_ONCE_PER_RETRY"

• AT_LEAST_ONCE_PER_RETRY (default) Re-execute the step if the function replays before the result has checkpointed. Safe for idempotent operations.
• AT_MOST_ONCE_PER_RETRY Execute the step at most once per retry attempt. If the function replays before the result has checkpointed, the SDK skips the step and raises StepInterruptedError. Use for operations with side effects.

enum StepSemantics {
    AT_LEAST_ONCE_PER_RETRY,
    AT_MOST_ONCE_PER_RETRY
}

• AT_LEAST_ONCE_PER_RETRY (default) Re-executes the step if the function replays before the result is checkpointed. Safe for idempotent operations.
• AT_MOST_ONCE_PER_RETRY Executes the step at most once per retry attempt. If the function replays before the result is checkpointed, the SDK skips the step and throws StepInterruptedException. Use for operations with side effects.

type StepSemantics int

const (
    AtLeastOncePerRetry StepSemantics = iota
    AtMostOncePerRetry
)

• AtLeastOncePerRetry (default) Re-executes a step whose previous invocation was interrupted before it recorded an outcome. Safe for idempotent operations.
• AtMostOncePerRetry Never re-executes an interrupted attempt. The SDK passes a *durable.StepInterruptedError to the retry strategy as the failed attempt's error, so the interruption consumes one attempt. If the strategy retries, the next attempt runs the step body after the retry delay. If the strategy stops, Step returns a *durable.StepError whose ErrorType is "StepInterruptedError". Use for operations with side effects.

public enum StepSemantics
{
    AtLeastOncePerRetry,
    AtMostOncePerRetry
}

• AtLeastOncePerRetry (default) Re-executes the step if the Lambda is re-invoked before the result is checkpointed. Safe for idempotent operations.
• AtMostOncePerRetry Executes the step at most once per retry attempt. If the Lambda is re-invoked before the result is checkpointed, the SDK skips re-execution. Use for operations with side effects.

Pass any async function directly.

import {
  DurableContext,
  StepContext,
  withDurableExecution,
} from "@aws/durable-execution-sdk-js";

async function validateOrder(ctx: StepContext, orderId: string): Promise<object> {
  return { order_id: orderId, valid: true };
}

export const handler = withDurableExecution(
  async (event: any, context: DurableContext) => {
    const orderId = event.order_id;
    const validation = await context.step("validate_order", (ctx) =>
      validateOrder(ctx, orderId),
    );
    return validation;
  },
);

Step functions are async. await the result of context.step().

Use the @durable_step decorator. It automatically uses the function's name as the step name. Step functions must be synchronous.

from aws_durable_execution_sdk_python import (
    DurableContext,
    StepContext,
    durable_execution,
    durable_step,
)
from aws_durable_execution_sdk_python.config import StepConfig
from aws_durable_execution_sdk_python.retries import (
    RetryStrategyConfig,
    create_retry_strategy,
)


@durable_step
def validate_order(step_context: StepContext, order_id: str) -> dict:
    return {"order_id": order_id, "valid": True}


@durable_execution
def handler(event: dict, context: DurableContext) -> dict:
    order_id = event["order_id"]
    validation = context.step(validate_order(order_id))
    return validation

Pass a lambda or method reference directly. Step functions are synchronous. Use stepAsync() to get a DurableFuture<T> you can compose with other async operations.

import java.util.Map;
import software.amazon.lambda.durable.DurableContext;
import software.amazon.lambda.durable.DurableHandler;
import software.amazon.lambda.durable.StepContext;

public class ValidateOrderExample extends DurableHandler<Map<String, Object>, Map<String, Object>> {
    @Override
    public Map<String, Object> handleRequest(Map<String, Object> event, DurableContext context) {
        String orderId = (String) event.get("order_id");

        Map<String, Object> validation = context.step("validate_order", Map.class,
            (StepContext ctx) -> Map.of("order_id", orderId, "valid", true));

        return validation;
    }
}

A step body is an ordinary synchronous func(durable.StepContext) (O, error). Use durable.StepAsync to get a *durable.Future[O].

package main

import "github.com/aws/aws-durable-execution-sdk-go/durable"

type OrderEvent struct {
    OrderID string `json:"order_id"`
}

type Validation struct {
    OrderID string `json:"order_id"`
    Valid   bool   `json:"valid"`
}

func validateOrder(ctx durable.StepContext, orderID string) (Validation, error) {
    return Validation{OrderID: orderID, Valid: true}, nil
}

func handler(ctx durable.Context, event OrderEvent) (Validation, error) {
    return durable.Step(ctx, "validate_order", func(sc durable.StepContext) (Validation, error) {
        return validateOrder(sc, event.OrderID)
    })
}

func main() {
    durable.Start(handler)
}

Pass an async (ctx, ct) => ... lambda directly. Step bodies are async; await the result of ctx.StepAsync().

using Amazon.Lambda.Core;
using Amazon.Lambda.DurableExecution;

public class ValidateOrderExample
{
    public Task<DurableExecutionInvocationOutput> Handler(
        DurableExecutionInvocationInput input, ILambdaContext context)
        => DurableFunction.WrapAsync<OrderEvent, Validation>(Workflow, input, context);

    private async Task<Validation> Workflow(OrderEvent input, IDurableContext ctx)
    {
        Validation validation = await ctx.StepAsync(
            async (_, _) => ValidateOrder(input.OrderId),
            name: "validate_order");
        return validation;
    }

    private static Validation ValidateOrder(string orderId) => new(orderId, Valid: true);
}

public record OrderEvent(string OrderId);
public record Validation(string OrderId, bool Valid);

If you use an anonymous function it will not automatically get named like the @durable_step decorator does.

result = context.step(lambda _: "some value", name="my_step")

Pass "" as the name for an unnamed inline step.

package main

import "github.com/aws/aws-durable-execution-sdk-go/durable"

func handler(ctx durable.Context, event map[string]any) (string, error) {
    // Pass "" as the name for an unnamed step.
    return durable.Step(ctx, "", func(sc durable.StepContext) (string, error) {
        return "some value", nil
    })
}

func main() {
    durable.Start(handler)
}

Capture arguments in a closure:

import { DurableContext, withDurableExecution } from "@aws/durable-execution-sdk-js";

async function myStep(arg1: string, arg2: number): Promise<string> {
  return `${arg1}: ${arg2}`;
}

export const handler = withDurableExecution(
  async (event: any, context: DurableContext) => {
    const result = await context.step("my_step", async () => myStep("value", 42));
    return result;
  },
);

Use @durable_step and pass arguments when calling the function:

@durable_step
def my_step(step_context: StepContext, arg1: str, arg2: int) -> str:
    return f"{arg1}: {arg2}"

result = context.step(my_step("value", 42))

Capture arguments in a lambda:

import software.amazon.lambda.durable.DurableContext;
import software.amazon.lambda.durable.DurableHandler;
import software.amazon.lambda.durable.StepContext;

public class MultiArgumentStepExample extends DurableHandler<Object, String> {
    @Override
    public String handleRequest(Object input, DurableContext context) {
        String arg1 = "value";
        int arg2 = 42;

        String result = context.step("my_step", String.class,
            (StepContext ctx) -> arg1 + ": " + arg2);

        return result;
    }
}

Capture arguments in the closure. The step body takes only a durable.StepContext.

package main

import (
    "fmt"

    "github.com/aws/aws-durable-execution-sdk-go/durable"
)

func myStep(arg1 string, arg2 int) (string, error) {
    return fmt.Sprintf("%s: %d", arg1, arg2), nil
}

func handler(ctx durable.Context, event map[string]any) (string, error) {
    // Capture arguments in the closure. The step body takes only StepContext.
    arg1, arg2 := "value", 42
    return durable.Step(ctx, "my_step", func(sc durable.StepContext) (string, error) {
        return myStep(arg1, arg2)
    })
}

func main() {
    durable.Start(handler)
}

Capture arguments in the closure:

using Amazon.Lambda.Core;
using Amazon.Lambda.DurableExecution;

public class MultiArgumentStepExample
{
    public Task<DurableExecutionInvocationOutput> Handler(
        DurableExecutionInvocationInput input, ILambdaContext context)
        => DurableFunction.WrapAsync<object, string>(Workflow, input, context);

    private async Task<string> Workflow(object input, IDurableContext ctx)
    {
        string arg1 = "value";
        int arg2 = 42;

        // Capture arguments in the closure
        string result = await ctx.StepAsync(
            async (_, _) => MyStep(arg1, arg2),
            name: "my_step");
        return result;
    }

    private static string MyStep(string arg1, int arg2) => $"{arg1}: {arg2}";
}

The name is the first argument. Pass undefined to omit it.

The @durable_step decorator uses the function's name automatically as the step name. Override it with the name keyword argument.

The name is always the first argument. Pass null for no name.

The name is the second argument, after the context. Pass "" to omit it.

The name is the optional name argument. Omit it to infer one from the call site.