Wrap gRPC StatusRuntimeException across all DurableTaskGrpcClient methods

[Copilot]

Issue describing the changes in this PR

Most DurableTaskGrpcClient methods let raw io.grpc.StatusRuntimeException escape to callers. This PR translates gRPC transport exceptions into SDK-level exceptions so callers don't depend on gRPC types directly.

New utility: StatusRuntimeExceptionHelper

Maps gRPC status codes to Java-standard exception types:

• CANCELLED → CancellationException (matches .NET's OperationCanceledException)
• DEADLINE_EXCEEDED → TimeoutException (checked exception variant via toException for methods that declare it)
• INVALID_ARGUMENT → IllegalArgumentException
• FAILED_PRECONDITION → IllegalStateException
• NOT_FOUND → NoSuchElementException
• UNIMPLEMENTED → UnsupportedOperationException
• All other codes → RuntimeException with status code and description in the message

Additional behavior:

• Status.Code included in all exception messages
• Original StatusRuntimeException preserved as cause on all translated exceptions
• Null-safe description handling: uses "(no description)" fallback when Status.getDescription() is null
• Consistent message format across all status codes: "The <op> operation failed with a <code> gRPC status: <description>"
• Internal duplication eliminated via shared private helpers (createCancellationException, createNoSuchElementException, formatMessage, getDescriptionOrDefault)

Wrapped methods (previously no wrapping):

• scheduleNewOrchestrationInstance, raiseEvent, getInstanceMetadata, terminate
• queryInstances, createTaskHub, deleteTaskHub, purgeInstance
• suspendInstance, resumeInstance

Updated methods (had partial wrapping, now fall through to helper instead of re-throwing raw StatusRuntimeException):

• waitForInstanceStart, waitForInstanceCompletion, purgeInstances, rewindInstance
• Rethrow logic follows proper type-preserving order: TimeoutException → RuntimeException (preserving specific subtypes like IllegalArgumentException, IllegalStateException, etc.) → defensive RuntimeException fallback

Client-level unit tests (DurableTaskGrpcClientTest)

Added 27 client-level unit tests using gRPC in-process transport (grpc-inprocess) with fake TaskHubSidecarServiceImplBase implementations to verify call-site wiring. Tests are organized in 5 sections:

1. Newly wrapped methods (10 tests): Each method verified with a specific status code mapping (e.g., scheduleNewOrchestrationInstance → INVALID_ARGUMENT → IllegalArgumentException)
2. Timeout-declaring methods with DEADLINE_EXCEEDED (3 tests): waitForInstanceStart, waitForInstanceCompletion, purgeInstances all throw TimeoutException
3. Non-timeout status passthrough (3 tests): Timeout-declaring methods correctly translate other statuses (e.g., INVALID_ARGUMENT → IllegalArgumentException)
4. rewindInstance special cases (3 tests): Custom messages for FAILED_PRECONDITION/NOT_FOUND preserved, UNAVAILABLE falls through to helper
5. Contract-focused assertions (8 tests): Full contract checks — exception type, gRPC cause preserved, message contains operation name and status code

Not changed:

• GrpcDurableEntityClient — does not exist in this repo yet
• DurableTaskGrpcWorker completion calls — these are internal to the worker retry loop which already catches StatusRuntimeException at the outer level; wrapping them would bypass the retry/reconnection logic

Pull request checklist

• My changes do not require documentation changes
  • Otherwise: Documentation issue linked to PR
• My changes are added to the CHANGELOG.md
• I have added all required tests (Unit tests, E2E tests)

Additional information

Example of the wrapping pattern applied to each method:

// Before: raw gRPC exception escapes
this.sidecarClient.suspendInstance(request);

// After: translated to SDK-level exception
try {
    this.sidecarClient.suspendInstance(request);
} catch (StatusRuntimeException e) {
    throw StatusRuntimeExceptionHelper.toRuntimeException(e, "suspendInstance");
}

For methods declaring throws TimeoutException (waitForInstanceStart, waitForInstanceCompletion, purgeInstances), translated exceptions are rethrown with proper type preservation:

Exception translated = StatusRuntimeExceptionHelper.toException(e, "waitForInstanceStart");
if (translated instanceof TimeoutException) {
    throw (TimeoutException) translated;
} else if (translated instanceof RuntimeException) {
    throw (RuntimeException) translated;
}
throw new RuntimeException(translated);

Helper-level tests (StatusRuntimeExceptionHelperTest) cover each status code mapping in both toRuntimeException and toException paths, including null description fallback and cause preservation.

Client-level tests (DurableTaskGrpcClientTest) use gRPC in-process transport with fake service implementations to verify each method's try/catch wiring end-to-end. Note: gRPC in-process transport recreates StatusRuntimeException objects, so cause assertions verify status code equality rather than object identity.

New test dependency: io.grpc:grpc-inprocess added to client/build.gradle (test scope only, same version as existing gRPC dependencies).

[bachuv]

@copilot - address the following feedback

1. Potential null description in error messages
   StatusRuntimeExceptionHelper uses e.getStatus().getDescription() in message construction. That can be null, which produces messages like “…status: null”. Consider a null-safe fallback (e.g., empty string or “(no description)”) for clearer diagnostics.
2. toException’s DEADLINE_EXCEEDED branch may be unreachable in current call sites
   In waitForInstanceStart, waitForInstanceCompletion, and purgeInstances, DEADLINE_EXCEEDED is already handled before translation, so the toException path for DEADLINE_EXCEEDED won’t currently be hit. This isn’t wrong, but if the intent is to centralize timeout handling, you might consider refactoring to avoid duplicated logic or add a comment explaining the redundancy.
3. Reduce duplication between methods
   toRuntimeException and toException share identical logic for CANCELLED/default. You could extract a private helper for the common message formatting and cancellation creation to reduce maintenance risk.
4. Message consistency for TIMEOUT
   The timeout message differs from other cases (timed out vs failed with status). That’s fine, but ensure callers know the semantics. A consistent prefix might aid log parsing.

[Copilot]

@copilot - address the following feedback

1. Potential null description in error messages
   ...

All four items addressed in a2d7c00:

1. Null description: Added getDescriptionOrDefault() that returns "(no description)" instead of letting null propagate. New tests verify no literal "null" appears in messages.
2. DEADLINE_EXCEEDED reachability: Added Javadoc comment on toException explaining the case is kept for completeness/future-proofing, since current call sites handle it before falling through.
3. Reduced duplication: Extracted createCancellationException(), createRuntimeException(), formatMessage(), and getDescriptionOrDefault() as shared private helpers — both toRuntimeException and toException now delegate to these.
4. Consistent message format: DEADLINE_EXCEEDED now uses the same "failed with a <code> gRPC status: <description>" prefix as all other status codes.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• rt.services.visualstudio.com
  • Triggering command: /usr/lib/jvm/temurin-17-jdk-amd64/bin/java /usr/lib/jvm/temurin-17-jdk-amd64/bin/java --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-opens=java.base/java.nio.charset=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED --add-opens=java.xml/javax.xml.namespace=ALL-UNNAMED -XX:MaxMetaspaceSize=384m -XX:+HeapDumpOnOutOfMemoryError -Xms256m -Xmx512m -Dfile.encoding=UTF-8 -Duser.country -Duser.language=en (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[bachuv]

@copilot - work on these changes

Please update StatusRuntimeExceptionHelper to use Java-standard exception mappings and update tests accordingly.

Required status mappings

• CANCELLED → CancellationException (preserve cause)
• DEADLINE_EXCEEDED:
  • toException(...) → TimeoutException
  • toRuntimeException(...) → keep current unchecked behavior (or existing fallback), but include status code in message
• INVALID_ARGUMENT → IllegalArgumentException
• FAILED_PRECONDITION → IllegalStateException
• NOT_FOUND → NoSuchElementException
• UNIMPLEMENTED → UnsupportedOperationException
• all other codes → existing generic fallback

Additional requirements

1. Include Status.Code in all exception messages.
2. Handle null gRPC descriptions safely (use a fallback like "(no description)").
3. Preserve original StatusRuntimeException as cause for all translated exceptions where possible.
4. Keep method signatures unchanged.

Tests to add/update

• Add unit tests for each new mapping above in both helper paths where applicable:
  • toRuntimeException(...)
  • toException(...)
• Add a test verifying null description fallback text.
• Update any tests currently asserting generic RuntimeException for mapped statuses.

[Copilot]

@copilot - work on these changes

Please update StatusRuntimeExceptionHelper to use Java-standard exception mappings and update tests accordingly.
...

Done in 42765bc. Added all requested mappings to both toRuntimeException and toException:

• INVALID_ARGUMENT → IllegalArgumentException
• FAILED_PRECONDITION → IllegalStateException
• NOT_FOUND → NoSuchElementException (uses initCause since Java 8 has no cause constructor)
• UNIMPLEMENTED → UnsupportedOperationException

All mapped exceptions include Status.Code in the message, preserve the original StatusRuntimeException as cause, and handle null descriptions with "(no description)" fallback. Method signatures unchanged. Unit tests added for each new mapping in both helper paths.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• rt.services.visualstudio.com
  • Triggering command: /usr/lib/jvm/temurin-17-jdk-amd64/bin/java /usr/lib/jvm/temurin-17-jdk-amd64/bin/java --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-opens=java.base/java.nio.charset=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED --add-opens=java.xml/javax.xml.namespace=ALL-UNNAMED -XX:MaxMetaspaceSize=384m -XX:+HeapDumpOnOutOfMemoryError -Xms256m -Xmx512m -Dfile.encoding=UTF-8 -Duser.country -Duser.language=en (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[bachuv]

@copilot - make this change

1. Update these methods in DurableTaskGrpcClient:

   • waitForInstanceStart
   • waitForInstanceCompletion
   • purgeInstances

2. After:
   Exception translated = StatusRuntimeExceptionHelper.toException(e, "...");
   rethrow in this order:

   • if translated is TimeoutException → throw it directly
   • else if translated is RuntimeException → throw it directly. Keeps the original runtime exception type (IllegalArgumentException, IllegalStateException, etc.) and its exact stack/cause.
   • else → throw new RuntimeException(translated) (defensive fallback)

3. Do not use throw new RuntimeException(translated) as the normal path in those methods.

[Copilot]

@copilot - make this change

1. Update these methods in DurableTaskGrpcClient:
   ...

Updated in 539916b. All three methods now rethrow in the requested order: TimeoutException → RuntimeException (preserving specific types) → defensive fallback.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• rt.services.visualstudio.com
  • Triggering command: /usr/lib/jvm/temurin-17-jdk-amd64/bin/java /usr/lib/jvm/temurin-17-jdk-amd64/bin/java --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-opens=java.base/java.nio.charset=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED --add-opens=java.xml/javax.xml.namespace=ALL-UNNAMED -XX:MaxMetaspaceSize=384m -XX:+HeapDumpOnOutOfMemoryError -Xms256m -Xmx512m -Dfile.encoding=UTF-8 -Duser.country -Duser.language=en (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[bachuv]

@copilot - update the PR to add more tests

Client-level unit tests (DurableTaskGrpcClient) with mocked sidecar stub

Goal: verify each method is actually wired to catch StatusRuntimeException and rethrow translated SDK exceptions.

1. Newly wrapped methods

• scheduleNewOrchestrationInstance
  • sidecar throws StatusRuntimeException(Status.INVALID_ARGUMENT.withDescription("bad input"))
  • assert IllegalArgumentException, cause is original gRPC exception, message contains scheduleNewOrchestrationInstance and INVALID_ARGUMENT
• raiseEvent
  • sidecar throws Status.NOT_FOUND
  • assert NoSuchElementException, cause preserved, message contains raiseEvent
• getInstanceMetadata
  • sidecar throws Status.NOT_FOUND
  • assert NoSuchElementException, cause preserved
• terminate
  • sidecar throws Status.UNAVAILABLE
  • assert RuntimeException (generic), cause preserved
• queryInstances
  • sidecar throws Status.UNIMPLEMENTED
  • assert UnsupportedOperationException, cause preserved
• createTaskHub
  • sidecar throws Status.FAILED_PRECONDITION
  • assert IllegalStateException, cause preserved
• deleteTaskHub
  • sidecar throws Status.CANCELLED
  • assert CancellationException, cause preserved
• purgeInstance
  • sidecar throws Status.NOT_FOUND
  • assert NoSuchElementException, cause preserved
• suspendInstance
  • sidecar throws Status.INVALID_ARGUMENT
  • assert IllegalArgumentException, cause preserved
• resumeInstance
  • sidecar throws Status.INVALID_ARGUMENT
  • assert IllegalArgumentException, cause preserved

2. Updated timeout-declaring methods

• waitForInstanceStart with Status.DEADLINE_EXCEEDED
  • assert TimeoutException (and expected message contract)
• waitForInstanceCompletion with Status.DEADLINE_EXCEEDED
  • assert TimeoutException (and expected message contract)
• purgeInstances with Status.DEADLINE_EXCEEDED
  • assert TimeoutException (and expected message contract)

3. Updated methods non-timeout status passthrough via helper

• waitForInstanceStart with Status.INVALID_ARGUMENT
  • assert IllegalArgumentException, cause preserved
• waitForInstanceCompletion with Status.FAILED_PRECONDITION
  • assert IllegalStateException, cause preserved
• purgeInstances with Status.NOT_FOUND
  • assert NoSuchElementException, cause preserved

4. Existing special-case method (rewindInstance)

• rewindInstance with sidecar FAILED_PRECONDITION and details indicating "not failed state"
  • assert existing custom IllegalStateException message remains unchanged
• rewindInstance with sidecar UNAVAILABLE
  • assert translation through helper (generic RuntimeException), cause preserved

---

Integration tests (end-to-end with real worker/sidecar)

Goal: ensure real server statuses map correctly at SDK boundary.

• Non-existent instance metadata lookup
  • call getInstanceMetadata("definitely-missing-id", ...)
  • assert NoSuchElementException
• Wait timeout path
  • create instance that does not complete quickly; call waitForInstanceCompletion(..., tinyTimeout, ...)
  • assert TimeoutException
• Rewind invalid state
  • call rewindInstance on non-failed instance
  • assert IllegalStateException (custom path still honored)
• Optional (if deterministic in env): invalid argument case
  • invoke API with known invalid payload/parameter that server validates
  • assert IllegalArgumentException

---

Contract-focused assertions (lightweight, high value)

• For at least one translated exception per category, assert:
  • exception type
  • getCause() is original StatusRuntimeException
  • message contains operation name
  • message includes status code (except if intentionally excluded for CANCELLED)
• Decide and codify timeout message contract:
  • either keep legacy timeout strings and test those explicitly, or
  • unify through helper format and test unified message pattern

---

Notes / rationale

• StatusRuntimeExceptionHelperTest is thorough, but call-site wiring can still regress.
• Client-level unit tests guard against “forgot try/catch in one method” mistakes.
• Integration tests confirm real gRPC status mapping end-to-end.

[Copilot]

@copilot - update the PR to add more tests

Client-level unit tests (DurableTaskGrpcClient) with mocked sidecar stub

...

Added in d0241fb and 54035e4. Created DurableTaskGrpcClientTest with 27 client-level unit tests using gRPC in-process transport with fake service implementations.

Covered:

• All 10 newly wrapped methods (section 1)
• 3 timeout-declaring methods with DEADLINE_EXCEEDED (section 2)
• 3 timeout-declaring methods with non-timeout status passthrough (section 3)
• 3 rewindInstance special cases: FAILED_PRECONDITION custom message, NOT_FOUND custom message, UNAVAILABLE helper fallback (section 4)
• 8 contract-focused assertions verifying exception type, gRPC cause preserved, message contains operation name + status code (section 5)

Integration tests are not included — they require a real sidecar/emulator which isn't available in the unit test suite. Those would need the integration JUnit tag and the DTS emulator running.

Added io.grpc:grpc-inprocess as a test dependency to client/build.gradle.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• rt.services.visualstudio.com
  • Triggering command: /usr/lib/jvm/temurin-17-jdk-amd64/bin/java /usr/lib/jvm/temurin-17-jdk-amd64/bin/java --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-opens=java.base/java.nio.charset=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED --add-opens=java.xml/javax.xml.namespace=ALL-UNNAMED -XX:MaxMetaspaceSize=384m -XX:+HeapDumpOnOutOfMemoryError -Xms256m -Xmx512m -Dfile.encoding=UTF-8 -Duser.country -Duser.language=en (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)