Skip to main content

Crate aws_durable_execution_sdk

Crate aws_durable_execution_sdk 

Source
Expand description

AWS Durable Execution SDK for Rust.

This crate provides a Rust implementation of the AWS Lambda Durable Functions SDK, enabling long-running orchestrations that survive Lambda invocation timeouts through automatic checkpointing and deterministic replay.

§Overview

A durable function is a Lambda function whose progress is automatically checkpointed. If the function is interrupted, it restarts and replays recorded results instead of re-executing operations. The SDK guarantees deterministic replay as long as operations are created in a consistent order across invocations.

§Quick start

use aws_durable_execution_sdk as durable;
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize)]
struct Order { id: String }

#[tokio::main]
async fn main() -> Result<(), lambda_runtime::Error> {
    durable::run(|event: Order, ctx: durable::DurableContext| async move {
        let result = ctx.step(|_step_ctx| async move {
            Ok(format!("processed {}", event.id))
        }).name("process")
          .await?;
        Ok(result)
    }).await
}

§Determinism contract

Each durable operation has an operation ID: the identity that ties a call site to its recorded result. The SDK mints IDs synchronously at the call site, in the order the handler creates operations, and replay hands each recorded result to the operation that claims the same ID. Two kinds of operation are exceptions. A DurableContext::with_retry builder claims no ID at the call: the block claims its ID when the builder becomes its future (.await, .future() or .spawn()). A combinator (DurableContext::try_join_all, DurableContext::join_all, DurableContext::select_ok, DurableContext::race) claims its ID when it is first awaited or polled, or when it is spawned. That point is in the handler’s own control flow, so it is deterministic as long as the handler awaits the combinator where it awaited it on the first run. A combinator that is dropped before that point claims no ID and records nothing. A combinator passed to another combinator must already have claimed its ID: start the inner combinator with .spawn() and pass the returned handle. A still-unclaimed one fails the execution with a context usage error. A map, parallel or parallel_mixed claims one ID from its caller, its own, and numbers its items inside the batch: item i gets the ID of item i in the batch’s namespace, however the items are scheduled. Replay is therefore correct only if the handler creates the same operations in the same order on every invocation:

  1. Keep the control flow that decides which operations to create a pure function of the event and of results the SDK already recorded.
  2. Never create durable operations while iterating a HashMap or HashSet; their iteration order changes between runs. Sort into a Vec first, or use a collection with deterministic iteration order such as BTreeMap, BTreeSet, or the indexmap crate’s IndexMap.
  3. Do not use tokio::select! over durable futures; use DurableContext::race or DurableContext::select_ok, which record which branch won.
  4. Do not use tokio::spawn to run a durable operation in the background; use .spawn() on the operation’s builder, which keeps the spawned work inside the execution’s replay accounting. Dropping the handle .spawn() returns loses only the result: the operation keeps running until it settles, until the scope it was started in closes, or until the invocation ends (see DurableFuture). An operation claimed, spawned or awaited on a task or thread that does not own the context, plugin hook work included, fails the execution with a context usage error. No operation update whose checkpoint admission is requested after the error is recorded is written, so an operation whose next update is refused keeps the last state written, which can be STARTED.
  5. On suspension, the user future is dropped, so do not rely on Drop ordering for correctness between durable operations. For example, a guard that unlocks a resource in Drop runs the moment the execution suspends on a ctx.wait(...), not after the wait completes; release resources in a step instead of a destructor.

§Observability

The SDK instruments the operation lifecycle through the tracing facade: spans around the handler, each child body, each live step body and each wait_for_condition check, and DEBUG events at operation start/finish/replay/retry and execution start/resume/suspend. The span names, event names, and field names are a documented, stable contract, including how to bridge it to OpenTelemetry, in the observability module.

§Instrumentation plugins

A plugin observes each invocation through hooks for the invocation, each operation and each user function; register its factory with Options::builder().plugin(..). The plugin module documents the hooks and the order in which they run.

Re-exports§

pub use self::serdes::JsonSerdes;
pub use self::serdes::PassthroughSerdes;
pub use self::serdes::PayloadSerializer;
pub use self::serdes::Serdes;
pub use lambda_runtime;

Modules§

builders
Fluent operation builders, one public submodule per operation.
lambda_types
The service model types of the checkpoint transport.
observability
The SDK’s observability contract: documented, stable tracing spans and events describing the operation lifecycle.
plugin
Instrumentation plugins: per-invocation hooks for tracing and telemetry.
serdes
Serialization/deserialization abstraction.
test_util
In-process local testing runner (test-util feature).

Structs§

