Package software.amazon.lambda.durable.plugin

Class PluginRunner

java.lang.Object
software.amazon.lambda.durable.plugin.PluginRunner
public class PluginRunner extends Object
Dispatches the lifecycle hooks of a single Lambda invocation to that invocation's plugin instances.

A runner is created per invocation from the configured factories and holds no plugin instances until onInvocationStart(InvocationInfo) materializes and starts each plugin in configured order, from the very InvocationInfo the first hook then receives. releasePlugins() drops them when the invocation returns, so a plugin instance is never shared between invocations and never needs to key its state by execution ARN.

Event hooks are fire-and-forget: each plugin is called in order, non-fatal failures are contained. A factory with a non-fatal failure or returns null is contained the same way — the plugin is skipped for the invocation. Containment covers every non-fatal throwable, not only Exception, because a plugin built against a different SDK version, one missing an optional dependency, and one running with assertions enabled all fail with an Error. It stops short of two cases, which keep propagating: the errors that report the JVM itself failing, and the ThreadDeath that reports the thread running the plugin has already been terminated.

onInvocationEnd runs on the root handler thread after body unwinding, operation/checkpoint draining, and output preparation. The SDK awaits it before returning, so plugins can flush data before Lambda freezes.

  • Constructor Details

  • Method Details

    • validateExclusiveGroups

      public static void validateExclusiveGroups(List<DurableExecutionPluginFactory> factories)
      Validates configured factory metadata without creating invocation-owned plugins or spans.

    • noOp

      public static PluginRunner noOp()
      Returns a runner with no plugin factories, which does nothing.

    • isEmpty

      public boolean isEmpty()
      Returns true if no plugin factories are registered.

    • releasePlugins

      public void releasePlugins()
      Drops invocation-level plugin references when the invocation returns. A started operation retains only its matching hook recipients until its owner unwinds; these recipients are never reused by another invocation.

      No containment here: this only replaces the field, and calls nothing on the plugins it drops. There is no close() in the plugin contract, so releasing cannot run plugin code and cannot fail.

    • providePropagationMetadata

      public PropagationMetadata providePropagationMetadata(PropagationInput input)
      Collects supported metadata in configured order on the caller's thread. First non-null member wins; matching later values are harmless. Ordinary plugin/invalid-result failures and linkage errors are logged and skipped, matching the event hooks' isolation policy; other Errors continue to propagate. The core calls this while creating a new invoke START checkpoint, not while replaying an existing operation.

    • runHandler

      public <T> T runHandler(Supplier<T> handler)
      Runs the root handler with optional plugin scopes, closing them on the same thread in reverse order.

    • runHandler

      public <T> T runHandler(Supplier<T> handler, Runnable onScopeOpened)
      Runs the handler and notifies the invocation when a scope requires same-thread finalization.

    • runHandler

      public <T> T runHandler(Supplier<T> handler, Runnable onScopeOpened, Consumer<Error> onScopeFatal)
      Reports fatal errors from scope callbacks; retains the existing standalone runner body policy.

    • runHandler

      public <T> T runHandler(Supplier<T> handler, Runnable onScopeOpened, Consumer<Error> onScopeFatal, Function<Error,Error> publishBodyFatal)
      Publishes an existing-classifier body fatal before owned cleanup only if the invocation still accepts it. The publisher returns the winning fatal, or null when earlier invocation control already won. A null publisher retains the standalone body path without classifying its failures.

    • onInvocationStart

      public void onInvocationStart(InvocationInfo info)

    • onInvocationEnd

      public void onInvocationEnd(InvocationEndInfo info)
      Called at the end of each invocation. Awaited — the SDK blocks until all plugins return, allowing plugins to flush spans/metrics before Lambda freezes. The first fatal immediately stops outstanding operation work; an earlier invocation fatal retains precedence. Remaining plugins still receive their one finalization opportunity with the shared snapshot before the first end-hook fatal is rethrown.

    • onOperationStart

      public void onOperationStart(OperationInfo info)

    • onOperationEnd

      public void onOperationEnd(OperationEndInfo info)

    • onOperationChange

      public void onOperationChange(OperationChangeInfo info)

    • onUserFunctionStart

      public void onUserFunctionStart(UserFunctionStartInfo info)

    • onUserFunctionEnd

      public void onUserFunctionEnd(UserFunctionEndInfo info)

    • onUserFunctionEndAfterFatal

      public void onUserFunctionEndAfterFatal(UserFunctionEndInfo info, Error original)
      Completes same-owner attempt cleanup after a peer fatal while retaining the invocation's original failure.

    • captureUserFunctionHooks

      public PluginRunner.UserFunctionHooks captureUserFunctionHooks()
      Captures this invocation's attempt hook recipients without invoking factories or sharing plugin instances.