Skip to content

feat: add custom extension operations API - #607

Open
zhongkechen wants to merge 50 commits into
mainfrom
codex/extension-operation-refactor
Open

feat: add custom extension operations API#607
zhongkechen wants to merge 50 commits into
mainfrom
codex/extension-operation-refactor

Conversation

@zhongkechen

@zhongkechen zhongkechen commented Aug 10, 2026

Copy link
Copy Markdown
Contributor

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

Issue Link, if available

Closes #571

Description

  • Add the public ExtensionContext and ExtensionOperation SPI for composing SDK-owned durable primitives with stable reservations, custom subtypes, stateful step replay, and configurable child contexts.
  • Route customer-facing operations through singular Durable*Operation facades and move backend engines into the primitive package.
  • Add operation-owned nested config types while preserving existing DurableContext, ParallelDurableFuture, and compatibility config APIs.
  • Implement map, parallel, callback, condition, and retry operations on the extension path while preserving checkpoint/replay, plugin, retry, and serialization behavior.
  • Add extension author documentation and ADR-006.
  • PR #611, which migrates the experimental DAG support to the extension SPI, is a concrete example of using this new SPI.

Demo/Screenshots

Not applicable. This change adds Java SDK APIs and internal architecture; no visual interface is changed.

Checklist

  • I have filled out every section of the PR template
  • I have thoroughly tested this change

Testing

Unit Tests

Yes. Added and updated unit coverage for extension reservations, stateful steps, child-context replay, operation facades/config conversion, primitive implementations, deterministic IDs, plugin metadata, and compatibility APIs.

Full SDK result: 1,202 tests passed.

Integration Tests

Yes. Added integration coverage for extension operations, static operation facades, extension concurrency, plugins, replay, callbacks, retries, map, and parallel behavior.

Full integration result: 413 tests passed.

Examples

No new example was required. Existing examples remain source-compatible and passed their test suite: 120 tests passed, with 34 cloud-only tests skipped by default.

Verification command:

mvn clean install

The OpenTelemetry module also passed 163 tests. Spotless and diff checks pass.

@github-actions

This comment has been minimized.

@zhongkechen
zhongkechen had a problem deploying to ai-pr-review-runtime August 20, 2026 17:31 — with GitHub Actions Failure
@zhongkechen
zhongkechen temporarily deployed to ai-pr-review-runtime August 20, 2026 17:31 — with GitHub Actions Inactive
@zhongkechen
zhongkechen had a problem deploying to ai-pr-review-runtime August 20, 2026 18:41 — with GitHub Actions Failure
@zhongkechen
zhongkechen temporarily deployed to ai-pr-review-runtime August 20, 2026 18:41 — with GitHub Actions Inactive
Comment thread sdk/src/main/java/software/amazon/lambda/durable/execution/ExecutionManager.java Outdated
@github-actions

This comment has been minimized.

# Conflicts:
#	sdk-integration-tests/src/test/java/software/amazon/lambda/durable/PluginIntegrationTest.java
#	sdk/src/main/java/software/amazon/lambda/durable/execution/DurableExecutor.java
#	sdk/src/main/java/software/amazon/lambda/durable/plugin/PluginInfoConverter.java
#	sdk/src/test/java/software/amazon/lambda/durable/plugin/PluginInfoConverterTest.java
@zhongkechen
zhongkechen had a problem deploying to ai-pr-review-runtime August 27, 2026 05:02 — with GitHub Actions Failure
@zhongkechen
zhongkechen temporarily deployed to ai-pr-review-runtime August 27, 2026 05:02 — with GitHub Actions Inactive
@github-actions

This comment has been minimized.

@zhongkechen
zhongkechen deployed to ai-pr-review-runtime August 27, 2026 05:39 — with GitHub Actions Active
@zhongkechen
zhongkechen had a problem deploying to ai-pr-review-runtime August 27, 2026 05:39 — with GitHub Actions Failure
Throwable throwable) {
var cause = software.amazon.lambda.durable.util.ExceptionHelper.unwrapCompletableFuture(throwable);
if (cause instanceof SuspendExecutionException || cause instanceof UnrecoverableDurableExecutionException) {
return CompletableFuture.failedFuture(cause);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Codex AI review · Finding arf_v1_efufskzwapiifaigbhd53nhmx6

[P1] Preserve the durable context across backoff completion. When another durable thread remains active, this wait can complete in-process on a polling/checkpoint thread. The continuation then calls executeRetryLoop(), which reads thread-local context and fails with IllegalStateException instead of starting the next attempt. Resume via a context-aware executor that restores the child durable context and logical thread state, or explicitly capture and restore both. Add an integration test with retry backoff and a concurrently running sibling operation.

ignored ->
CompletableFuture.completedFuture(ExtensionStepResult.succeed(function.get())),
extensionConfig(config)));
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Codex AI review · Finding arf_v1_wleseolejcs67e5dfazmlwepne

[P2] Preserve zero-delay custom retry strategies. RetryDecision.retry(null) produces Duration.ZERO, and the previous step implementation accepted zero-second delays, but ExtensionStepResult.retry rejects durations below one second. Existing custom StepConfig retry strategies can therefore terminate the execution with a validation exception instead of retrying. Either retain immediate-retry support in the extension result or normalize zero to the intended supported delay before constructing it, and add a regression test for null/zero retry delays.

@github-actions

Copy link
Copy Markdown
Contributor

Codex AI review

Found two retry-related regressions affecting in-process backoff and existing zero-delay retry strategies.

Reviewed commit 09e3232778c58df63fbfc8b62613bf5727c73753. Workflow run

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Add a public API for custom extension operations

1 participant