Skip to content

Add initial extstore types#2900

Open
cconstable wants to merge 11 commits into
masterfrom
extstore-foundation
Open

Add initial extstore types#2900
cconstable wants to merge 11 commits into
masterfrom
extstore-foundation

Conversation

@cconstable
Copy link
Copy Markdown

@cconstable cconstable commented Jun 4, 2026

What was changed

Adds the @Experimental External Storage API surface under io.temporal.payload.storage. Type
definitions only.

Types:

  • StorageDriver: driver contract (async store/retrieve, getName/getType).
  • StorageDriverClaim: claim-check token for an externally stored payload.
  • StorageDriverSelector: chooses a driver per payload, or keeps it inline.
  • StorageDriverStoreContext / StorageDriverRetrieveContext: driver-call contexts.
  • StorageDriverTargetInfo plus StorageDriverWorkflowInfo / StorageDriverActivityInfo: best-effort,
    store-side target identity.
  • ExternalStorage (plus Builder): config for drivers, optional selector, and size threshold.

Notes:

  • No WorkflowClientOptions setter yet.
  • Builder validation throws IllegalStateException. Stable diagnostic codes are a follow-up.

Why?

  • First part of part of Large Payloads -> External Storage work

Checklist

  • Added tests.

Comment thread temporal-sdk/src/main/java/io/temporal/payload/storage/ExternalStorage.java Outdated
@cconstable cconstable changed the title Add initial extstore types. Add initial extstore types Jun 4, 2026
return this;
}

public ExternalStorage build() {
Copy link
Copy Markdown
Author

@cconstable cconstable Jun 4, 2026

Choose a reason for hiding this comment

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

Right now, these all throw state exceptions (which are tested). In a subsequent PR, I would like to replace these with stable diagnostic codes.

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.

For these in particular, do we need diagnostic codes? The messages are fairly clear as to what the issue is and prevent the use of external storage at startup rather than having to report during execution runtime.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

I am a proponent of best-effort, stable diagnostic codes if the mechanism for adding them very easy. I have a little write-up about this that I wanted to share but the tl;dr is I think we should make a best effort to tag anything that's actionable if for nothing else it supports automated tooling (e.g. AI) and feels like a healthy industry trend (hand wavy gesture). I would not have felt this way 4 years ago.

@cconstable cconstable marked this pull request as ready for review June 4, 2026 20:34
@cconstable cconstable requested a review from a team as a code owner June 4, 2026 20:34
Copy link
Copy Markdown
Contributor

@jmaeagle99 jmaeagle99 left a comment

Choose a reason for hiding this comment

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

Left some comments but overall looks good. Please hold off until a Java owner reviews and approves.

@cconstable cconstable requested a review from maciejdudko June 8, 2026 15:19
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.

2 participants