feat: add custom extension operations API by zhongkechen · Pull Request #607 · aws/aws-durable-execution-sdk-java

zhongkechen · 2026-08-10T16:11:58Z

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.

Sign in to view

 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
-package software.amazon.lambda.durable.operation;
+package software.amazon.lambda.durable.primitive;


Sign in to view

-    /** Returns the operation type derived from the sub-type. */
-    public OperationType operationType() {
-        return subType.getOperationType();
+public record OperationIdentifier(String operationId, String name, OperationType operationType, String subType) {


Sign in to view

+        if (!allocatedLocalIds.add(localOperationId)) {
+            throw new IllegalArgumentException("Local operation ID is already in use: " + localOperationId);
+        }


Sign in to view

+        if (delay.isNegative()) {
+            throw new IllegalArgumentException("delay cannot be negative");


Sign in to view

+        validateSubType(subType);
+        Objects.requireNonNull(function, "function cannot be null");
+        Objects.requireNonNull(config, "config cannot be null");
+        claim();


Sign in to view

+ */
+public class ErrorHandlingExample extends DurableHandler<Object, String> {
+
+    private static final Logger logger = LoggerFactory.getLogger(ErrorHandlingExample.class);


github-actions · 2026-08-12T21:43:57Z

 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
-package software.amazon.lambda.durable.operation;
+package software.amazon.lambda.durable.primitive;


Codex AI review

[P1] Retain compatibility classes at the old public FQCNs. This move, together with removal of the other public operation engine classes, makes existing clients fail to compile or link (NoClassDefFoundError) when upgrading to 2.1.1. Keep deprecated forwarding classes under software.amazon.lambda.durable.operation, or defer their removal to a major release.

github-actions · 2026-08-12T21:43:58Z

-    /** Returns the operation type derived from the sub-type. */
-    public OperationType operationType() {
-        return subType.getOperationType();
+public record OperationIdentifier(String operationId, String name, OperationType operationType, String subType) {


Codex AI review

[P1] Preserve the existing constructor and accessor descriptors. The public record previously accepted (String, String, OperationSubType) and exposed OperationSubType subType(). Replacing both breaks source and binary compatibility. Retain the three-argument constructor and enum accessor, and expose custom subtype strings through a separately named accessor such as subTypeValue().

github-actions · 2026-08-12T21:44:00Z

+        Completion awaitCompletion(ExpectedCompletionStatus expectedCompletionStatus) {
+            while (true) {


Codex AI review

[P2] Restore unrecoverable handling for coordinator faults. The former concurrency engine converted unexpected exceptions, including failures from custom shouldComplete callbacks, into IllegalDurableOperationException and terminated execution. Exceptions escaping this loop are now caught by ChildContextPrimitive, checkpointed as a recoverable failed map/parallel context, and can be caught by user code. Wrap this loop with the previous policy: rethrow suspension/unrecoverable signals and convert other failures to IllegalDurableOperationException; add an integration test for a throwing completion callback.

github-actions · 2026-08-12T21:44:01Z

+        var localOperationId = String.valueOf(operationCounter.incrementAndGet());
+        if (!allocatedLocalIds.add(localOperationId)) {
+            throw new IllegalArgumentException("Local operation ID is already in use: " + localOperationId);


Codex AI review

[P2] Skip custom-claimed numeric IDs instead of failing. After reserving custom local ID "2", the counter is 1, so the next sequential reservation calculates "2" and throws. This contradicts the new documented contract that generated IDs skip claimed values and makes valid mixed custom/sequential workflows fail before creating an operation. Increment in a loop until allocatedLocalIds.add(...) succeeds, and update the collision test accordingly.

github-actions · 2026-08-12T21:44:03Z

+        var virtualEmptyMap = itemList.isEmpty() && !context.getDurableConfig().shouldCheckpointEmptyMap();
+        var parentConfig = parentContextConfig(mapConfig.serDes(), virtualEmptyMap).toBuilder()


Codex AI review

[P2] Preserve the replay-to-execution transition for non-checkpointed empty maps. Making this parent virtual bypasses BasePrimitive.execute()'s missing-operation lookup and setExecutionMode() call. On replay, the enclosing context therefore remains replaying after reaching the empty map, so isReplaying() is incorrect and subsequent durable logs can be suppressed. Keep the map uncheckpointed while explicitly performing the transition, and cover this with a replay/logging test.

github-actions · 2026-08-12T21:44:05Z

Codex AI review

Found five actionable issues affecting compatibility, replay semantics, and execution lifecycle. Tests were not run per review constraints.

Reviewed commit 6d2ff84ffea314da23b4ce06abb7c86e96a787de. Workflow run

zhongkechen deployed to ai-pr-review August 10, 2026 16:12 — with GitHub Actions Active

zhongkechen had a problem deploying to ai-pr-review-runtime August 10, 2026 16:23 — with GitHub Actions Failure

zhongkechen mentioned this pull request Aug 10, 2026

[EXPERIMENTAL] feat(dag): migrate DAG support to extension SPI #611

Draft

2 tasks

zhongkechen force-pushed the codex/extension-operation-refactor branch from 03121c7 to a73d2d0 Compare August 10, 2026 19:22

zhongkechen deployed to ai-pr-review August 10, 2026 20:32 — with GitHub Actions Active

zhongkechen had a problem deploying to ai-pr-review-runtime August 10, 2026 20:32 — with GitHub Actions Failure

zhongkechen added 22 commits August 10, 2026 14:31

docs: design custom extension operations API

17ba43b

docs: split extension operation facades

3cb3728

docs: define TLS-only extension callbacks

8c4b3ee

docs: add custom extension operations ADR

0aaaace

docs: plan custom extension operations implementation

c03d6dd

feat: add extension operation reservations

6905f4b

feat: add static durable operation facades

59eb34d

feat: expose durable future completion signals

96eab15

test: verify extensions across module boundary

d3c7749

docs: publish custom extension operations guide

781655b

docs: design built-in extension migration

44dd8ac

docs: amend custom extension operations ADR

b1ff167

docs: plan built-in extension migration

f543e8a

feat: add custom extension operation ids

ef2ce97

feat: support custom extension subtypes

5a2b5e7

feat: add stateful extension steps

783dcf0

feat: add configurable extension contexts

3f638b3

feat: organize extension APIs and migrate callbacks

2546635

refactor: implement retry and condition as extensions

b5590fa

feat: add extension concurrency coordination

f126e4c

refactor: implement map as an extension

ca88c93

refactor: implement parallel as an extension

109c0ca

zhongkechen had a problem deploying to ai-pr-review-runtime August 11, 2026 00:52 — with GitHub Actions Failure

zhongkechen temporarily deployed to ai-pr-review-runtime August 11, 2026 00:52 — with GitHub Actions Inactive

refactor: mark primitive implementations internal

39b1381

zhongkechen temporarily deployed to ai-pr-review-runtime August 11, 2026 03:08 — with GitHub Actions Inactive

zhongkechen had a problem deploying to ai-pr-review-runtime August 11, 2026 03:08 — with GitHub Actions Failure