exstore/pipeline integration by cconstable · Pull Request #2978 · temporalio/sdk-java

cconstable · 2026-07-29T21:06:48Z

Client + Nexus + Worker external storage integration

What was changed

enabled extstore via WorkflowClientOptions.setExternalStorage(...), worker/WorkerFactoryOptions, internal/worker/SingleWorkerOptions, and worker/Worker
client/worker with no external storage configured fails with TMPRL-1105
Client: integration via new decorator ExternalStorageGenericWorkflowClient that is used in client/WorkflowClientInternalImpl
Workers: integration via internal/worker/{WorkflowWorker,ActivityWorker,NexusWorker} and internal/replay/{ServiceWorkflowHistoryIterator,ReplayWorkflowTaskHandler}
Activity completion + heartbeat integration.

Why?

makes extstore "work" in client, worker, and nexus pipelines

Checklist

Added new tests

…elines.

…ayloads

Copilot

Pull request overview

Adds end-to-end external storage (“extstore”) support across the Java SDK client and worker execution pipelines (including Nexus) by introducing message-level payload offload/restore and clear failure behavior when references are encountered without extstore configured.

Changes:

Introduces WorkflowClientOptions.setExternalStorage(...) integration via a ExternalStorageGenericWorkflowClient decorator and worker-side wiring through SingleWorkerOptions and worker implementations.
Adds worker/client plumbing to offload outbound payloads, restore inbound payloads, and propagate TMPRL-1105 consistently when references reach deserialization without extstore configured.
Expands tests to cover pipeline round-trips, concurrency bounds, interrupt behavior, and manual activity completion/heartbeat integration.

Reviewed changes

Copilot reviewed 35 out of 35 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
temporal-testing/src/main/java/io/temporal/testing/TestActivityEnvironmentInternal.java	Updates activity test environment wiring for new activity context factory signature (currently passes null extstore converter).
temporal-sdk/src/test/java/io/temporal/internal/payload/storage/ExternalStoragePipelineTest.java	New end-to-end pipeline test validating store/retrieve behavior through client + worker execution.
temporal-sdk/src/test/java/io/temporal/internal/payload/storage/ExternalStorageMessageConverterTest.java	Adds tests for visit concurrency bounding and interrupt handling in blocking store.
temporal-sdk/src/test/java/io/temporal/internal/client/external/ManualActivityCompletionClientImplTest.java	New tests ensuring manual completion wraps/ignores storage failures appropriately.
temporal-sdk/src/test/java/io/temporal/internal/client/external/ExternalStorageGenericWorkflowClientTest.java	New tests validating target info propagation for standalone activity start and multi-operation.
temporal-sdk/src/test/java/io/temporal/internal/activity/HeartbeatContextImplTest.java	Updates tests for new constructor parameters (extstore converter).
temporal-sdk/src/test/java/io/temporal/internal/activity/ActivityExecutionContextImplTest.java	New test validating local manual completion includes activity storage target info.
temporal-sdk/src/test/java/io/temporal/common/converter/ExternalStorageReferenceGuardTest.java	New tests validating `[TMPRL-1105]` guard behavior when extstore isn’t configured.
temporal-sdk/src/main/java/io/temporal/worker/WorkerFactoryOptions.java	Adds max concurrent external-storage visit option and exposes it via getter/builder.
temporal-sdk/src/main/java/io/temporal/worker/Worker.java	Wires client external storage config into worker `SingleWorkerOptions` via message converter creation.
temporal-sdk/src/main/java/io/temporal/payload/storage/StorageDriver.java	Clarifies driver expectations around cancellation + backend timeouts (SDK imposes no timeout).
temporal-sdk/src/main/java/io/temporal/internal/worker/WorkflowWorker.java	Offloads outbound workflow task/query completion payloads with workflow target context.
temporal-sdk/src/main/java/io/temporal/internal/worker/SyncActivityWorker.java	Passes extstore message converter into activity execution context factory.
temporal-sdk/src/main/java/io/temporal/internal/worker/SingleWorkerOptions.java	Adds optional external storage message converter to per-worker options.
temporal-sdk/src/main/java/io/temporal/internal/worker/NexusWorker.java	Adds inbound restore + outbound offload for Nexus task handling.
temporal-sdk/src/main/java/io/temporal/internal/worker/ActivityWorker.java	Adds inbound restore + outbound offload for activity task handling, including activity target context.
temporal-sdk/src/main/java/io/temporal/internal/sync/WorkflowExecutionHandler.java	Ensures missing-extstore failures propagate cleanly rather than being wrapped/obscured.
temporal-sdk/src/main/java/io/temporal/internal/sync/SignalDispatcher.java	Propagates missing-extstore failures distinctly from generic `DataConverterException`.
temporal-sdk/src/main/java/io/temporal/internal/replay/ServiceWorkflowHistoryIterator.java	Adds optional extstore restoration when paging history during replay.
temporal-sdk/src/main/java/io/temporal/internal/replay/ReplayWorkflowTaskHandler.java	Restores inbound WFT payloads and replay history when extstore is enabled; propagates missing-extstore error.
temporal-sdk/src/main/java/io/temporal/internal/payload/storage/ExternalStorageNotConfiguredException.java	New exception type for `[TMPRL-1105]` missing-extstore failures with helper `find(...)`.
temporal-sdk/src/main/java/io/temporal/internal/payload/storage/ExternalStorageMessageConverter.java	Makes message converter public (internal package), adds factory methods and blocking store/retrieve helpers.
temporal-sdk/src/main/java/io/temporal/internal/nexus/NexusTaskHandlerImpl.java	Propagates missing-extstore failures from Nexus handler execution.
temporal-sdk/src/main/java/io/temporal/internal/client/external/ManualActivityCompletionClientImpl.java	Offloads manual completion and heartbeat payloads; adds storage target + converter plumbing.
temporal-sdk/src/main/java/io/temporal/internal/client/external/ManualActivityCompletionClientFactoryImpl.java	Adds storage target computation and passes extstore converter into manual completion clients.
temporal-sdk/src/main/java/io/temporal/internal/client/external/ManualActivityCompletionClientFactory.java	Adds overloads to supply extstore converter and explicit storage target info.
temporal-sdk/src/main/java/io/temporal/internal/client/external/ExternalStorageGenericWorkflowClient.java	New client decorator that offloads outbound and restores inbound payloads for many service calls.
temporal-sdk/src/main/java/io/temporal/internal/client/ActivityClientHelper.java	Offloads heartbeat request details when extstore is configured.
temporal-sdk/src/main/java/io/temporal/internal/activity/HeartbeatContextImpl.java	Adds extstore-aware heartbeat sending with activity storage target info.
temporal-sdk/src/main/java/io/temporal/internal/activity/ActivityTaskExecutors.java	Propagates missing-extstore failures distinctly during activity execution.
temporal-sdk/src/main/java/io/temporal/internal/activity/ActivityExecutionContextImpl.java	Passes extstore converter into heartbeat context and provides storage target for local manual completion.
temporal-sdk/src/main/java/io/temporal/internal/activity/ActivityExecutionContextFactoryImpl.java	Stores extstore converter and wires it into contexts and manual completion factory.
temporal-sdk/src/main/java/io/temporal/common/converter/PayloadAndFailureDataConverter.java	Adds guard: reference payloads reaching deserialization without extstore configured throw `[TMPRL-1105]`.
temporal-sdk/src/main/java/io/temporal/client/WorkflowClientOptions.java	Adds user-facing external storage options field with builder/getter + equality/toString updates.
temporal-sdk/src/main/java/io/temporal/client/WorkflowClientInternalImpl.java	Wraps generic client with extstore decorator and passes extstore converter into manual completion factory.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

            testEnvironmentOptions.getWorkflowClientOptions().getDataConverter(),
