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:
- Keep the control flow that decides which operations to create a pure function of the event and of results the SDK already recorded.
- Never create durable operations while iterating a
HashMaporHashSet; their iteration order changes between runs. Sort into aVecfirst, or use a collection with deterministic iteration order such asBTreeMap,BTreeSet, or theindexmapcrate’sIndexMap. - Do not use
tokio::select!over durable futures; useDurableContext::raceorDurableContext::select_ok, which record which branch won. - Do not use
tokio::spawnto 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 (seeDurableFuture). 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 beSTARTED. - On suspension, the user future is dropped, so do not rely on
Dropordering for correctness between durable operations. For example, a guard that unlocks a resource inDropruns the moment the execution suspends on actx.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
tracingspans 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-utilfeature).
Structs§
- Branch
- A branch for
DurableContext::parallel. - Branch
Handle - The result of one branch of a
BranchSet. - Branch
Key - The key of one branch of a
BranchSet, which reads the branch’s value from aBatchResult<BranchValue>withBatchResult::value. - Branch
Set - A set of parallel branches whose results have different types, for
DurableContext::parallel_mixed. - Branch
Value - The value of one branch of a
BranchSet, with its type erased: the item type of theBatchResultthat aParallelMixedBuilder::summaryreceives. - Callback
Error - Error from a callback operation.
- Checkpoint
Output - The output of a successful
ExecutionClient::checkpointcall. - Child
Context Error - Error from a child context (sub-orchestration) operation.
- Combinator
Error - Error from a combinator operation (
try_join_all,join_all,select_ok,race). - Durable
Context - The durable execution context: a cheap-to-clone handle providing access to all durable operations.
- Durable
Future - The uniform future handle for all durable operations.
- Execution
Client Error - The terminal outcome a transport returns: a scope, a message and, when the transport has one, the error that caused it.
- GetState
Output - One page of execution state, returned by
ExecutionClient::get_state. - Invalid
Operation SubType - The error
OperationSubType::newreturns for a value the service would reject. - Invocation
Payload - The raw invocation payload
lambda_runtimehands to the service functionswrapproduces. - Invocation
Response - The durable response envelope one invocation of a
wrap-produced service function resolves with. - Invoke
Error - Error from an invoke operation.
- Join
Failed - Details of a
CombinatorErrorKind::JoinFailedfailure. - Lambda
Client - Client for AWS Lambda
- Lambda
Context - 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.
- Lambda
Execution Client - The transport the SDK uses when
execution_clientis not set. Wrap it to decorate the default. - MaxChecks
Exceeded - Details of a
WaitForConditionErrorKind::MaxChecksExceededfailure. - NonDeterministic
Execution Error - 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.
- Operation
Error - The top-level error type returned by
DurableFuture. - Operation
Mismatch - Details of a
NonDeterministicExecutionErrorKind::OperationMismatchfailure. - Operation
SubType - An operation subtype: 1 to 32 characters from
A-Z,a-z,0-9,-and_. - Options
- Configuration for the durable execution runtime.
- Options
Builder - Builder for
Options. - Options
Validation Error - Error returned when
OptionsBuilder::build()detects an invalid configuration combination. - Replay
Filter Layer - A per-layer filter that suppresses events describing replayed work:
events carrying their own
isReplay = truefield (the SDK’s lifecycle events: seecrate::observability) and application log lines emitted while their nearest execution namespace replays. - Replayed
Failure - The synthetic source attached to an error rebuilt from a checkpointed failure on replay.
- SdkConfig
- AWS Shared Configuration
- Step
Context - Context passed to step bodies.
- Step
Error - Error from a step operation.
- Typed
Error - An error wrapper that records its inner error’s concrete type name for
the wire
ErrorType. - Unexpected
Status - Details of a
WaitErrorKind::UnexpectedStatusfailure. - Unrecognized
Status - Details of a
NonDeterministicExecutionErrorKind::UnrecognizedStatusfailure. - Wait
Error - Error from a wait operation.
- Wait
ForCondition Error - Error from a wait-for-condition operation.
- Wire
Error - The failure fields of a wire
ErrorObject, as a named record.
Enums§
- Callback
Error Kind - Specific kinds of callback failures.
- Child
Context Error Kind - Specific kinds of child context failures.
- Combinator
Error Kind - Specific kinds of combinator failures.
- Execution
Client Error Scope - The recovery scope of an
ExecutionClientError. - Invocation
Status - How one invocation of a durable function ended, as a plugin sees it.
- Invoke
Error Kind - Specific kinds of invoke failures.
- NonDeterministic
Execution Error Kind - Specific kinds of non-deterministic execution failures.
- Operation
Error Kind - Classification of operation errors by operation type.
- Operation
Kind - The kind of a durable operation.
- Operation
Status - The status of a durable operation.
- Retry
Decision - Retry decision returned by a retry-strategy closure.
- Step
Error Kind - Specific kinds of step failures.
- Step
Semantics - Execution semantics for a step, controlling behavior on interrupted replay.
- Wait
Error Kind - Specific kinds of wait failures.
- Wait
ForCondition Error Kind - Specific kinds of wait-for-condition failures.
Traits§
- Execution
Client - 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>.