Skip to main content

aws_durable_execution_sdk/
future.rs

1//! Future types for durable operations.
2//!
3//! [`DurableFuture`] is the uniform handle for all durable operation
4//! results. [`Branch`] defines a named parallel branch, and [`BranchSet`]
5//! a set of branches with different result types whose results each
6//! [`BranchHandle`] returns. [`Callback`] holds a callback token and its
7//! result future.
8
9use std::future::Future;
10use std::marker::PhantomData;
11use std::pin::Pin;
12use std::sync::Arc;
13use std::sync::atomic::{AtomicBool, Ordering};
14use std::task::{Context, Poll};
15
16use crate::coordinator::InvocationCoordinator;
17
18use crate::BoxError;
19use crate::DurableContext;
20use crate::error::{ChildFnError, OperationError};
21
22/// The uniform future handle for all durable operations.
23///
24/// Every builder state that implements
25/// [`IntoFuture`](std::future::IntoFuture) targets `DurableFuture<O>`. A
26/// `wait_for_condition` builder implements it only once a wait strategy is
27/// set. Every operation except a combinator and a
28/// [`DurableContext::with_retry`] block has already claimed its operation
29/// ID when its builder was created. A `with_retry` block claims its ID when
30/// the builder becomes this future. A combinator
31/// ([`DurableContext::try_join_all`], [`DurableContext::join_all`],
32/// [`DurableContext::select_ok`] and [`DurableContext::race`]) claims its ID
33/// on the first poll of this future, or at `.spawn()`. A combinator future
34/// that is dropped before its first poll claims no ID and records nothing.
35/// A combinator future passed to another combinator must already have
36/// claimed its ID: start it with `.spawn()` and pass the returned handle. A
37/// still-unclaimed one fails the execution with a context usage error. The
38/// body runs when polled (lazy) unless the builder was terminated with
39/// `.spawn()` (eager).
40///
41/// When produced by `.spawn()`, `.spawn_batch()` or
42/// [`Callback::spawn_result`], the operation runs eagerly on its own SDK
43/// task. Dropping the `DurableFuture` loses only the result: the operation
44/// keeps running until it settles, its scope closes or the invocation ends.
45/// An operation that settles records its outcome and fires its plugin
46/// hooks. Its error goes into its record and is returned to nobody, and a
47/// panic in it fails the invocation. A running detached operation keeps the
48/// invocation from suspending, and one that waits only on the service lets
49/// it suspend. When the handler returns, the invocation ends and stops each
50/// detached operation that still runs. A stopped operation fires no end
51/// hook. Its record, if it has one, keeps the last state written, which can
52/// be `STARTED`, and the execution can end with the handler's result.
53///
54/// The SDK stops work in three cases:
55///
56/// - a combinator stops the `.future()` inputs it started that are still
57///   running when it resolves, and lets an input started with `.spawn()`
58///   run;
59/// - a closed scope stops the work still running inside it. A scope closes
60///   when a child context's body returns, when a `with_retry` block with
61///   its own record ends, when an attempt of any `with_retry` block ends,
62///   and when a `map`, `parallel` or
63///   `parallel_mixed` item, or the whole batch, completes;
64/// - the end of the invocation stops all remaining operation work.
65///
66/// A stopped task stops at its next `.await`, and its record can stay
67/// `STARTED`. The SDK cannot stop code between two `.await`s,
68/// `spawn_blocking` work, tasks or threads the handler starts itself, or a
69/// request already sent to another service.
70///
71/// An operation that waits on the service (a wait, a callback result, an
72/// invoke) stays pending while other SDK work runs, and continues in the
73/// same invocation when a checkpoint response completes it. The invocation
74/// suspends only when no SDK work can make progress and an operation
75/// waits.
76///
77/// # Examples
78///
79/// ```no_run
80/// use aws_durable_execution_sdk as durable;
81/// use aws_durable_execution_sdk::DurableFuture;
82///
83/// async fn handler(
84///     _event: serde_json::Value,
85///     ctx: durable::DurableContext,
86/// ) -> Result<(), durable::BoxError> {
87///     // DurableFuture implements Future
88///     let future: DurableFuture<i32> = ctx.step(|_| async { Ok(42) }).future();
89///     let value: i32 = future.await?;
90///     assert_eq!(value, 42);
91///     Ok(())
92/// }
93/// ```
94#[must_use = "futures do nothing unless polled or spawned"]
95#[non_exhaustive]
96pub struct DurableFuture<O> {
97    inner: Pin<Box<dyn Future<Output = Result<O, OperationError>> + Send>>,
98    /// The first-poll flag of an operation started on its own task, with
99    /// the coordinator to notify when the handle is first polled. `None`
100    /// for every other handle, and after the first poll.
101    awaited: Option<(Arc<AtomicBool>, Arc<InvocationCoordinator>)>,
102    /// The pending claim of a combinator that has not claimed its operation
103    /// ID yet. `None` for every other future, and once the claim ran. While
104    /// it is `Some`, `inner` is a placeholder that is never polled.
105    claim: Option<PendingClaim<O>>,
106    /// The task context captured when the operation was created: the
107    /// frames of its context and the span current at the call. A task that
108    /// runs this future runs inside it, whoever starts the task.
109    task_cx: crate::task::TaskContext,
110    /// The start step of a lazy operation whose execution begins with one
111    /// (see [`crate::start`]): it runs the start step and returns the rest
112    /// of the operation. `None` for every other future, and once it ran.
113    /// While it is `Some`, `inner` is a placeholder that is never polled.
114    begin: Option<BeginFn<O>>,
115    /// Whether a combinator begins this future by polling it once on its
116    /// own task: a lazy invoke or `wait_for_condition`, whose first poll
117    /// serializes its input before it can queue its `START`.
118    first_poll_start: bool,
119    /// The ownership gate of an operation future: the context whose owner
120    /// may poll it. `None` for a future that executes nothing of its own:
121    /// a spawned handle, a settled callback result, an error future, and a
122    /// combinator until it claims its ID. Boxed, so the gate adds one
123    /// pointer to every future.
124    gate: Option<Box<PollGate>>,
125}
126
127/// The ownership gate of one operation future (see [`DurableFuture`]).
128///
129/// Every poll checks ownership, before the operation checks admission: an
130/// abandoned scope makes the operation pend, so a later check would never
131/// run for a future its owner sent out unpolled. The gate keeps no
132/// identity of an earlier poller, because Tokio may give a new task the ID
133/// of a task that exited, and a cached ID would then admit a task the
134/// invocation does not own. So a future that its owner polled until it
135/// suspended and then moved to such a task fails the execution when that
136/// task resumes it. The check costs the owner comparison and, for a task
137/// other than the owner, one lookup in the set of tasks the SDK started.
138struct PollGate {
139    ctx: DurableContext,
140}
141
142impl PollGate {
143    fn new(ctx: &DurableContext) -> Self {
144        Self { ctx: ctx.clone() }
145    }
146
147    /// Admits the current poll when the calling task or thread owns the
148    /// context. A refused poll has recorded the fatal context usage error.
149    fn admit(&mut self) -> Result<(), OperationError> {
150        self.ctx.enforce_task_ownership()
151    }
152}
153
154/// The start step of a lazy operation, and the builder of its remainder.
155type BeginFn<O> =
156    Box<dyn FnOnce() -> Pin<Box<dyn Future<Output = Result<O, OperationError>> + Send>> + Send>;
157
158/// The claim a combinator future runs on its first poll or at `.spawn()`.
159///
160/// `run` claims the combinator's operation ID on the context the
161/// combinator was created on, checks the claimed ID against the recorded
162/// history, and returns the future that runs the combinator.
163pub(crate) struct PendingClaim<O> {
164    /// The combinator's public method, such as `"race"`.
165    method: &'static str,
166    /// The display name of the context the combinator was created on:
167    /// `"root"` or the positional ID of the operation that created it.
168    context: String,
169    /// Claims the ID and builds the combinator's future.
170    run: Box<dyn FnOnce() -> DurableFuture<O> + Send>,
171}
172
173impl<O> PendingClaim<O> {
174    /// Creates the pending claim of combinator `method` created on the
175    /// context whose display name is `context`.
176    pub(crate) fn new(
177        method: &'static str,
178        context: String,
179        run: impl FnOnce() -> DurableFuture<O> + Send + 'static,
180    ) -> Self {
181        Self {
182            method,
183            context,
184            run: Box::new(run),
185        }
186    }
187}
188
189impl<O> std::fmt::Debug for DurableFuture<O> {
190    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
191        f.debug_struct("DurableFuture").finish_non_exhaustive()
192    }
193}
194
195impl<O: Send + 'static> DurableFuture<O> {
196    /// Creates a `DurableFuture` from an async computation.
197    pub(crate) fn from_async<F>(fut: F) -> Self
198    where
199        F: Future<Output = Result<O, OperationError>> + Send + 'static,
200    {
201        Self {
202            inner: Box::pin(fut),
203            awaited: None,
204            claim: None,
205            task_cx: crate::task::TaskContext::none(),
206            begin: None,
207            first_poll_start: false,
208            gate: None,
209        }
210    }
211
212    /// Maps the output and keeps the task context, so a
213    /// task that later runs the mapped future runs it inside the frames
214    /// and span of the operation's creation, as for the unmapped future.
215    pub(crate) fn map_output<T, M>(self, map: M) -> DurableFuture<T>
216    where
217        T: Send + 'static,
218        M: FnOnce(Result<O, OperationError>) -> Result<T, OperationError> + Send + 'static,
219    {
220        let Self {
221            inner,
222            awaited,
223            claim,
224            task_cx,
225            begin,
226            first_poll_start,
227            gate,
228        } = self;
229        match claim {
230            // An unclaimed combinator stays unclaimed: the mapped future
231            // keeps a pending claim that claims the ID and maps the claimed
232            // future, so `claim_now` takes the claimed future's context.
233            Some(claim) => {
234                let PendingClaim {
235                    method,
236                    context,
237                    run,
238                } = claim;
239                DurableFuture::deferred(PendingClaim::new(method, context, move || {
240                    run().map_output(map)
241                }))
242            }
243            // A lazy operation stays lazy: the mapped future keeps the
244            // start step, and maps the remainder the start step returns.
245            None => match begin {
246                Some(begin) => DurableFuture {
247                    inner: Box::pin(std::future::pending()),
248                    awaited,
249                    claim: None,
250                    task_cx,
251                    begin: Some(Box::new(move || {
252                        let rest = begin();
253                        Box::pin(async move { map(rest.await) })
254                    })),
255                    first_poll_start,
256                    gate,
257                },
258                None => DurableFuture {
259                    inner: Box::pin(async move { map(inner.await) }),
260                    awaited,
261                    claim: None,
262                    task_cx,
263                    begin: None,
264                    first_poll_start,
265                    gate,
266                },
267            },
268        }
269    }
270
271    /// Creates the future of a combinator that claims its operation ID on
272    /// its first poll or at `.spawn()`, through [`Self::claim_now`].
273    pub(crate) fn deferred(claim: PendingClaim<O>) -> Self {
274        Self {
275            // A placeholder: `claim_now` replaces it before the first poll.
276            inner: Box::pin(std::future::pending()),
277            awaited: None,
278            claim: Some(claim),
279            task_cx: crate::task::TaskContext::none(),
280            begin: None,
281            first_poll_start: false,
282            gate: None,
283        }
284    }
285
286    /// Runs the pending claim of a combinator future: claims its operation
287    /// ID and checks it against the recorded history.
288    ///
289    /// The first poll and `.spawn()` call this. It runs the claim once. It
290    /// does nothing for a future that is not a combinator, and for a
291    /// combinator that already claimed.
292    pub(crate) fn claim_now(&mut self) {
293        if let Some(claim) = self.claim.take() {
294            let claimed = (claim.run)();
295            self.inner = claimed.inner;
296            self.task_cx = claimed.task_cx;
297            self.gate = claimed.gate;
298        }
299    }
300
301    /// Reports whether this future is a combinator that has not claimed its
302    /// operation ID yet.
303    pub(crate) fn is_unclaimed_combinator(&self) -> bool {
304        self.claim.is_some()
305    }
306
307    /// The message of the context usage error an outer combinator records
308    /// when it would start this still-unclaimed combinator as an input.
309    /// `None` when this future is not an unclaimed combinator.
310    ///
311    /// `outer` is the positional ID of the outer combinator.
312    pub(crate) fn unclaimed_input_message(&self, outer: &str) -> Option<String> {
313        self.claim.as_ref().map(|claim| {
314            format!(
315                "context usage error in \"{method}\": the combinator was created on context \
316                 \"{context}\", but combinator \"{outer}\" started it as an input. Start the \
317                 inner combinator with .spawn() and pass the returned handle to the outer \
318                 combinator.",
319                method = claim.method,
320                context = claim.context,
321            )
322        })
323    }
324
325    /// Creates the future of one operation created on `ctx`.
326    ///
327    /// When one of the context's owners is abandoned before the first poll,
328    /// `fut` is never polled and the future never resolves (see
329    /// [`crate::checkpoint_coalescer::Admission`]). Every builder terminal,
330    /// awaited or spawned, passes here before its operation runs.
331    pub(crate) fn for_operation<F>(ctx: &DurableContext, fut: F) -> Self
332    where
333        F: Future<Output = Result<O, OperationError>> + Send + 'static,
334    {
335        let gate = ctx.clone();
336        let mut future = Self::from_async(async move {
337            gate.admit_operation().await;
338            drop(gate);
339            fut.await
340        });
341        future.task_cx = crate::task::TaskContext::current();
342        future.gate = Some(Box::new(PollGate::new(ctx)));
343        future
344    }
345
346    /// The task context captured when the operation was created.
347    pub(crate) fn task_context(&self) -> crate::task::TaskContext {
348        self.task_cx.clone()
349    }
350
351    /// Creates the future of one operation whose start step already ran on
352    /// the caller's task (see [`crate::start`]): `fut` is the rest of the
353    /// operation.
354    ///
355    /// It captures the task context current at the call, as
356    /// [`Self::for_operation`] does.
357    pub(crate) fn for_started_operation<F>(ctx: &DurableContext, fut: F) -> Self
358    where
359        F: Future<Output = Result<O, OperationError>> + Send + 'static,
360    {
361        let mut future = Self::from_async(fut);
362        future.task_cx = crate::task::TaskContext::current();
363        future.gate = Some(Box::new(PollGate::new(ctx)));
364        future
365    }
366
367    /// Creates the lazy future of one operation whose execution begins with
368    /// the start step (see [`crate::start`]): a step, a wait, a child
369    /// context, `with_retry`, a map, a parallel, a `parallel_mixed`, a
370    /// `create_callback` or a `wait_for_callback`.
371    ///
372    /// `begin` runs the start step and returns the rest of the operation.
373    /// It runs on the first poll, in the poller's context, or earlier when a
374    /// combinator begins the future as an input, in the creator's context
375    /// ([`Self::begin_in_creator_context`]). The start step checks
376    /// admission itself before it queues anything, so this adds no
377    /// admission gate of its own, unlike [`Self::for_operation`].
378    pub(crate) fn for_start_step<F>(
379        ctx: &DurableContext,
380        begin: impl FnOnce() -> F + Send + 'static,
381    ) -> Self
382    where
383        F: Future<Output = Result<O, OperationError>> + Send + 'static,
384    {
385        Self {
386            // A placeholder: `begin_now` replaces it before the first poll.
387            inner: Box::pin(std::future::pending()),
388            awaited: None,
389            claim: None,
390            begin: Some(Box::new(move || Box::pin(begin()))),
391            first_poll_start: false,
392            task_cx: crate::task::TaskContext::current(),
393            gate: Some(Box::new(PollGate::new(ctx))),
394        }
395    }
396
397    /// Runs the start step of a lazy operation now, on the calling task,
398    /// in the caller's context: the first poll calls this, so an operation
399    /// awaited directly runs both its start step and its body in its
400    /// awaiter's frames and span (#126 rule 5.2).
401    ///
402    /// It runs the start step once, and does nothing for a future without
403    /// one.
404    fn begin_now(&mut self) {
405        if let Some(begin) = self.begin.take() {
406            self.inner = begin();
407        }
408    }
409
410    /// Runs the start step of a lazy combinator input now, on the calling
411    /// task, inside the task context captured at the operation's creation:
412    /// its frames and its span. So `on_operation_start` and the start step
413    /// see the creator's context when a combinator created elsewhere begins
414    /// the input, as the input's remainder does on the task the combinator
415    /// spawns with that context (#126 rule 5.2).
416    ///
417    /// Only a combinator that begins its inputs calls this. It runs the
418    /// start step once, and does nothing for a future without one.
419    pub(crate) fn begin_in_creator_context(&mut self) {
420        if let Some(begin) = self.begin.take() {
421            self.inner = self.task_cx.enter(begin);
422        }
423    }
424
425    /// Creates the future of a lazy invoke or `wait_for_condition` on
426    /// `ctx`, as [`Self::for_operation`] does. A combinator begins such an
427    /// input by polling it once on its own task, because its first poll
428    /// serializes its input before it can queue its `START`.
429    pub(crate) fn for_first_poll_operation<F>(ctx: &DurableContext, fut: F) -> Self
430    where
431        F: Future<Output = Result<O, OperationError>> + Send + 'static,
432    {
433        let mut future = Self::for_operation(ctx, fut);
434        future.first_poll_start = true;
435        future
436    }
437
438    /// Reports whether a combinator begins this future by polling it once
439    /// on its own task (see [`Self::for_first_poll_operation`]).
440    pub(crate) fn starts_on_first_poll(&self) -> bool {
441        self.first_poll_start
442    }
443
444    /// Spawns the operation future on its own task, blessed in the task
445    /// ownership of `ctx` before its first poll.
446    ///
447    /// The task starts through the task gateway
448    /// ([`crate::task::spawn_tracked`]) and holds a permit of the
449    /// invocation's coordinator whenever it can make progress, so the
450    /// invocation does not suspend while it runs. A wait inside it registers
451    /// like any other wait. The task is registered with the scopes of `ctx`
452    /// (see [`crate::checkpoint_coalescer::Admission`]), so it stops when
453    /// one of them closes. Dropping the returned future loses only the
454    /// result: the task keeps running. A caller that does not own the
455    /// context fails the execution with a context usage error, no task
456    /// starts, and a combinator claims no ID. Otherwise a combinator claims
457    /// its ID here, before its task starts. A panic in the operation resumes on
458    /// the task that awaits the handle, with its original payload, and
459    /// fails the invocation when nothing awaits it. When the invocation
460    /// coordinator was created without a Tokio runtime, the returned future
461    /// resolves to an error and the operation records nothing.
462    ///
463    /// `awaited` is the first-poll flag the operation's wait registrations
464    /// carry. The returned handle sets it on its first poll and asks the
465    /// coordinator to arm those registrations' refreshes (see
466    /// [`crate::coordinator`]).
467    pub(crate) fn spawn_blessed(
468        mut future: Self,
469        ctx: &DurableContext,
470        awaited: Option<Arc<AtomicBool>>,
471    ) -> Self {
472        // The ownership check runs before a combinator's pending claim, so
473        // a refused `.spawn()` records the error of method `spawn` rather
474        // than the claim's, and the combinator claims no ID.
475        if let Some(refused) = Self::refuse_foreign_spawn(ctx) {
476            return refused;
477        }
478        future.claim_now();
479        let coordinator = ctx.coordinator();
480        let task_cx = future.task_context();
481        match crate::task::spawn_tracked(task_cx.clone(), coordinator, ctx.task_ownership(), future)
482        {
483            Ok(task) => {
484                if let Some(abort) = task.abort_handle() {
485                    ctx.admission().register_task(ctx.owners(), abort);
486                }
487                let mut handle = Self::from_async(async move { task.await.into_value() });
488                handle.awaited = awaited.map(|flag| (flag, Arc::clone(coordinator)));
489                // The handle keeps the operation's context. A combinator
490                // that takes it spawns its input task with that context, so
491                // the input runs inside the creator's frames and span.
492                handle.task_cx = task_cx;
493                handle
494            }
495            // The invocation coordinator was created without a Tokio runtime:
496            // the operation records nothing and resolves to an error.
497            Err(no_runtime) => {
498                Self::from_async(
499                    async move { Err(crate::task::NoRuntime::operation_error(no_runtime)) },
500                )
501            }
502        }
503    }
504
505    /// Builds the operation future with `build` and spawns it as
506    /// [`Self::spawn_blessed`] describes, for an operation whose `.spawn()`
507    /// runs no start step on the caller's task.
508    ///
509    /// The task-ownership check runs before `build`: building an invoke or
510    /// a `wait_for_condition` future runs its replay identity preflight,
511    /// which records a fatal error on a mismatch, and the first fatal error
512    /// wins. So a caller that does not own the context fails the execution
513    /// with the error of method `spawn`, and `build` is not called.
514    pub(crate) fn spawn_built(
515        ctx: &DurableContext,
516        awaited: Option<Arc<AtomicBool>>,
517        build: impl FnOnce() -> Self,
518    ) -> Self {
519        if let Some(refused) = Self::refuse_foreign_spawn(ctx) {
520            return refused;
521        }
522        Self::spawn_blessed(build(), ctx, awaited)
523    }
524
525    /// Starts an operation whose JS form begins inside the call: runs its
526    /// start step on the caller's task, then spawns the rest of it.
527    ///
528    /// The task-ownership check runs first: a caller that does not own the
529    /// context fails the execution, `start` is not called, and nothing is
530    /// queued. The runtime check runs next: when the invocation coordinator
531    /// was created without a Tokio runtime, the returned future resolves to
532    /// an error, `start` is not called, and nothing is queued. Otherwise `start` builds the
533    /// operation future after it ran the start step (see [`crate::start`])
534    /// on this task: the admission check, the task-ownership check, and the
535    /// `START` the
536    /// operation's record requires, with the start hook its JS order fires
537    /// at the call. Then the future runs on its own task, as
538    /// [`Self::spawn_blessed`] describes.
539    pub(crate) fn spawn_started(
540        ctx: &DurableContext,
541        awaited: Option<Arc<AtomicBool>>,
542        start: impl FnOnce() -> Self,
543    ) -> Self {
544        // The task-ownership check runs first: before the runtime check, so
545        // a thread with no runtime is refused rather than told it has none,
546        // and before the admission check and the builder's replay identity
547        // preflight, so a caller that does not own the context fails the
548        // execution in an abandoned owner and when the record also
549        // contradicts the operation.
550        if let Some(refused) = Self::refuse_foreign_spawn(ctx) {
551            return refused;
552        }
553        if let Err(no_runtime) = crate::task::task_runtime(ctx.coordinator()).map(drop) {
554            return Self::from_async(async move {
555                Err(crate::task::NoRuntime::operation_error(no_runtime))
556            });
557        }
558        Self::spawn_blessed(start(), ctx, awaited)
559    }
560
561    /// Refuses a `.spawn()` from a task or thread that does not own `ctx`:
562    /// records the fatal context usage error for method `spawn` and returns
563    /// a handle that resolves to an error. No task starts, so the operation
564    /// takes no permit and its body never runs. Returns `None` for a caller
565    /// that owns the context.
566    fn refuse_foreign_spawn(ctx: &DurableContext) -> Option<Self> {
567        let reason = ctx.task_ownership().check_current_task().err()?;
568        ctx.coordinator().record_fatal(
569            "Error".to_owned(),
570            crate::context::foreign_caller_message("spawn"),
571        );
572        Some(Self::from_async(async move {
573            Err(OperationError::from_kind(
574                crate::error::OperationErrorKind::Step(crate::error::StepError::new(
575                    crate::error::StepErrorKind::ExecutionFailed,
576                    Some(reason.into()),
577                )),
578            ))
579        }))
580    }
581}
582
583impl<O: Send + 'static> Future for DurableFuture<O> {
584    type Output = Result<O, OperationError>;
585
586    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
587        // The first poll of a combinator claims its operation ID.
588        self.claim_now();
589        // Every poll checks ownership before the operation checks
590        // admission.
591        if let Some(gate) = self.gate.as_mut()
592            && let Err(refused) = gate.admit()
593        {
594            return Poll::Ready(Err(refused));
595        }
596        // The first poll of a lazy operation runs its start step, unless a
597        // combinator ran it already.
598        self.begin_now();
599        // The first poll of the handle of an operation started on its own
600        // task: from now on the scheduler refreshes its registrations.
601        if let Some((flag, coordinator)) = self.awaited.take() {
602            flag.store(true, Ordering::SeqCst);
603            coordinator.notify_awaited();
604        }
605        self.inner.as_mut().poll(cx)
606    }
607}
608
609// DurableFuture<O> is automatically Send when O: Send, since it only
610// contains a pinned boxed future that is Send when O: Send.
611
612/// A branch for [`DurableContext::parallel`].
613///
614/// Each branch defines an optional name and an async closure that receives
615/// a child [`DurableContext`]. History records the name, or
616/// `parallel-branch-{index}` when the branch has no name or an empty one.
617///
618/// # Examples
619///
620/// ```no_run
621/// use aws_durable_execution_sdk::{Branch, DurableContext};
622///
623/// let branch = Branch::new("process-a", |ctx: DurableContext| async move {
624///     let v = ctx.step(|_| async { Ok(1) }).await?;
625///     Ok(v)
626/// });
627/// # drop(branch);
628/// ```
629#[non_exhaustive]
630pub struct Branch<O> {
631    name: Option<String>,
632    body: BranchBody<O>,
633}
634
635/// The erased body of one parallel branch (crate-internal).
636///
637/// Branch bodies are inherently heterogeneous: every `Branch::new` call
638/// site captures a different closure and future type, and they are all
639/// collected into one `Vec`, so exactly ONE erasure per branch is
640/// unavoidable. This type keeps it to exactly one: the user's closure and
641/// its future live UNERASED inside a single boxed future built at
642/// [`Branch::new`]. The child [`DurableContext`] is not known until the
643/// batch coordinator dispatches the branch, so it is delivered through a
644/// oneshot channel the body awaits on first poll. There is no nested
645/// closure-box-returning-future-box layering: polling a running branch goes
646/// through one vtable hop.
647pub(crate) struct BranchBody<O> {
648    /// Delivers the child context to the body. The coordinator sends the
649    /// context BEFORE first polling `future`, so the body's receive
650    /// resolves immediately on first poll.
651    ctx_tx: tokio::sync::oneshot::Sender<DurableContext>,
652    /// The single erased branch future: awaits the child context, then runs
653    /// the user's factory closure and its future in place.
654    future: Pin<Box<dyn Future<Output = Result<O, ChildFnError>> + Send>>,
655}
656
657impl<O> BranchBody<O> {
658    /// Injects the child context and returns the branch future, ready to
659    /// poll. Called exactly once by the batch coordinator at dispatch time.
660    pub(crate) fn start(
661        self,
662        ctx: DurableContext,
663    ) -> Pin<Box<dyn Future<Output = Result<O, ChildFnError>> + Send>> {
664        // Send cannot fail: the receiver lives inside `self.future`, which
665        // we hold. Ignore the impossible error rather than panicking.
666        let _ = self.ctx_tx.send(ctx);
667        self.future
668    }
669}
670
671impl<O> std::fmt::Debug for Branch<O> {
672    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
673        f.debug_struct("Branch")
674            .field("name", &self.name)
675            .finish_non_exhaustive()
676    }
677}
678
679impl<O: Send + 'static> Branch<O> {
680    /// Creates a new named branch.
681    ///
682    /// The factory function receives a child [`DurableContext`] and returns
683    /// a future producing the branch result. The factory is not invoked
684    /// here: it runs when the parallel operation dispatches the branch.
685    ///
686    /// History records `name`. An empty name records
687    /// `parallel-branch-{index}`, and a completion predicate sees
688    /// `Some("")`.
689    ///
690    /// # Examples
691    ///
692    /// ```no_run
693    /// use aws_durable_execution_sdk::{Branch, DurableContext};
694    ///
695    /// let branch: Branch<i32> = Branch::new("my-branch", |_ctx: DurableContext| async move {
696    ///     Ok(42)
697    /// });
698    /// # drop(branch);
699    /// ```
700    pub fn new<F, Fut>(name: impl Into<String>, factory: F) -> Self
701    where
702        F: FnOnce(DurableContext) -> Fut + Send + 'static,
703        Fut: Future<Output = Result<O, BoxError>> + Send + 'static,
704    {
705        Self::with_name(Some(name.into()), factory)
706    }
707
708    /// A branch the caller does not name. A completion predicate sees
709    /// `None`; history records `parallel-branch-{index}`.
710    ///
711    /// # Examples
712    ///
713    /// ```no_run
714    /// use aws_durable_execution_sdk::{Branch, DurableContext};
715    ///
716    /// let branch: Branch<i32> = Branch::unnamed(|_ctx: DurableContext| async move { Ok(42) });
717    /// assert_eq!(branch.name(), None);
718    /// ```
719    pub fn unnamed<F, Fut>(factory: F) -> Self
720    where
721        F: FnOnce(DurableContext) -> Fut + Send + 'static,
722        Fut: Future<Output = Result<O, BoxError>> + Send + 'static,
723    {
724        Self::with_name(None, factory)
725    }
726
727    /// Builds a branch with the caller's name, if any (internal).
728    fn with_name<F, Fut>(name: Option<String>, factory: F) -> Self
729    where
730        F: FnOnce(DurableContext) -> Fut + Send + 'static,
731        Fut: Future<Output = Result<O, BoxError>> + Send + 'static,
732    {
733        let (ctx_tx, ctx_rx) = tokio::sync::oneshot::channel::<DurableContext>();
734        Self {
735            name,
736            body: BranchBody {
737                ctx_tx,
738                // The SDK does the pinning and BoxError -> internal-carrier
739                // type erasure so callers write a plain `async move` body
740                // with `?`. This is the branch's ONE erasure: the factory
741                // closure and its concrete future both live inside this box;
742                // there is no separate closure box producing a second
743                // future box.
744                future: Box::pin(async move {
745                    let ctx = ctx_rx.await.map_err(|_| {
746                        ChildFnError::new("branch context was never delivered (coordinator gone)")
747                    })?;
748                    factory(ctx).await.map_err(ChildFnError::from)
749                }),
750            },
751        }
752    }
753
754    /// Returns the name the caller gave, or `None` for a branch built with
755    /// [`Branch::unnamed`].
756    pub fn name(&self) -> Option<&str> {
757        self.name.as_deref()
758    }
759
760    /// Consumes the branch and returns its name and erased body (internal).
761    pub(crate) fn into_parts(self) -> (Option<String>, BranchBody<O>) {
762        (self.name, self.body)
763    }
764}
765
766/// A callback token and its result future.
767///
768/// Returned by [`DurableContext::create_callback`]. Call [`id()`](Self::id)
769/// to obtain the token string that external systems use to complete the
770/// callback, and [`result()`](Self::result) to get the future that
771/// resolves when the callback arrives.
772///
773/// # Examples
774///
775/// ```no_run
776/// use aws_durable_execution_sdk as durable;
777/// use serde::{Deserialize, Serialize};
778///
779/// #[derive(Serialize, Deserialize)]
780/// struct Approval { approved: bool }
781///
782/// async fn handler(
783///     _event: serde_json::Value,
784///     ctx: durable::DurableContext,
785/// ) -> Result<bool, durable::BoxError> {
786///     let cb = ctx.create_callback::<Approval>()
787///         .name("wait-approval")
788///         .await?;
789///     let _id = cb.id(); // send to external system
790///     let approval = cb.result().await?;
791///     Ok(approval.approved)
792/// }
793/// ```
794#[derive(Debug)]
795#[non_exhaustive]
796pub struct Callback<O> {
797    id: String,
798    state: CallbackState<O>,
799}
800
801/// Resolves a pending callback from its record once the record is
802/// terminal.
803pub(crate) type CallbackResolver<O> =
804    Box<dyn FnOnce() -> Pin<Box<dyn Future<Output = Result<O, OperationError>> + Send>> + Send>;
805
806/// What a pending callback's `result()` needs, besides its context and
807/// wire ID, to build the plugin info of the callback.
808#[derive(Debug)]
809pub(crate) struct CallbackIdentity {
810    /// The callback's name.
811    pub(crate) name: Option<String>,
812    /// The name the plugin hooks report instead of `name`, if any.
813    pub(crate) plugin_name: Option<String>,
814    /// The callback's resolved subtype.
815    pub(crate) sub_type: String,
816}
817
818/// Internal state for a callback: either settled (replay) or pending (live).
819enum CallbackState<O> {
820    /// The callback has a known outcome from the checkpoint log (replay).
821    Settled(Option<Result<O, OperationError>>),
822    /// The callback is in flight: the result waits on its record.
823    Pending {
824        /// The context the callback was created on.
825        ctx: DurableContext,
826        /// The callback operation's wire ID.
827        wire_id: String,
828        /// The name, plugin name and subtype of the callback.
829        identity: CallbackIdentity,
830        /// Builds the outcome from the terminal record.
831        resolver: CallbackResolver<O>,
832    },
833}
834
835impl<O: std::fmt::Debug> std::fmt::Debug for CallbackState<O> {
836    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
837        match self {
838            Self::Settled(outcome) => f.debug_tuple("Settled").field(outcome).finish(),
839            Self::Pending {
840                ctx,
841                wire_id,
842                identity,
843                ..
844            } => f
845                .debug_struct("Pending")
846                .field("ctx", ctx)
847                .field("wire_id", wire_id)
848                .field("identity", identity)
849                .finish_non_exhaustive(),
850        }
851    }
852}
853
854impl<O: Send + 'static> Callback<O> {
855    /// Creates a settled callback (replay: outcome already known).
856    pub(crate) fn new_settled(id: String, result: Result<O, OperationError>) -> Self {
857        Self {
858            id,
859            state: CallbackState::Settled(Some(result)),
860        }
861    }
862
863    /// Creates a pending callback (live: outcome not yet known).
864    /// `resolver` builds the outcome from the record once it is terminal.
865    pub(crate) fn new_pending(
866        id: String,
867        ctx: DurableContext,
868        wire_id: String,
869        identity: CallbackIdentity,
870        resolver: CallbackResolver<O>,
871    ) -> Self {
872        Self {
873            id,
874            state: CallbackState::Pending {
875                ctx,
876                wire_id,
877                identity,
878                resolver,
879            },
880        }
881    }
882
883    /// Returns the callback ID token.
884    ///
885    /// This string is passed to an external system, which uses it to
886    /// complete the callback via the durable execution API.
887    ///
888    /// # Examples
889    ///
890    /// ```no_run
891    /// use aws_durable_execution_sdk as durable;
892    /// use serde::{Deserialize, Serialize};
893    ///
894    /// #[derive(Serialize, Deserialize)]
895    /// struct Data { value: i32 }
896    ///
897    /// async fn handler(
898    ///     _event: serde_json::Value,
899    ///     ctx: durable::DurableContext,
900    /// ) -> Result<(), durable::BoxError> {
901    ///     let cb = ctx.create_callback::<Data>()
902    ///         .await?;
903    ///     println!("callback id: {}", cb.id());
904    ///     let _data = cb.result().await?;
905    ///     Ok(())
906    /// }
907    /// ```
908    pub fn id(&self) -> &str {
909        &self.id
910    }
911
912    /// Returns the callback result as a [`DurableFuture`].
913    ///
914    /// For settled callbacks (replay), the future resolves with the stored
915    /// outcome immediately. For pending callbacks (live), the future waits
916    /// for the external completion. It resolves in the same invocation when
917    /// a checkpoint response carries the completed callback; otherwise the
918    /// invocation suspends once no other SDK work can make progress.
919    ///
920    /// Because the return type is a [`DurableFuture`], a callback result
921    /// participates in the durable combinators
922    /// ([`try_join_all`](DurableContext::try_join_all),
923    /// [`join_all`](DurableContext::join_all),
924    /// [`select_ok`](DurableContext::select_ok),
925    /// [`race`](DurableContext::race)) exactly like any other durable
926    /// operation.
927    ///
928    /// Awaiting the future yields `Result<O, OperationError>`: an
929    /// [`OperationError`] is returned if the callback failed (timeout,
930    /// heartbeat timeout, or external failure), or if its payload could not
931    /// be decoded with a permanent failure
932    /// ([`CallbackErrorKind::DeserializationFailed`](crate::CallbackErrorKind::DeserializationFailed)),
933    /// whether the record was terminal when the callback was created or
934    /// settled while this future waited. Awaiting the result of a
935    /// pending callback on a task or thread that does not own the context
936    /// fails the execution with a context usage error.
937    ///
938    /// # Examples
939    ///
940    /// ```no_run
941    /// use aws_durable_execution_sdk as durable;
942    /// use serde::{Deserialize, Serialize};
943    ///
944    /// #[derive(Serialize, Deserialize)]
945    /// struct Payload { msg: String }
946    ///
947    /// async fn handler(
948    ///     _event: serde_json::Value,
949    ///     ctx: durable::DurableContext,
950    /// ) -> Result<String, durable::BoxError> {
951    ///     let cb = ctx.create_callback::<Payload>()
952    ///         .await?;
953    ///     let payload = cb.result().await?;
954    ///     Ok(payload.msg)
955    /// }
956    /// ```
957    pub fn result(self) -> DurableFuture<O> {
958        match self.state {
959            CallbackState::Settled(outcome) => DurableFuture::from_async(async move {
960                // Replay path: return the stored outcome directly.
961                outcome.unwrap_or_else(|| {
962                    Err(OperationError::from_kind(
963                        crate::error::OperationErrorKind::Callback(
964                            crate::error::CallbackError::new(
965                                crate::error::CallbackErrorKind::Internal,
966                                Some("settled callback had no outcome".into()),
967                            ),
968                        ),
969                    ))
970                })
971            }),
972            CallbackState::Pending {
973                ctx,
974                wire_id,
975                identity,
976                resolver,
977            } => Self::pending_result(ctx, wire_id, identity, resolver),
978        }
979    }
980
981    /// Waits for the callback result on its own SDK task, as `.spawn()` does
982    /// for other operations, and returns its handle. The SDK refreshes the
983    /// callback's status only after the handle is first polled. Dropping the
984    /// handle loses only the result: the wait keeps running until the
985    /// callback settles, until its scope closes, or until the invocation
986    /// ends, and dropping it does not count as the first poll. A stopped
987    /// wait stops at its next `.await`.
988    ///
989    /// For a settled callback (replay) it returns the same future as
990    /// [`result()`](Self::result), which resolves with the stored outcome
991    /// and starts no task. In both its settled and pending forms it returns
992    /// the same callback outcomes and errors as `result()`, a permanent
993    /// payload decode failure included.
994    ///
995    /// # Errors
996    ///
997    /// For a pending callback, the task runs on the invocation's runtime;
998    /// when the invocation coordinator was created without one, the returned
999    /// future resolves to an error. A settled callback needs no
1000    /// runtime. For a pending callback, a call on a task or thread that
1001    /// does not own the context fails the execution with a context usage
1002    /// error.
1003    ///
1004    /// # Examples
1005    ///
1006    /// ```no_run
1007    /// use aws_durable_execution_sdk as durable;
1008    ///
1009    /// async fn handler(
1010    ///     _event: serde_json::Value,
1011    ///     ctx: durable::DurableContext,
1012    /// ) -> Result<String, durable::BoxError> {
1013    ///     let cb = ctx.create_callback::<String>().name("approval").await?;
1014    ///     let approval = cb.spawn_result();
1015    ///     ctx.step(|_| async { Ok(()) }).name("other-work").await?;
1016    ///     Ok(approval.await?)
1017    /// }
1018    /// ```
1019    pub fn spawn_result(self) -> DurableFuture<O> {
1020        match self.state {
1021            CallbackState::Settled(_) => self.result(),
1022            CallbackState::Pending {
1023                ctx,
1024                wire_id,
1025                identity,
1026                resolver,
1027            } => {
1028                let flag = Arc::new(AtomicBool::new(false));
1029                let waiting = ctx.with_awaited(Arc::clone(&flag));
1030                // `pending_result` builds the future through `for_operation`,
1031                // so the task gets the creating context's frames and the span
1032                // current here. The capture point is this call, as for
1033                // `.spawn()`: it is where the user starts the waiting task.
1034                let future = Self::pending_result(waiting, wire_id, identity, resolver);
1035                DurableFuture::spawn_blessed(future, &ctx, Some(flag))
1036            }
1037        }
1038    }
1039
1040    /// The future of a pending callback's result. It waits until the record
1041    /// is terminal, then builds the outcome from it as creation-time replay
1042    /// does.
1043    ///
1044    /// The record becomes terminal while this future waits in the
1045    /// invocation. A `SUCCEEDED`, `FAILED`, `TIMED_OUT`, `STOPPED` or
1046    /// `CANCELLED` record therefore fires `on_operation_end` with
1047    /// `is_replay` false before the outcome is built.
1048    fn pending_result(
1049        ctx: DurableContext,
1050        wire_id: String,
1051        identity: CallbackIdentity,
1052        resolver: CallbackResolver<O>,
1053    ) -> DurableFuture<O> {
1054        let gate = ctx.clone();
1055        DurableFuture::for_operation(&gate, async move {
1056            // Execution entry: a task or thread that does not own the
1057            // context fails the execution. A settled result executes
1058            // nothing, so it is not checked.
1059            ctx.enforce_task_ownership()?;
1060            ctx.wait_for_record(&wire_id, |status| {
1061                !matches!(
1062                    status,
1063                    crate::engine::CheckpointStatus::Started
1064                        | crate::engine::CheckpointStatus::Pending
1065                )
1066            })
1067            .await;
1068            if let Some(plugins) = ctx.plugins() {
1069                let terminal = ctx
1070                    .with_checkpoint_record_by_wire(&wire_id, |record| {
1071                        crate::callback::is_terminal_callback_status(&record.status)
1072                    })
1073                    .unwrap_or(false);
1074                if terminal {
1075                    let info = crate::callback::callback_info(
1076                        &ctx,
1077                        &wire_id,
1078                        &identity.sub_type,
1079                        identity.name.as_deref(),
1080                        identity.plugin_name.as_deref(),
1081                    )
1082                    .with_replay(false);
1083                    crate::plugin::operation_ended(plugins, &info);
1084                }
1085            }
1086            resolver().await
1087        })
1088    }
1089}
1090
1091/// A set of parallel branches whose results have different types, for
1092/// [`DurableContext::parallel_mixed`].
1093///
1094/// Each [`add`](Self::add) or [`add_with_serdes`](Self::add_with_serdes)
1095/// call adds one branch and returns a [`BranchHandle`] typed with that
1096/// branch's result. Branches start, and are numbered, in the order they
1097/// were added. The number of branches is unlimited.
1098///
1099/// # Examples
1100///
1101/// ```no_run
1102/// use aws_durable_execution_sdk as durable;
1103/// use durable::BranchSet;
1104///
1105/// async fn handler(
1106///     _event: serde_json::Value,
1107///     ctx: durable::DurableContext,
1108/// ) -> Result<String, durable::BoxError> {
1109///     let mut branches = BranchSet::new();
1110///     let count = branches.add("count", |_ctx| async { Ok(7_u32) });
1111///     let label = branches.add("label", |_ctx| async { Ok("ready".to_owned()) });
1112///     ctx.parallel_mixed(branches).name("fan-out").await?;
1113///     Ok(format!("{}: {}", count.into_result()?, label.into_result()?))
1114/// }
1115/// ```
1116#[non_exhaustive]
1117pub struct BranchSet {
1118    /// Each branch's caller name and erased body, in the order added.
1119    branches: Vec<(Option<String>, BranchBody<BranchValue>)>,
1120    /// Each branch's decoder, at the branch's index.
1121    decoders: Vec<Arc<dyn BranchDecoder>>,
1122    /// Whether each branch uses the default JSON serdes, at its index.
1123    json: Vec<bool>,
1124    /// The set's identity, shared by every key and value of its branches.
1125    identity: Arc<SetIdentity>,
1126}
1127
1128/// The identity of one [`BranchSet`]: each set allocates its own, and two
1129/// identities are the same exactly when they are the same allocation.
1130struct SetIdentity;
1131
1132impl Default for BranchSet {
1133    fn default() -> Self {
1134        Self::new()
1135    }
1136}
1137
1138impl std::fmt::Debug for BranchSet {
1139    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1140        let names: Vec<&str> = self
1141            .branches
1142            .iter()
1143            .map(|(name, _)| name.as_deref().unwrap_or_default())
1144            .collect();
1145        f.debug_struct("BranchSet")
1146            .field("names", &names)
1147            .finish_non_exhaustive()
1148    }
1149}
1150
1151impl BranchSet {
1152    /// Creates an empty set.
1153    #[must_use]
1154    pub fn new() -> Self {
1155        Self {
1156            branches: Vec::new(),
1157            decoders: Vec::new(),
1158            json: Vec::new(),
1159            identity: Arc::new(SetIdentity),
1160        }
1161    }
1162
1163    /// Adds a branch whose result is encoded and decoded as JSON.
1164    ///
1165    /// This is [`add_with_serdes`](Self::add_with_serdes) with
1166    /// [`JsonSerdes`](crate::JsonSerdes). The batch record holds the
1167    /// branch's value as JSON, as [`DurableContext::parallel`] does with
1168    /// its default serdes.
1169    #[must_use]
1170    pub fn add<T, F, Fut>(&mut self, name: impl Into<String>, factory: F) -> BranchHandle<T>
1171    where
1172        T: serde::Serialize + serde::de::DeserializeOwned + Send + 'static,
1173        F: FnOnce(DurableContext) -> Fut + Send + 'static,
1174        Fut: Future<Output = Result<T, BoxError>> + Send + 'static,
1175    {
1176        self.insert(name.into(), crate::JsonSerdes, factory, true)
1177    }
1178
1179    /// Adds a branch whose result is encoded and decoded by `serdes`.
1180    ///
1181    /// `name` and `factory` have the same types as in [`Branch::new`].
1182    /// History records `name`, or `parallel-branch-{index}` when it is
1183    /// empty, and a completion predicate sees `Some(name)`. `serdes` must
1184    /// implement [`Serdes<T>`](crate::Serdes), so a serdes written for
1185    /// another type fails to compile. It is called wherever the item serdes
1186    /// of [`DurableContext::parallel`] is called for this branch, with the
1187    /// same [`SerdesContext`](crate::serdes::SerdesContext). To share one
1188    /// serdes across branches, pass a clone of one `Arc` to each call.
1189    ///
1190    /// # Examples
1191    ///
1192    /// ```no_run
1193    /// use std::sync::Arc;
1194    ///
1195    /// use aws_durable_execution_sdk as durable;
1196    /// use durable::serdes::{FileSystemSerdes, SerdesContext};
1197    /// use durable::{BoxError, BranchSet, Serdes};
1198    ///
1199    /// struct Order {
1200    ///     id: u64,
1201    /// }
1202    ///
1203    /// // A serdes for `Order` only: attaching it to a branch of another
1204    /// // type fails to compile.
1205    /// struct OrderSerdes;
1206    ///
1207    /// impl Serdes<Order> for OrderSerdes {
1208    ///     async fn serialize(&self, value: Order, _ctx: SerdesContext) -> Result<String, BoxError> {
1209    ///         Ok(value.id.to_string())
1210    ///     }
1211    ///     async fn deserialize(&self, wire: String, _ctx: SerdesContext) -> Result<Order, BoxError> {
1212    ///         Ok(Order { id: wire.parse()? })
1213    ///     }
1214    /// }
1215    ///
1216    /// async fn handler(
1217    ///     _event: serde_json::Value,
1218    ///     ctx: durable::DurableContext,
1219    /// ) -> Result<u64, durable::BoxError> {
1220    ///     let files = Arc::new(FileSystemSerdes::new("/mnt/efs"));
1221    ///     let mut branches = BranchSet::new();
1222    ///     let order = branches.add_with_serdes("order", OrderSerdes, |_ctx| async {
1223    ///         Ok(Order { id: 42 })
1224    ///     });
1225    ///     let report = branches.add_with_serdes("report", Arc::clone(&files), |_ctx| async {
1226    ///         Ok("a large report".to_owned())
1227    ///     });
1228    ///     ctx.parallel_mixed(branches).name("process-order").await?;
1229    ///     let order = order.into_result()?;
1230    ///     let _report: String = report.into_result()?;
1231    ///     Ok(order.id)
1232    /// }
1233    /// ```
1234    #[must_use]
1235    pub fn add_with_serdes<T, S, F, Fut>(
1236        &mut self,
1237        name: impl Into<String>,
1238        serdes: S,
1239        factory: F,
1240    ) -> BranchHandle<T>
1241    where
1242        T: Send + 'static,
1243        S: crate::Serdes<T> + 'static,
1244        F: FnOnce(DurableContext) -> Fut + Send + 'static,
1245        Fut: Future<Output = Result<T, BoxError>> + Send + 'static,
1246    {
1247        self.insert(name.into(), serdes, factory, false)
1248    }
1249
1250    /// Adds one branch (internal). `json` is `true` when the batch record
1251    /// holds the branch's value as JSON.
1252    fn insert<T, S, F, Fut>(
1253        &mut self,
1254        name: String,
1255        serdes: S,
1256        factory: F,
1257        json: bool,
1258    ) -> BranchHandle<T>
1259    where
1260        T: Send + 'static,
1261        S: crate::Serdes<T> + 'static,
1262        F: FnOnce(DurableContext) -> Fut + Send + 'static,
1263        Fut: Future<Output = Result<T, BoxError>> + Send + 'static,
1264    {
1265        let index = self.branches.len();
1266        let record_name = if name.is_empty() {
1267            format!("parallel-branch-{index}")
1268        } else {
1269            name.clone()
1270        };
1271        let key = BranchKey {
1272            identity: Arc::clone(&self.identity),
1273            index,
1274            _marker: PhantomData,
1275        };
1276        let slot: BranchSlot<T> = Arc::new(std::sync::Mutex::new(None));
1277        let serdes = Arc::new(serdes);
1278        let decoder = BranchShared {
1279            serdes: Arc::clone(&serdes),
1280            slot: Arc::clone(&slot),
1281            identity: Arc::clone(&self.identity),
1282            index,
1283        };
1284        let body_slot = Arc::clone(&slot);
1285        let body_identity = Arc::clone(&self.identity);
1286        let branch = Branch::new(name, move |ctx: DurableContext| async move {
1287            let value = factory(ctx).await?;
1288            Ok(BranchValue {
1289                value: Box::new(TypedBranchValue {
1290                    value,
1291                    serdes,
1292                    slot: body_slot,
1293                }),
1294                identity: body_identity,
1295                index,
1296            })
1297        });
1298        self.branches.push(branch.into_parts());
1299        self.decoders.push(Arc::new(decoder));
1300        self.json.push(json);
1301        BranchHandle {
1302            name: record_name,
1303            slot,
1304            key,
1305        }
1306    }
1307
1308    /// Consumes the set and returns each branch's caller name and body,
1309    /// the decoders and the JSON flags, all in branch order (internal).
1310    #[expect(clippy::type_complexity)]
1311    // reason: the three parts go to three different places, and a named type for each would add nothing
1312    pub(crate) fn into_parts(
1313        self,
1314    ) -> (
1315        Vec<(Option<String>, BranchBody<BranchValue>)>,
1316        Arc<Vec<Arc<dyn BranchDecoder>>>,
1317        Arc<[bool]>,
1318    ) {
1319        (self.branches, Arc::new(self.decoders), Arc::from(self.json))
1320    }
1321}
1322
1323/// The result of one branch of a [`BranchSet`].
1324///
1325/// [`into_result`](Self::into_result) returns the branch's result once the
1326/// `.await` of the [`DurableContext::parallel_mixed`] that ran the set has
1327/// returned, or the `.await` of the future its `.spawn()` returned. Before
1328/// that, the handle has no result, even when its branch
1329/// has finished, so what a handle returns never depends on timing. Dropping
1330/// a handle does not cancel or skip its branch.
1331#[non_exhaustive]
1332pub struct BranchHandle<T> {
1333    /// The name history records for the branch.
1334    name: String,
1335    /// Shared with the branch: filled when the parallel's `.await` returns.
1336    slot: BranchSlot<T>,
1337    /// The branch's key.
1338    key: BranchKey<T>,
1339}
1340
1341impl<T> std::fmt::Debug for BranchHandle<T> {
1342    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1343        let has_result = lock_slot(&self.slot).is_some();
1344        f.debug_struct("BranchHandle")
1345            .field("name", &self.name)
1346            .field("has_result", &has_result)
1347            .finish_non_exhaustive()
1348    }
1349}
1350
1351impl<T> BranchHandle<T> {
1352    /// Returns the key that reads this branch's value from the
1353    /// [`BatchResult`](crate::builders::map_parallel::BatchResult) a
1354    /// [`ParallelMixedBuilder::summary`](crate::builders::ParallelMixedBuilder::summary)
1355    /// receives, with
1356    /// [`BatchResult::value`](crate::builders::map_parallel::BatchResult::value).
1357    ///
1358    /// Every call returns a key of the same branch.
1359    #[must_use]
1360    pub fn key(&self) -> BranchKey<T> {
1361        self.key.clone()
1362    }
1363
1364    /// Returns the branch's result, without waiting.
1365    ///
1366    /// - `Ok(value)` when the branch succeeded. `value` is what the
1367    ///   branch's serdes decoded, so the first run and replay return the
1368    ///   same value.
1369    /// - The branch's own error when the branch failed: a
1370    ///   [`ChildContextError`](crate::ChildContextError) of kind
1371    ///   [`ChildFailed`](crate::ChildContextErrorKind::ChildFailed) that
1372    ///   holds the recorded failure, the error `parallel(...).await`
1373    ///   returns when a failed item ends the batch.
1374    ///
1375    /// # Errors
1376    ///
1377    /// Besides the branch's own error, returns an error of kind
1378    /// [`NotCompleted`](crate::ChildContextErrorKind::NotCompleted), whose
1379    /// message names the branch, when the handle has no result: the
1380    /// parallel has not returned, it returned an error of its own, the
1381    /// branch never started, or the batch completed while the branch still
1382    /// ran.
1383    pub fn into_result(self) -> Result<T, OperationError> {
1384        let taken = lock_slot(&self.slot).take();
1385        taken.unwrap_or_else(|| Err(not_completed_error(&self.name)))
1386    }
1387}
1388
1389/// The slot a [`BranchHandle`] shares with its branch.
1390type BranchSlot<T> = Arc<std::sync::Mutex<Option<Result<T, OperationError>>>>;
1391
1392/// Locks a branch slot. A poisoned lock still holds a valid slot value.
1393fn lock_slot<T>(
1394    slot: &std::sync::Mutex<Option<Result<T, OperationError>>>,
1395) -> std::sync::MutexGuard<'_, Option<Result<T, OperationError>>> {
1396    slot.lock()
1397        .unwrap_or_else(std::sync::PoisonError::into_inner)
1398}
1399
1400/// The error of a [`BranchHandle`] that has no result.
1401fn not_completed_error(name: &str) -> OperationError {
1402    OperationError::from_kind(crate::OperationErrorKind::ChildContext(
1403        crate::error::ChildContextError::new(
1404            crate::ChildContextErrorKind::NotCompleted,
1405            Some(format!("parallel branch \"{name}\" has no result").into()),
1406        ),
1407    ))
1408}
1409
1410/// The value of one branch of a [`BranchSet`], with its type erased: the
1411/// item type of the [`BatchResult`](crate::builders::map_parallel::BatchResult) that a
1412/// [`ParallelMixedBuilder::summary`](crate::builders::ParallelMixedBuilder::summary)
1413/// receives.
1414///
1415/// A `BranchValue` exposes nothing of its value. Read the value with
1416/// [`BatchResult::value`](crate::builders::map_parallel::BatchResult::value) and the key that
1417/// [`BranchHandle::key`] returns. Its `Debug` text is `BranchValue { .. }`.
1418pub struct BranchValue {
1419    /// The value, with its serdes and its handle's slot.
1420    value: Box<dyn ErasedBranchValue>,
1421    /// The identity of the set the branch belongs to.
1422    identity: Arc<SetIdentity>,
1423    /// The branch's index in its set.
1424    index: usize,
1425}
1426
1427impl std::fmt::Debug for BranchValue {
1428    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1429        f.debug_struct("BranchValue").finish_non_exhaustive()
1430    }
1431}
1432
1433impl BranchValue {
1434    /// Encodes the value with its branch's serdes (internal).
1435    pub(crate) fn encode(
1436        self,
1437        ctx: crate::serdes::SerdesContext,
1438    ) -> Pin<Box<dyn Future<Output = Result<String, BoxError>> + Send>> {
1439        self.value.encode(ctx)
1440    }
1441
1442    /// Stores `Ok(value)` in the branch handle's slot (internal).
1443    pub(crate) fn publish(self) {
1444        self.value.publish();
1445    }
1446
1447    /// Returns the value when it belongs to `key`'s branch (internal).
1448    pub(crate) fn of_branch<T: 'static>(&self, key: &BranchKey<T>) -> Option<&T> {
1449        if !Arc::ptr_eq(&self.identity, &key.identity) || self.index != key.index {
1450            return None;
1451        }
1452        #[expect(clippy::expect_used)]
1453        // reason: the set and the index name one branch, and that branch's
1454        // body and decoder produce only values of the type of its key
1455        let value = self
1456            .value
1457            .value()
1458            .downcast_ref::<T>()
1459            .expect("a branch's key has the type of the branch's values");
1460        Some(value)
1461    }
1462}
1463
1464/// The key of one branch of a [`BranchSet`], which reads the branch's value
1465/// from a [`BatchResult<BranchValue>`](crate::builders::map_parallel::BatchResult) with
1466/// [`BatchResult::value`](crate::builders::map_parallel::BatchResult::value).
1467///
1468/// [`BranchHandle::key`] returns it. A key reads only values of its own
1469/// branch: a key from another set returns `None`. It is `Clone`, `Send`
1470/// and `Sync` for every branch type, and holds no value of type `T`.
1471///
1472/// A key's type is exactly its branch's type. Subtyping cannot turn a key
1473/// of one type into a key of another, so a key never reads a value as a
1474/// type the branch did not produce:
1475///
1476/// ```compile_fail,E0308
1477/// use aws_durable_execution_sdk::BranchKey;
1478///
1479/// fn coerce(key: BranchKey<for<'a> fn(&'a ())>) -> BranchKey<fn(&'static ())> {
1480///     key
1481/// }
1482/// ```
1483pub struct BranchKey<T> {
1484    /// The identity of the set the branch belongs to.
1485    identity: Arc<SetIdentity>,
1486    /// The branch's index in its set.
1487    index: usize,
1488    /// The branch's type, without owning a `T`. `fn(T) -> T` makes the key
1489    /// invariant in `T`, so subtyping cannot change the type it reads.
1490    _marker: PhantomData<fn(T) -> T>,
1491}
1492
1493impl<T> BranchKey<T> {
1494    /// The branch's index in its set (internal).
1495    pub(crate) fn index(&self) -> usize {
1496        self.index
1497    }
1498}
1499
1500impl<T> Clone for BranchKey<T> {
1501    fn clone(&self) -> Self {
1502        Self {
1503            identity: Arc::clone(&self.identity),
1504            index: self.index,
1505            _marker: PhantomData,
1506        }
1507    }
1508}
1509
1510impl<T> std::fmt::Debug for BranchKey<T> {
1511    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1512        f.debug_struct("BranchKey")
1513            .field("index", &self.index)
1514            .finish_non_exhaustive()
1515    }
1516}
1517
1518/// A branch value whose type is erased (crate-internal).
1519pub(crate) trait ErasedBranchValue: Send {
1520    /// Encodes the value with the branch's serdes.
1521    fn encode(
1522        self: Box<Self>,
1523        ctx: crate::serdes::SerdesContext,
1524    ) -> Pin<Box<dyn Future<Output = Result<String, BoxError>> + Send>>;
1525    /// Stores `Ok(value)` in the branch handle's slot.
1526    fn publish(self: Box<Self>);
1527    /// Returns the value.
1528    fn value(&self) -> &dyn std::any::Any;
1529}
1530
1531/// Decodes the values of one branch and fails its handle (crate-internal).
1532pub(crate) trait BranchDecoder: Send + Sync {
1533    /// Decodes a wire string with the branch's serdes.
1534    fn decode(
1535        &self,
1536        wire: String,
1537        ctx: crate::serdes::SerdesContext,
1538    ) -> Pin<Box<dyn Future<Output = Result<BranchValue, BoxError>> + Send + '_>>;
1539    /// Stores `Err(err)` in the branch handle's slot.
1540    fn publish_error(&self, err: OperationError);
1541}
1542
1543/// A branch's value with its serdes and its handle's slot.
1544struct TypedBranchValue<T, S> {
1545    value: T,
1546    serdes: Arc<S>,
1547    slot: BranchSlot<T>,
1548}
1549
1550impl<T, S> ErasedBranchValue for TypedBranchValue<T, S>
1551where
1552    T: Send + 'static,
1553    S: crate::Serdes<T>,
1554{
1555    fn encode(
1556        self: Box<Self>,
1557        ctx: crate::serdes::SerdesContext,
1558    ) -> Pin<Box<dyn Future<Output = Result<String, BoxError>> + Send>> {
1559        let Self { value, serdes, .. } = *self;
1560        Box::pin(async move { serdes.serialize(value, ctx).await })
1561    }
1562
1563    fn publish(self: Box<Self>) {
1564        let Self { value, slot, .. } = *self;
1565        *lock_slot(&slot) = Some(Ok(value));
1566    }
1567
1568    fn value(&self) -> &dyn std::any::Any {
1569        &self.value
1570    }
1571}
1572
1573/// One branch's serdes, handle slot, set identity and index: the branch's
1574/// [`BranchDecoder`].
1575struct BranchShared<T, S> {
1576    serdes: Arc<S>,
1577    slot: BranchSlot<T>,
1578    identity: Arc<SetIdentity>,
1579    index: usize,
1580}
1581
1582impl<T, S> BranchDecoder for BranchShared<T, S>
1583where
1584    T: Send + 'static,
1585    S: crate::Serdes<T>,
1586{
1587    fn decode(
1588        &self,
1589        wire: String,
1590        ctx: crate::serdes::SerdesContext,
1591    ) -> Pin<Box<dyn Future<Output = Result<BranchValue, BoxError>> + Send + '_>> {
1592        Box::pin(async move {
1593            let value = self.serdes.deserialize(wire, ctx).await?;
1594            Ok(BranchValue {
1595                value: Box::new(TypedBranchValue {
1596                    value,
1597                    serdes: Arc::clone(&self.serdes),
1598                    slot: Arc::clone(&self.slot),
1599                }),
1600                identity: Arc::clone(&self.identity),
1601                index: self.index,
1602            })
1603        })
1604    }
1605
1606    fn publish_error(&self, err: OperationError) {
1607        *lock_slot(&self.slot) = Some(Err(err));
1608    }
1609}
1610
1611#[cfg(test)]
1612#[expect(clippy::panic)]
1613// reason: test assertions
1614// Tests deliberately spawn foreign (unblessed) tasks to exercise runtime
1615// behavior; production spawning is confined to the src/task.rs gateway.
1616#[expect(clippy::disallowed_methods)]
1617mod tests {
1618    use super::*;
1619    use crate::engine::CheckpointLog;
1620    use std::sync::Arc;
1621    use std::sync::atomic::{AtomicBool, Ordering};
1622
1623    fn test_ctx_with_client() -> DurableContext {
1624        let client = Arc::new(crate::client::InMemoryExecutionClient::new(Vec::new()));
1625        DurableContext::new_root_with_client(
1626            "test-function-arn".to_owned(),
1627            lambda_runtime::Context::default(),
1628            Arc::new(CheckpointLog::empty()),
1629            client,
1630            "token0".to_owned(),
1631        )
1632    }
1633
1634    use std::future::IntoFuture as _;
1635
1636    thread_local! {
1637        /// The wraps of [`Tag`] plugins entered on this thread, outermost
1638        /// first.
1639        static TAGS: std::cell::RefCell<Vec<String>> = const { std::cell::RefCell::new(Vec::new()) };
1640        /// Each user-function wrap entered on this thread: its tag and the
1641        /// tags entered around it.
1642        static ENTERED: std::cell::RefCell<Vec<(String, Vec<String>)>> = const { std::cell::RefCell::new(Vec::new()) };
1643    }
1644
1645    fn current_tags() -> Vec<String> {
1646        TAGS.with(|tags| tags.borrow().clone())
1647    }
1648
1649    /// A plugin whose wraps record `inv`, or the user function's name (its
1650    /// ID without one), while they are entered.
1651    struct Tag;
1652
1653    impl Tag {
1654        fn wrap(site: &str, next: &mut dyn FnMut()) {
1655            TAGS.with(|tags| tags.borrow_mut().push(site.to_owned()));
1656            next();
1657            TAGS.with(|tags| tags.borrow_mut().pop());
1658        }
1659    }
1660
1661    impl crate::plugin::Plugin for Tag {
1662        fn wrap_invocation(&self, _info: &crate::plugin::InvocationInfo, next: &mut dyn FnMut()) {
1663            Self::wrap("inv", next);
1664        }
1665
1666        fn wrap_user_function(&self, info: &crate::plugin::OperationInfo, next: &mut dyn FnMut()) {
1667            let site = info.name().unwrap_or(info.id());
1668            ENTERED.with(|entered| {
1669                entered.borrow_mut().push((site.to_owned(), current_tags()));
1670            });
1671            Self::wrap(site, next);
1672        }
1673    }
1674
1675    impl crate::plugin::PluginFactory for Tag {
1676        fn create_plugin(
1677            &self,
1678            _info: &crate::plugin::InvocationInfo,
1679        ) -> Result<Option<Box<dyn crate::plugin::Plugin>>, BoxError> {
1680            Ok(Some(Box::new(Tag)))
1681        }
1682    }
1683
1684    /// A root context over the in-memory transport whose one plugin is a
1685    /// [`Tag`], and its invocation frames.
1686    fn tagged_ctx() -> (DurableContext, crate::plugin::Frames) {
1687        let factory: Arc<dyn crate::plugin::PluginFactory> = Arc::new(Tag);
1688        let plugins = crate::plugin::create_plugins(
1689            &[("Tag", factory)],
1690            None,
1691            crate::plugin::tests_support_info,
1692        )
1693        .expect("a factory was given");
1694        let ctx = DurableContext::new_root_with_client_and_defaults(
1695            "test-function-arn".to_owned(),
1696            lambda_runtime::Context::default(),
1697            Arc::new(CheckpointLog::empty()),
1698            Arc::new(crate::client::InMemoryExecutionClient::new(Vec::new())),
1699            "token0".to_owned(),
1700            std::time::Duration::ZERO,
1701            0,
1702            Some(Arc::clone(&plugins)),
1703        );
1704        (ctx, crate::plugin::Frames::invocation(Some(plugins)))
1705    }
1706
1707    /// What a step body saw: its name and the wraps entered at its call.
1708    type Seen = Arc<std::sync::Mutex<Vec<(&'static str, Vec<String>)>>>;
1709
1710    /// A step body that records what it saw in `seen`, then returns
1711    /// `value`.
1712    fn recording(
1713        seen: &Seen,
1714        name: &'static str,
1715        value: u32,
1716    ) -> impl FnOnce(crate::StepContext) -> std::future::Ready<Result<u32, BoxError>>
1717    + Clone
1718    + Send
1719    + 'static {
1720        let seen = Arc::clone(seen);
1721        move |_| {
1722            seen.lock().unwrap().push((name, current_tags()));
1723            std::future::ready(Ok(value))
1724        }
1725    }
1726
1727    /// Rule 5.4: in A (child `a`, span `A`) a step future is made and
1728    /// mapped, and so is an unclaimed `try_join_all` of two steps. The
1729    /// mapped step keeps A. Mapping claims no ID; the combinator claims the
1730    /// next positional ID in B (child `b`, span `B`), by its first poll, then
1731    /// by what `.spawn()` does; and its task context is B's. Each path
1732    /// yields its inputs' mapped result; the join runs in `[I, b, join]`,
1733    /// and each input's body in the frames it captured in A.
1734    #[test]
1735    fn map_output_keeps_task_context_and_pending_claim() {
1736        let subscriber = lambda_runtime::tracing::subscriber::registry();
1737        {
1738            let _guard = test_tracing::install_test_subscriber(subscriber);
1739            let runtime = tokio::runtime::Builder::new_current_thread()
1740                .build()
1741                .expect("runtime");
1742            let _guard = runtime.enter();
1743            let span_a = tracing::info_span!("A");
1744            let span_b = tracing::info_span!("B");
1745            assert!(span_a.id().is_some() && span_b.id().is_some());
1746            for spawned in [false, true] {
1747                let (ctx, inv) = tagged_ctx();
1748                let frames_a =
1749                    inv.with_user_function(Arc::new(crate::plugin::OperationInfo::for_test("a")));
1750                let frames_b =
1751                    inv.with_user_function(Arc::new(crate::plugin::OperationInfo::for_test("b")));
1752                let seen: Seen = Arc::default();
1753                let (step, mut join) = span_a.in_scope(|| {
1754                    frames_a.enter(|| {
1755                        let step = ctx
1756                            .step(recording(&seen, "solo", 1))
1757                            .name("solo")
1758                            .future()
1759                            .map_output(|r| r.map(|v| v + 1));
1760                        let s1 = ctx.step(recording(&seen, "s1", 1)).name("s1").future();
1761                        let s2 = ctx.step(recording(&seen, "s2", 2)).name("s2").future();
1762                        let join = ctx
1763                            .try_join_all([s1, s2])
1764                            .name("join")
1765                            .into_future()
1766                            .map_output(|r| r.map(|v| v.iter().sum::<u32>() * 10));
1767                        (step, join)
1768                    })
1769                });
1770                // The mapped step keeps A.
1771                assert_eq!(
1772                    step.task_context().frames().enter(current_tags),
1773                    ["inv", "a"],
1774                    "spawned: {spawned}"
1775                );
1776                assert_eq!(step.task_context().span().id(), span_a.id());
1777                // The claim is kept, and mapping claimed nothing: the steps
1778                // took 1 to 3, so the probe takes 4.
1779                assert!(join.is_unclaimed_combinator(), "spawned: {spawned}");
1780                assert_eq!(ctx.mint_id().positional(), "4", "spawned: {spawned}");
1781                span_b.in_scope(|| {
1782                    frames_b.enter(|| {
1783                        if spawned {
1784                            // What `.spawn()` does: claim, then start the task.
1785                            join.claim_now();
1786                        } else {
1787                            // The first poll claims.
1788                            let waker = std::task::Waker::noop();
1789                            let mut cx = Context::from_waker(waker);
1790                            drop(Pin::new(&mut join).poll(&mut cx));
1791                        }
1792                    });
1793                });
1794                assert!(!join.is_unclaimed_combinator(), "spawned: {spawned}");
1795                // The combinator claimed 5, the ID after the probe's 4.
1796                assert_eq!(ctx.mint_id().positional(), "6", "spawned: {spawned}");
1797                assert_eq!(
1798                    join.task_context().frames().enter(current_tags),
1799                    ["inv", "b"],
1800                    "the claim captured B's frames; spawned: {spawned}"
1801                );
1802                assert_eq!(join.task_context().span().id(), span_b.id());
1803                let step = DurableFuture::spawn_blessed(step, &ctx, None);
1804                assert_eq!(runtime.block_on(step).expect("the step succeeds"), 2);
1805                let join = DurableFuture::spawn_blessed(join, &ctx, None);
1806                assert_eq!(runtime.block_on(join).expect("the join succeeds"), 30);
1807                let mut seen = std::mem::take(&mut *seen.lock().unwrap());
1808                seen.sort_by_key(|(name, _)| *name);
1809                let tags = |list: &[&str]| -> Vec<String> {
1810                    list.iter().map(|tag| (*tag).to_owned()).collect()
1811                };
1812                // Each input's body runs on its own task, in the frames it
1813                // captured in A.
1814                assert_eq!(
1815                    seen,
1816                    [
1817                        ("s1", tags(&["inv", "a", "s1"])),
1818                        ("s2", tags(&["inv", "a", "s2"])),
1819                        ("solo", tags(&["inv", "a", "solo"])),
1820                    ],
1821                    "spawned: {spawned}"
1822                );
1823                // The join's node sits above B: its wrap is entered inside
1824                // B's frames, so the join runs in `[I, b, join]`.
1825                let entered = ENTERED.with(|entered| std::mem::take(&mut *entered.borrow_mut()));
1826                let joins: Vec<_> = entered.iter().filter(|(site, _)| site == "join").collect();
1827                assert!(!joins.is_empty(), "the join ran as a user function");
1828                assert!(
1829                    joins
1830                        .iter()
1831                        .all(|(_, around)| *around == tags(&["inv", "b"])),
1832                    "{entered:?}; spawned: {spawned}"
1833                );
1834            }
1835        };
1836    }
1837
1838    /// r7 item 5: a `parallel_mixed` future keeps the task context of its
1839    /// batch, so a task that runs it runs inside the span and frames of its
1840    /// creation.
1841    #[test]
1842    fn parallel_mixed_keeps_the_task_context_of_its_creation() {
1843        let subscriber = lambda_runtime::tracing::subscriber::registry();
1844        {
1845            let _guard = test_tracing::install_test_subscriber(subscriber);
1846            let runtime = tokio::runtime::Builder::new_current_thread()
1847                .build()
1848                .expect("runtime");
1849            let _guard = runtime.enter();
1850            let ctx = test_ctx_with_client();
1851            let span = tracing::info_span!("creation");
1852            let mixed = span.in_scope(|| {
1853                let mut set = BranchSet::new();
1854                let _handle = set.add("b", |_c| async { Ok(1_u32) });
1855                ctx.parallel_mixed(set).into_future()
1856            });
1857            assert!(span.id().is_some());
1858            assert_eq!(mixed.task_context().span().id(), span.id());
1859            let plain = span.in_scope(|| ctx.step(|_| async { Ok(1_u32) }).future());
1860            let mapped = plain.map_output(|r| r.map(|v| v + 1));
1861            assert_eq!(mapped.task_context().span().id(), span.id());
1862        };
1863    }
1864
1865    /// Tokio may give a new task the ID of a task that exited, and the
1866    /// exited task's blessing is gone. So a raw task whose ID matches a
1867    /// poller that passed earlier must still be refused: the gate checks
1868    /// ownership on every poll. The test gives one task the identity the
1869    /// gate admitted: it blesses the task, passes the gate, then removes
1870    /// the blessing, as the task gateway does when a blessed task exits,
1871    /// and polls the same gate again with that task ID. A gate that cached
1872    /// the ID of its last passing poller would admit the second poll.
1873    #[test]
1874    fn poll_gate_refuses_raw_task_with_reused_identity() {
1875        let ctx = test_ctx_with_client();
1876        let mut gate = PollGate::new(&ctx);
1877        let ownership = Arc::clone(ctx.task_ownership());
1878        let runtime = tokio::runtime::Builder::new_current_thread()
1879            .build()
1880            .unwrap();
1881        let (first, second) = runtime
1882            .block_on(async move {
1883                tokio::spawn(async move {
1884                    let id = tokio::task::id();
1885                    ownership.bless_task(id);
1886                    let first = gate.admit().is_ok();
1887                    ownership.unbless_task(id);
1888                    let second = gate.admit().is_ok();
1889                    (first, second)
1890                })
1891                .await
1892            })
1893            .unwrap();
1894        assert!(first, "the blessed task was refused");
1895        assert!(!second, "a raw task with a reused task ID was admitted");
1896        let fatal = ctx.coordinator().fatal_error().expect("fatal recorded");
1897        assert_eq!(
1898            fatal.error_message,
1899            crate::context::foreign_caller_message("execute")
1900        );
1901    }
1902
1903    /// Test 16: a combinator future claims one ID however often
1904    /// `claim_now` runs, and its first poll after a claim claims nothing.
1905    #[tokio::test]
1906    async fn claim_now_claims_once() {
1907        let ctx = test_ctx_with_client();
1908        let mut all = ctx.try_join_all(Vec::<DurableFuture<i32>>::new()).future();
1909        assert!(all.is_unclaimed_combinator());
1910        all.claim_now();
1911        assert!(!all.is_unclaimed_combinator());
1912        all.claim_now();
1913        assert_eq!(
1914            all.await.expect("an empty join succeeds"),
1915            Vec::<i32>::new()
1916        );
1917        assert_eq!(
1918            ctx.mint_id().positional(),
1919            "2",
1920            "the combinator claimed 1 only"
1921        );
1922    }
1923
1924    /// Test 17: a step's future carries no pending claim.
1925    #[tokio::test]
1926    async fn claim_now_is_noop_for_non_combinator() {
1927        let ctx = test_ctx_with_client();
1928        let mut step = ctx.step(|_| async { Ok(1_i32) }).future();
1929        assert!(!step.is_unclaimed_combinator());
1930        assert_eq!(step.unclaimed_input_message("9"), None);
1931        step.claim_now();
1932        assert_eq!(ctx.mint_id().positional(), "2", "only the step claimed");
1933        assert_eq!(step.await.expect("the step succeeds"), 1);
1934    }
1935
1936    /// A panic inside a `.spawn()`ed operation body must surface to the
1937    /// awaiter as the ORIGINAL panic (payload intact), exactly like the lazy
1938    /// path, not as a fabricated "spawned task was cancelled" step error.
1939    #[tokio::test]
1940    async fn spawned_panic_propagates_original_payload() {
1941        let ctx = test_ctx_with_client();
1942        let fut: DurableFuture<i32> = ctx.step(|_| async { panic!("kaboom-spawn") }).spawn();
1943
1944        // Await on a dedicated task so the re-raised panic is observable as
1945        // a JoinError instead of unwinding the test itself.
1946        let join_err = tokio::spawn(fut).await.unwrap_err();
1947        assert!(join_err.is_panic(), "panic must stay a panic: {join_err}");
1948        let payload = join_err.into_panic();
1949        let msg = payload
1950            .downcast_ref::<&str>()
1951            .map(|s| (*s).to_owned())
1952            .or_else(|| payload.downcast_ref::<String>().cloned())
1953            .unwrap_or_default();
1954        assert!(
1955            msg.contains("kaboom-spawn"),
1956            "original panic payload must be preserved, got: {msg}"
1957        );
1958    }
1959
1960    /// A context created outside every runtime has no invocation runtime.
1961    /// `spawn_started` called later inside a current-thread runtime still
1962    /// refuses: `start` is not called, and the handle resolves to the
1963    /// no-runtime error.
1964    #[test]
1965    fn spawn_started_with_current_runtime_but_no_invocation_runtime_does_not_start() {
1966        let ctx = test_ctx_with_client();
1967        let runtime = tokio::runtime::Builder::new_current_thread()
1968            .enable_all()
1969            .build()
1970            .expect("a runtime builds");
1971        let started = Arc::new(AtomicBool::new(false));
1972        let flag = Arc::clone(&started);
1973        let error = runtime.block_on(async move {
1974            let handle: DurableFuture<u32> = DurableFuture::spawn_started(&ctx, None, move || {
1975                flag.store(true, Ordering::SeqCst);
1976                DurableFuture::from_async(async { Ok(1_u32) })
1977            });
1978            handle.await.expect_err("no invocation runtime").to_string()
1979        });
1980        assert!(!started.load(Ordering::SeqCst), "start must not be called");
1981        let expected = crate::task::NoRuntime::operation_error(crate::task::NoRuntime).to_string();
1982        assert_eq!(error, expected);
1983    }
1984
1985    /// `.spawn()` on a thread with no Tokio runtime resolves to the error
1986    /// the task-ownership check would return, records nothing, and never
1987    /// runs the body.
1988    #[tokio::test]
1989    async fn spawn_outside_runtime_returns_error() {
1990        let client = Arc::new(crate::client::InMemoryExecutionClient::new(Vec::new()));
1991        let ran = Arc::new(AtomicBool::new(false));
1992        let thread_client = Arc::clone(&client);
1993        let thread_ran = Arc::clone(&ran);
1994        // The context is built on the polling thread, so that thread owns it.
1995        let polled = crate::task::test_support::poll_once_without_runtime(move || {
1996            DurableContext::new_root_with_client(
1997                "arn:aws:lambda:us-east-1:1:function:test".to_owned(),
1998                lambda_runtime::Context::default(),
1999                Arc::new(CheckpointLog::empty()),
2000                thread_client as Arc<dyn crate::client::ExecutionClient>,
2001                "token0".to_owned(),
2002            )
2003            .step(move |_| async move {
2004                thread_ran.store(true, Ordering::SeqCst);
2005                Ok(1_i32)
2006            })
2007            .spawn()
2008        });
2009        let Poll::Ready(Err(err)) = polled else {
2010            panic!("expected an immediate error, got {polled:?}");
2011        };
2012        let crate::error::OperationErrorKind::Step(step_err) = err.kind() else {
2013            panic!(
2014                "expected the task-ownership error kind, got {:?}",
2015                err.kind()
2016            );
2017        };
2018        assert!(matches!(
2019            step_err.kind(),
2020            crate::error::StepErrorKind::ExecutionFailed
2021        ));
2022        assert!(
2023            format!("{err:#}").contains(crate::task::NO_RUNTIME_MESSAGE),
2024            "unexpected error: {err:#}"
2025        );
2026        assert!(!ran.load(Ordering::SeqCst), "the body must not run");
2027        assert!(client.recorded_updates().is_empty(), "nothing is recorded");
2028    }
2029
2030    /// Dropping the handle of a `.spawn()`ed operation does not cancel the
2031    /// spawned task: the body keeps running. The task stops, without
2032    /// unwinding anything into the caller, when the tracker aborts it.
2033    #[tokio::test]
2034    async fn dropped_spawned_future_keeps_task_running_without_panic() {
2035        #[derive(Clone)]
2036        struct DropGuard(Arc<AtomicBool>);
2037        impl Drop for DropGuard {
2038            fn drop(&mut self) {
2039                self.0.store(true, Ordering::SeqCst);
2040            }
2041        }
2042
2043        let ctx = test_ctx_with_client();
2044        let dropped = Arc::new(AtomicBool::new(false));
2045        let started = Arc::new(AtomicBool::new(false));
2046        // The guard lives in the closure environment, so the body and the
2047        // guard drop together.
2048        let guard = DropGuard(Arc::clone(&dropped));
2049        let body_started = Arc::clone(&started);
2050
2051        let fut: DurableFuture<i32> = ctx
2052            .step(move |_| async move {
2053                let _guard = guard;
2054                body_started.store(true, Ordering::SeqCst);
2055                std::future::pending::<()>().await;
2056                Ok(0)
2057            })
2058            .spawn();
2059        drop(fut);
2060
2061        for _ in 0..50 {
2062            if started.load(Ordering::SeqCst) {
2063                break;
2064            }
2065            tokio::time::sleep(std::time::Duration::from_millis(10)).await;
2066        }
2067        assert!(
2068            started.load(Ordering::SeqCst),
2069            "the body runs after the drop"
2070        );
2071        assert!(
2072            !dropped.load(Ordering::SeqCst),
2073            "the dropped handle does not cancel the body"
2074        );
2075        let tasks = Arc::clone(ctx.coordinator().tasks());
2076        tasks.abort_all();
2077        tasks.wait_idle().await;
2078        assert!(dropped.load(Ordering::SeqCst), "abort_all cancels the body");
2079    }
2080
2081    #[test]
2082    fn handle_of_a_set_that_never_ran() {
2083        let mut set = BranchSet::new();
2084        let handle = set.add("inventory", |_ctx| async { Ok(1_u32) });
2085        drop(set);
2086        let Err(err) = handle.into_result() else {
2087            panic!("a handle whose set never ran has no result");
2088        };
2089        let crate::OperationErrorKind::ChildContext(child) = err.kind() else {
2090            panic!("the error is a child context error: {err:?}");
2091        };
2092        assert!(matches!(
2093            child.kind(),
2094            crate::ChildContextErrorKind::NotCompleted
2095        ));
2096        assert_eq!(child.kind().to_string(), "branch has no result");
2097        let source = std::error::Error::source(child).expect("the error has a source");
2098        assert_eq!(
2099            source.to_string(),
2100            r#"parallel branch "inventory" has no result"#
2101        );
2102    }
2103
2104    #[test]
2105    fn empty_branch_name_records_the_default_name() {
2106        let mut set = BranchSet::default();
2107        let handle = set.add("", |_ctx| async { Ok(1_u32) });
2108        drop(set);
2109        let err = handle.into_result().expect_err("no result");
2110        let source = std::error::Error::source(&err)
2111            .and_then(std::error::Error::source)
2112            .map(ToString::to_string);
2113        assert_eq!(
2114            source.as_deref(),
2115            Some(r#"parallel branch "parallel-branch-0" has no result"#)
2116        );
2117    }
2118
2119    #[test]
2120    fn branch_set_and_handle_debug() {
2121        let mut set = BranchSet::new();
2122        assert_eq!(format!("{set:?}"), "BranchSet { names: [], .. }");
2123        let handle = set.add("a", |_ctx| async { Ok(1_u32) });
2124        let _other = set.add_with_serdes("b", crate::JsonSerdes, |_ctx| async { Ok(2_u32) });
2125        assert_eq!(format!("{set:?}"), r#"BranchSet { names: ["a", "b"], .. }"#);
2126        assert_eq!(
2127            format!("{handle:?}"),
2128            r#"BranchHandle { name: "a", has_result: false, .. }"#
2129        );
2130        *lock_slot(&handle.slot) = Some(Ok(1));
2131        assert_eq!(
2132            format!("{handle:?}"),
2133            r#"BranchHandle { name: "a", has_result: true, .. }"#
2134        );
2135    }
2136
2137    /// Whether two keys name the same branch of the same set.
2138    fn same_branch<T>(a: &BranchKey<T>, b: &BranchKey<T>) -> bool {
2139        Arc::ptr_eq(&a.identity, &b.identity) && a.index == b.index
2140    }
2141
2142    #[test]
2143    fn branch_keys_name_their_branch_and_set() {
2144        fn assert_clone_send_sync<K: Clone + Send + Sync>() {}
2145        assert_clone_send_sync::<BranchKey<std::cell::Cell<String>>>();
2146
2147        let mut first = BranchSet::new();
2148        let a = first.add("a", |_ctx| async { Ok(1_u32) });
2149        let b = first.add("b", |_ctx| async { Ok(2_u32) });
2150        let mut second = BranchSet::new();
2151        let other_a = second.add("a", |_ctx| async { Ok(1_u32) });
2152
2153        assert!(same_branch(&a.key(), &a.key()));
2154        assert!(same_branch(&a.key(), &a.key().clone()));
2155        assert!(!same_branch(&a.key(), &b.key()));
2156        assert!(!same_branch(&a.key(), &other_a.key()));
2157        assert_eq!(format!("{:?}", b.key()), "BranchKey { index: 1, .. }");
2158    }
2159}