-            heartbeatExecutor);
+            heartbeatExecutor,
+            null);


+     * Maximum number of concurrent payload-list visits performed while offloading or restoring
+     * external-storage payloads for a single worker task. Only applies when external storage is
+     * configured on the client. Must be at least 1.
+     *
+     * <p>Default is 3.


cconstable · 2026-07-31T21:26:48Z

-    payloads.ifPresent(request::setDetails);
+    payloads.ifPresent(builder::setDetails);
+    RecordActivityTaskHeartbeatRequest request = builder.build();
+    if (externalStorage != null) {


This covers both worker and manual heartbeats

cconstable · 2026-07-31T21:33:11Z


      ServiceWorkflowHistoryIterator historyIterator =
-          new ServiceWorkflowHistoryIterator(service, namespace, workflowTask, metricsScope);
+          new ServiceWorkflowHistoryIterator(


is this used by the worker?

cconstable · 2026-07-31T21:36:33Z

+      ExternalStorageNotConfiguredException externalStorageFailure =
+          ExternalStorageNotConfiguredException.find(e);
+      if (externalStorageFailure != null) {
+        throw externalStorageFailure;
+      }


lets look at how other errors are being handled here and make sure we aren't special-casing extstore errors

cconstable · 2026-07-31T21:46:45Z

+                    .setIdentity(options.getIdentity())
+                    .setNamespace(namespace)
+                    .setWorkerVersion(options.workerVersionStamp())
+                    .build(),


@jmaeagle99 suggests looking at passing through builders to visitor. are there perf concerns? are we building messages twice? @cconstable will investigate.

cconstable added 3 commits July 29, 2026 14:35

feat(exstore): add to client and worker options.

9b0bf33

feat(extstore): integrate external storage into client and worker pip…

61b6960

…elines.

feat(extstore): offload activity completion and heartbeat payloads

802f0d0

cconstable changed the base branch from main to extstore-core-logic July 29, 2026 21:07

cconstable added 10 commits July 29, 2026 17:17

feat(extstore): offload nexus worker task payloads

b366b7a

feat(extstore): offload remaining client RPCs and WFT query/failure p…

1077c15

…ayloads

add clientWithoutExternalStorageReadingAReferenceFails test

347cd02

fix(extstore): resolve external-storage references during offline replay

e2324dc

fix(extstore): release Nexus slots on retrieval failure

0d499a6

fix(extstore): preserve missing storage failures

eb94434

fix(extstore): correct activity storage targets.

eb7dfb9

fix(extstore): handle manual completion storage failures

a274ddd

fix(extstore): bound client I/O and honor interrupts.

0bb07a8

fix(extstore): add multi-operation workflow target

df97c19

cconstable marked this pull request as ready for review July 30, 2026 19:42

cconstable requested a review from a team as a code owner July 30, 2026 19:42

cconstable requested a review from Copilot July 30, 2026 19:56

Copilot started reviewing on behalf of cconstable July 30, 2026 19:56 View session

Copilot AI reviewed Jul 30, 2026

View reviewed changes

cconstable commented Jul 31, 2026

View reviewed changes

Navigation Menu

Uh oh!

exstore/pipeline integration - #2978

exstore/pipeline integration#2978
cconstable wants to merge 13 commits into
extstore-core-logicfrom
exstore/pipeline-integration

cconstable commented Jul 29, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

cconstable Jul 31, 2026

Uh oh!

cconstable Jul 31, 2026

Uh oh!

cconstable Jul 31, 2026

Uh oh!

cconstable Jul 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

cconstable commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What was changed

Why?

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

cconstable Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

cconstable Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

cconstable Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

cconstable Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cconstable commented Jul 29, 2026 •

edited

Loading