Branch
A branch for DurableContext::parallel.
BranchHandle
The result of one branch of a BranchSet.
BranchKey
The key of one branch of a BranchSet, which reads the branch’s value from a BatchResult<BranchValue> with BatchResult::value.
BranchSet
A set of parallel branches whose results have different types, for DurableContext::parallel_mixed.
BranchValue
The value of one branch of a BranchSet, with its type erased: the item type of the BatchResult that a ParallelMixedBuilder::summary receives.
CallbackError
Error from a callback operation.
CheckpointOutput
The output of a successful ExecutionClient::checkpoint call.
ChildContextError
Error from a child context (sub-orchestration) operation.
CombinatorError
Error from a combinator operation (try_join_all, join_all, select_ok, race).
DurableContext
The durable execution context: a cheap-to-clone handle providing access to all durable operations.
DurableFuture
The uniform future handle for all durable operations.
ExecutionClientError
The terminal outcome a transport returns: a scope, a message and, when the transport has one, the error that caused it.
GetStateOutput
One page of execution state, returned by ExecutionClient::get_state.
InvalidOperationSubType
The error OperationSubType::new returns for a value the service would reject.
InvocationPayload
The raw invocation payload lambda_runtime hands to the service functions wrap produces.
InvocationResponse
The durable response envelope one invocation of a wrap-produced service function resolves with.
InvokeError
Error from an invoke operation.
JoinFailed
Details of a CombinatorErrorKind::JoinFailed failure.
LambdaClient
Client for AWS Lambda
LambdaContext
The Lambda function execution context. The values in this struct are populated using the Lambda environment variables and the headers returned by the poll request to the Runtime APIs.
LambdaExecutionClient
The transport the SDK uses when execution_client is not set. Wrap it to decorate the default.
MaxChecksExceeded
Details of a WaitForConditionErrorKind::MaxChecksExceeded failure.
NonDeterministicExecutionError
Error raised when replay cannot faithfully reproduce the checkpointed history: the claimed operation does not match the record at its slot (the handler produced operations in a different order between invocations), or the record carries a status this SDK version cannot interpret.
OperationError
The top-level error type returned by DurableFuture.
OperationMismatch
Details of a NonDeterministicExecutionErrorKind::OperationMismatch failure.
OperationSubType
An operation subtype: 1 to 32 characters from A-Z, a-z, 0-9, - and _.
Options
Configuration for the durable execution runtime.
OptionsBuilder
Builder for Options.
OptionsValidationError
Error returned when OptionsBuilder::build() detects an invalid configuration combination.
ReplayFilterLayer
A per-layer filter that suppresses events describing replayed work: events carrying their own isReplay = true field (the SDK’s lifecycle events: see crate::observability) and application log lines emitted while their nearest execution namespace replays.
ReplayedFailure
The synthetic source attached to an error rebuilt from a checkpointed failure on replay.
SdkConfig
AWS Shared Configuration
StepContext
Context passed to step bodies.
StepError
Error from a step operation.
TypedError
An error wrapper that records its inner error’s concrete type name for the wire ErrorType.
UnexpectedStatus
Details of a WaitErrorKind::UnexpectedStatus failure.
UnrecognizedStatus
Details of a NonDeterministicExecutionErrorKind::UnrecognizedStatus failure.
WaitError
Error from a wait operation.
WaitForConditionError
Error from a wait-for-condition operation.
WireError
The failure fields of a wire ErrorObject, as a named record.

Enums§

CallbackErrorKind
Specific kinds of callback failures.
ChildContextErrorKind
Specific kinds of child context failures.
CombinatorErrorKind
Specific kinds of combinator failures.
ExecutionClientErrorScope
The recovery scope of an ExecutionClientError.
InvocationStatus
How one invocation of a durable function ended, as a plugin sees it.
InvokeErrorKind
Specific kinds of invoke failures.
NonDeterministicExecutionErrorKind
Specific kinds of non-deterministic execution failures.
OperationErrorKind
Classification of operation errors by operation type.
OperationKind
The kind of a durable operation.
OperationStatus
The status of a durable operation.
RetryDecision
Retry decision returned by a retry-strategy closure.
StepErrorKind
Specific kinds of step failures.
StepSemantics
Execution semantics for a step, controlling behavior on interrupted replay.
WaitErrorKind
Specific kinds of wait failures.
WaitForConditionErrorKind
Specific kinds of wait-for-condition failures.

Traits§

ExecutionClient
The transport for the two durable execution service calls.

Functions§

init_default_subscriber
Installs the default Lambda subscriber with replayed records suppressed.
init_default_subscriber_with_writer
Installs the default Lambda subscriber with replayed records suppressed, writing to writer.
run
Starts the durable function runtime with the given handler.
run_with_options
Starts the durable function runtime with the given handler and options.
wrap
Creates a Lambda service function with durable execution support.

Type Aliases§

BoxError
Boxed error type: Box<dyn std::error::Error + Send + Sync>.