[diwu-sf]

What changed?

Added an experimental Google Cloud Storage driver for external payloads and an adapter for the official Google Cloud Storage Java client.

Object names follow the existing GCS drivers' encoding and namespace layout, with a namespace-preserving fallback for long names. Claims use object_name. Uploads leave existing objects unchanged, and downloads verify SHA-256 before decoding the complete payload, including metadata.

The application owns the Google client and executor. Includes setup documentation and automatic integration tests against fsouza/fake-gcs-server. Gradle downloads and caches a checksum-verified native binary; JUnit starts the server on a free local port and cleans up afterward.

The quickstart uses StorageOptions.grpc() for automatic DirectPath selection and includes a short note on preserving Google's runtime dependencies, service registrations, and Conscrypt native libraries when packaging an application.

Why?

Store large Temporal payloads in GCS without writing a custom storage driver.

Related to temporalio/features#924.

Breaking changes?

No existing SDK API changes. The optional Google client adapter brings newer protobuf and gRPC dependencies.

Server PR

Not required.

Testing

• All 54 GCS tests passed without skips, including seven tests using the real Google client against fake GCS.
• Integration coverage includes canonical claims, Unicode object names, a 6 MiB payload, missing objects and buckets, concurrent conditional uploads, integrity failures, empty namespaces, and long-name fallback.
• ./gradlew --offline spotlessApply passed.
• Both GCS modules passed build, including tests and Javadocs, with Java 21 and Java 8 release compatibility checks.
• Confirmed that the existing dev-server preparation task also prepares the cached GCS emulator for offline tests.
• Manual validation with a temporary GCE VM and a co-located GCS bucket confirmed ALTS DirectPath for uploads and downloads.
• The full repository test suite was not run.

[diwu-sf]

@jmaeagle99 this java GCS support is ready for review now, thanks

[diwu-sf]

Tested against real GCS

I ran this branch end to end against real Google Cloud Storage and Temporal, over both HTTP and gRPC. Tests ran from AWS and from a GCP VM in the same region as the bucket.

No bugs found. Over 150,000 storage calls, nothing failed and every payload came back exactly as stored. Large payloads, unusual names, tampered files, cancelled uploads and worker restarts all behaved correctly.

The main test was an AI agent that sends its whole conversation to each LLM call, 200 conversations at once. A 500k-token conversation is about 2 MB per call. On the GCP VM:

	HTTP	gRPC
Total time	53 s	33 s
Typical upload	333 ms	62 ms
Timeouts (retried automatically)	70	0

Running this on GCP

1. Use gRPC (StorageOptions.grpc()) when workers run in GCP, in the same region as the bucket. It was about twice as fast as HTTP. Outside GCP, use HTTP; gRPC was 3–7× slower there.
2. Give the worker's service account roles/monitoring.metricWriter, or call setEnableGrpcClientMetrics(false). Otherwise the gRPC client fills the logs with permission warnings.
3. Limit load with the worker's slot settings, not the storage thread pool. 32 slots handled all 200 conversations at full speed in a 4 GB heap.
4. On Java 8–20, use a fixed thread pool at least as large as the worker's slots. A 16-thread pool was about 20% slower.
5. Make the workflow cache large enough for active workflows. Each cache miss downloads all of that workflow's stored payloads again.