Add export history support (#293)

Author: bachuv

.github/workflows/build-validation.yml

@@ -142,6 +142,14 @@ jobs:
         name: Integration test report
         path: client/build/reports/tests/integrationTest
 
+    - name: Archive export history integration test report
+      if: always()
+      uses: actions/upload-artifact@v4
+      with:
+        name: Export history integration test report
+        path: exporthistory/build/reports/tests/integrationTest
+        if-no-files-found: ignore
+
     - name: Upload JAR output
       uses: actions/upload-artifact@v4
       with:

CHANGELOG.md

@@ -1,4 +1,5 @@
 ## Unreleased
+* Add the `exporthistory` module for durable, checkpointed export of terminal orchestration history to Azure Blob Storage ([#293](https://github.com/microsoft/durabletask-java/pull/293))
 * Add client APIs to list terminal instance IDs by completion time (`listInstanceIds`) and read orchestration history (`getOrchestrationHistory`) ([#292](https://github.com/microsoft/durabletask-java/pull/292))
 * Add `createReplaySafeLogger` to suppress orchestration log output during replay ([#295](https://github.com/microsoft/durabletask-java/pull/295)).
 * Add `getParentInstance()` API to `TaskOrchestrationContext` for discovering parent orchestration info ([#284](https://github.com/microsoft/durabletask-java/pull/284))

client/src/main/java/com/microsoft/durabletask/AbstractTaskEntity.java

@@ -392,7 +392,13 @@ private static Optional<Method> findMethodUncached(Class<?> targetClass, String
                     "Ambiguous match: multiple methods named '" + operationName + "' found on " +
                     targetClass.getName() + ". Entity operation methods must have unique names.");
         }
-        return matches.isEmpty() ? Optional.empty() : Optional.of(matches.get(0));
+        if (matches.isEmpty()) {
+            return Optional.empty();
+        }
+        // Resolve reflective accessibility once, at method-caching time, rather than on every dispatch.
+        Method resolved = matches.get(0);
+        makeDeclaringClassAccessible(resolved);
+        return Optional.of(resolved);
     }
 
     /**
@@ -431,4 +437,19 @@ private static Object invokeMethod(Method method, Object target, TaskEntityOpera
             throw new RuntimeException(cause);
         }
     }
+
+    private static void makeDeclaringClassAccessible(Method method) {
+        if (!Modifier.isPublic(method.getDeclaringClass().getModifiers())) {
+            try {
+                method.setAccessible(true);
+            } catch (RuntimeException ex) {
+                // Under JPMS (Java 16+), setAccessible throws InaccessibleObjectException when the entity's
+                // package is not open for reflection. Surface an actionable message instead of the raw error.
+                throw new IllegalStateException(
+                        "Unable to access entity method '" + method.getName() + "' on non-public class '"
+                                + method.getDeclaringClass().getName() + "'. Make the entity class public, or "
+                                + "open its package for reflection (e.g. 'opens' in module-info.java).", ex);
+            }
+        }
+    }
 }

client/src/test/java/com/microsoft/durabletask/TaskEntityTest.java

@@ -42,6 +42,23 @@ protected Class<Integer> getStateType() {
         }
     }
 
+    /** A non-public entity implementation, matching internal feature entities. */
+    private static class PrivateEntity extends AbstractTaskEntity<String> {
+        public String get() {
+            return this.state;
+        }
+
+        @Override
+        protected String initializeState(TaskEntityOperation operation) {
+            return "private-state";
+        }
+
+        @Override
+        protected Class<String> getStateType() {
+            return String.class;
+        }
+    }
+
     /**
      * Entity that accepts a TaskEntityContext as a method parameter.
      */
@@ -247,6 +264,12 @@ void reflectionDispatch_methodWithReturnValue() throws Exception {
         assertEquals(42, result);
     }
 
+    @Test
+    void reflectionDispatch_publicOperationOnPrivateEntityClass() throws Exception {
+        Object result = new PrivateEntity().run(createOperation("get"));
+        assertEquals("private-state", result);
+    }
+
     @Test
     void reflectionDispatch_caseInsensitive() throws Exception {
         CounterEntity entity = new CounterEntity();

exporthistory/README.md

@@ -0,0 +1,125 @@
+# Durable Task Export History (Java)
+
+Durable, resumable export of **terminal orchestration history** to Azure Blob Storage for the Durable Task Java
+SDK — for compliance, audit, and offline analysis before instances age out of the task hub.
+
+This module is at parity with the .NET `Microsoft.DurableTask.ExportHistory` (preview) feature: a checkpointed
+entity + orchestrator that pages terminal instances by completion window, fans out per-instance export activities,
+and uploads serialized history (gzipped JSONL by default) to a customer-owned blob container.
+
+> **Status:** preview (`0.1.0`).
+
+## Install
+
+Add the module dependency alongside the core `client` (and your Durable Task Scheduler extension):
+
+```groovy
+implementation 'com.microsoft:durabletask-exporthistory:0.1.0'
+```
+
+The export activities upload to Azure Blob Storage via `azure-storage-blob`. If you authenticate with a managed
+identity, also add `com.azure:azure-identity` to your application.
+
+## Usage
+
+```java
+// Storage destination for exported history (Azure Blob)
+ExportHistoryStorageOptions storage = new ExportHistoryStorageOptions()
+    .setConnectionString(System.getenv("EXPORT_HISTORY_STORAGE_CONNECTION_STRING"))
+    .setContainerName("orchestration-history")
+    .setPrefix("exports/");                  // optional
+    // identity alt: .setAccountUri(uri).setCredential(new DefaultAzureCredentialBuilder().build())
+
+// Build a client first — the export activities need a client to the same backend.
+DurableTaskGrpcClientBuilder clientBuilder = new DurableTaskGrpcClientBuilder();
+DurableTaskSchedulerClientExtensions.useDurableTaskScheduler(clientBuilder, dtsConn);
+DurableTaskClient client = clientBuilder.build();
+
+// Worker: register the export entity + orchestrators + activities (uploads run here).
+DurableTaskGrpcWorkerBuilder workerBuilder = new DurableTaskGrpcWorkerBuilder();
+DurableTaskSchedulerWorkerExtensions.useDurableTaskScheduler(workerBuilder, dtsConn);
+ExportHistoryWorkerExtensions.useExportHistory(workerBuilder, storage, client);
+
+// Client: obtain an ExportHistoryClient bound to the destination.
+ExportHistoryClient export = ExportHistoryClientExtensions.useExportHistory(client, storage);
+
+// Create a job: archive everything completed in a window.
+ExportHistoryJobClient job = export.createJob(new ExportJobCreationOptions("nightly-archive")
+    .setMode(ExportMode.BATCH)
+    .setCompletedTimeFrom(Instant.parse("2026-06-01T00:00:00Z"))
+    .setCompletedTimeTo(Instant.parse("2026-06-25T00:00:00Z"))
+    .setRuntimeStatus(List.of(OrchestrationRuntimeStatus.COMPLETED))
+    .setMaxInstancesPerBatch(200));          // 1–1000, default 100
+
+// Inspect progress.
+ExportJobDescription d = job.describe();
+System.out.println(d.getStatus() + " exported=" + d.getExportedInstances());
+```
+
+### Modes
+
+- **BATCH** — exports a fixed completion-time window and completes. Requires `completedTimeFrom` and
+  `completedTimeTo` (the upper bound must not be in the future).
+- **CONTINUOUS** — tails newly-completed terminal instances on a 1-minute idle loop until the job is deleted.
+
+### Terminal statuses only
+
+Export supports terminal orchestration statuses only: `COMPLETED`, `FAILED`, `TERMINATED`. When no status filter is
+supplied, all three are exported.
+
+## Required settings
+
+- **DTS connection** — the one your app already uses; no new value.
+- **Blob destination** — a container name plus either a storage **connection string** or **identity**
+  (`AccountUri` + `TokenCredential`). Prefix and format (JSONL + gzip) are optional with defaults. The storage
+  secret is held worker-side, not persisted in task-hub state.
+- **Permissions** — the storage credential needs blob write on the container; the DTS credential needs
+  orchestration read.
+
+## Export format
+
+Each blob holds the instance's full history, and the **blob body is byte-for-byte identical to the .NET
+`Microsoft.DurableTask.ExportHistory` output** (pinned by a test against golden output captured from
+`Microsoft.Azure.DurableTask.Core`):
+
+- **JSONL** (default, gzipped) is one JSON object per line; **JSON** is a single array.
+- Each event is `{"eventType": "...", <type-specific fields>, "eventId": N, "isPlayed": false, "timestamp": "..."}`.
+- camelCase field names, null fields omitted, empty maps as `{}`, enum values in PascalCase (e.g. `"Completed"`),
+  timestamps as trimmed ISO-8601 ending in `Z`, and the same HTML-safe string escaping (`"` → `\u0022`,
+  `& < > ' +` and all non-ASCII → `\uXXXX`).
+
+Blob **names**: a lowercase-hex SHA-256 of `"<completedTimestamp>|<instanceId>"` plus the format extension.
+
+## Backend requirement
+
+The export feature relies on the `ListInstanceIds` and `StreamInstanceHistory` gRPC operations. Managed DTS serves
+both; the emulator / self-hosted sidecar needs **≥ v0.4.22**. Against an older backend, a raw gRPC `UNIMPLEMENTED`
+surfaces (matching .NET).
+
+## Validating the export
+
+Locally, with the DTS emulator and Azurite:
+
+1. Start the backends:
+   ```
+   docker run --name durabletask-emulator -p 4001:8080 -d mcr.microsoft.com/dts/dts-emulator:latest
+   docker run --name azurite -p 10000:10000 -d mcr.microsoft.com/azure-storage/azurite azurite-blob --blobHost 0.0.0.0
+   ```
+2. Point the app at them: DTS connection `Endpoint=http://localhost:4001;Authentication=None`, storage = the Azurite
+   dev connection string, container `orchestration-history`.
+3. Run an orchestration to a terminal state, then create a `BATCH` export job whose window covers its completion time.
+4. Confirm the job reaches `COMPLETED` and inspect progress:
+   ```java
+   ExportJobDescription d = job.describe();
+   // d.getStatus() == ExportJobStatus.COMPLETED, d.getExportedInstances() >= 1
+   ```
+5. Download the blob from the container (gunzip for JSONL) and inspect it. Every line carries an `eventType`
+   discriminator, `isPlayed:false`, and a trailing `timestamp`.
+
+## Sample
+
+See [`HistoryExportSample`](../samples/src/main/java/io/durabletask/samples/HistoryExportSample.java):
+
+```
+./gradlew :samples:runHistoryExportSample
+```

exporthistory/build.gradle

@@ -0,0 +1,173 @@
+plugins {
+    id 'java-library'
+    id 'maven-publish'
+    id 'signing'
+    id 'com.github.spotbugs' version '6.4.8'
+}
+
+group 'com.microsoft'
+version = '0.1.0'
+archivesBaseName = 'durabletask-exporthistory'
+
+def grpcVersion = '1.78.0'
+def azureCoreVersion = '1.57.1'
+def azureStorageBlobVersion = '12.29.1'
+
+// Java 11 is used to compile and run all tests. Set the JDK_11 env var to your
+// local JDK 11 home directory, e.g. C:/Program Files/Java/openjdk-11.0.12_7/
+// If unset, falls back to the current JDK running Gradle.
+def rawJdkPath = System.env.JDK_11 ?: System.getProperty("java.home")
+def PATH_TO_TEST_JAVA_RUNTIME = rawJdkPath
+if (rawJdkPath != null) {
+    def f = new File(rawJdkPath)
+    if (f.isFile()) {
+        PATH_TO_TEST_JAVA_RUNTIME = f.parentFile.parentFile.absolutePath
+    }
+}
+def isWindows = System.getProperty("os.name").toLowerCase().contains("win")
+def exeSuffix = isWindows ? ".exe" : ""
+
+dependencies {
+    api project(':client')
+
+    // Azure Storage Blobs — export destination for serialized history.
+    implementation "com.azure:azure-storage-blob:${azureStorageBlobVersion}"
+
+    // TokenCredential abstraction (from azure-core) — 'api' because
+    // ExportHistoryStorageOptions exposes TokenCredential in its public API.
+    api "com.azure:azure-core:${azureCoreVersion}"
+
+    // gRPC API (used by the export activities that call the client wrappers).
+    implementation "io.grpc:grpc-api:${grpcVersion}"
+    implementation "io.grpc:grpc-protobuf:${grpcVersion}"
+    implementation "io.grpc:grpc-stub:${grpcVersion}"
+
+    // NOTE: azure-identity is NOT included here. Users who need
+    // DefaultAzureCredential should add it to their own project.
+
+    testImplementation 'org.mockito:mockito-core:5.21.0'
+    testImplementation 'org.mockito:mockito-junit-jupiter:5.21.0'
+    testImplementation project(':azuremanaged')
+}
+
+compileJava {
+    sourceCompatibility = JavaVersion.VERSION_1_8
+    targetCompatibility = JavaVersion.VERSION_1_8
+}
+compileTestJava {
+    sourceCompatibility = JavaVersion.VERSION_11
+    targetCompatibility = JavaVersion.VERSION_11
+    options.fork = true
+    options.forkOptions.executable = "${PATH_TO_TEST_JAVA_RUNTIME}/bin/javac${exeSuffix}"
+}
+
+tasks.withType(Test) {
+    executable = new File("${PATH_TO_TEST_JAVA_RUNTIME}", "bin/java${exeSuffix}")
+}
+
+test {
+    useJUnitPlatform {
+        // Skip tests tagged as "integration" since those require
+        // external dependencies (DTS emulator + Azurite).
+        excludeTags "integration"
+    }
+}
+
+// Integration tests require DTS emulator (default localhost:4001) and Azurite on localhost:10000.
+task integrationTest(type: Test) {
+    useJUnitPlatform {
+        includeTags 'integration'
+    }
+    dependsOn build
+    shouldRunAfter test
+    testLogging.showStandardStreams = true
+    ignoreFailures = false
+}
+
+spotbugs {
+    toolVersion = '4.9.8'
+    effort = com.github.spotbugs.snom.Effort.valueOf('MAX')
+    reportLevel = com.github.spotbugs.snom.Confidence.valueOf('HIGH')
+    ignoreFailures = true
+}
+
+spotbugsMain {
+    reports {
+        html {
+            required = true
+            stylesheet = 'fancy-hist.xsl'
+        }
+        xml {
+            required = true
+        }
+    }
+}
+
+spotbugsTest {
+    reports {
+        html {
+            required = true
+            stylesheet = 'fancy-hist.xsl'
+        }
+        xml {
+            required = true
+        }
+    }
+}
+
+publishing {
+    repositories {
+        maven {
+            url "file://$project.rootDir/repo"
+        }
+    }
+    publications {
+        mavenJava(MavenPublication) {
+            from components.java
+            artifactId = archivesBaseName
+            pom {
+                name = 'Durable Task Export History for Java'
+                description = 'This package provides durable export of terminal orchestration history to Azure Blob Storage for the Durable Task Java SDK.'
+                url = "https://github.com/microsoft/durabletask-java/tree/main/exporthistory"
+                licenses {
+                    license {
+                        name = "MIT License"
+                        url = "https://opensource.org/licenses/MIT"
+                        distribution = "repo"
+                    }
+                }
+                developers {
+                    developer {
+                        id = "Microsoft"
+                        name = "Microsoft Corporation"
+                    }
+                }
+                scm {
+                    connection = "scm:git:https://github.com/microsoft/durabletask-java"
+                    developerConnection = "scm:git:git@github.com:microsoft/durabletask-java"
+                    url = "https://github.com/microsoft/durabletask-java/tree/main/exporthistory"
+                }
+                withXml {
+                    project.configurations.compileOnly.allDependencies.each { dependency ->
+                        asNode().dependencies[0].appendNode("dependency").with {
+                            it.appendNode("groupId", dependency.group)
+                            it.appendNode("artifactId", dependency.name)
+                            it.appendNode("version", dependency.version)
+                            it.appendNode("scope", "provided")
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+signing {
+    required = !project.hasProperty("skipSigning")
+    sign publishing.publications.mavenJava
+}
+
+java {
+    withSourcesJar()
+    withJavadocJar()
+}