Now requiring UUID

Author: Evanthx

temporal-sdk/src/main/java/io/temporal/client/NexusServiceClient.java

@@ -50,20 +50,9 @@ static <T> NexusServiceClient<T> newInstance(
   }
 
   /**
-   * Executes an operation synchronously. Equivalent to {@link #start(BiFunction, Object)} followed
-   * by {@link NexusOperationHandle#getResult()}.
-   *
-   * @param operation a method reference on {@code T} identifying the operation
-   * @param input the operation input
-   * @return the operation result
-   * @throws RuntimeException if the operation failed, timed out, or was cancelled
-   */
-  default <U, R> R execute(BiFunction<T, U, R> operation, U input) {
-    return start(operation, input).getResult();
-  }
-
-  /**
-   * Executes an operation synchronously with per-call options.
+   * Executes an operation synchronously with per-call options. The supplied {@link
+   * StartNexusOperationOptions} must have its {@code id} set; the SDK does not generate operation
+   * IDs on the caller's behalf.
    *
    * @param operation a method reference on {@code T} identifying the operation
    * @param input the operation input
@@ -77,18 +66,8 @@ default <U, R> R execute(
   }
 
   /**
-   * Starts an operation and returns a typed handle for tracking its execution.
-   *
-   * @param operation a method reference on {@code T} identifying the operation
-   * @param input the operation input
-   * @return a typed handle bound to the started operation
-   */
-  default <U, R> NexusOperationHandle<R> start(BiFunction<T, U, R> operation, U input) {
-    return start(operation, input, StartNexusOperationOptions.getDefaultInstance());
-  }
-
-  /**
-   * Starts an operation with per-call options and returns a typed handle.
+   * Starts an operation with per-call options and returns a typed handle. The supplied {@link
+   * StartNexusOperationOptions} must have its {@code id} set.
    *
    * @param operation a method reference on {@code T} identifying the operation
    * @param input the operation input
@@ -99,18 +78,9 @@ <U, R> NexusOperationHandle<R> start(
       BiFunction<T, U, R> operation, U input, StartNexusOperationOptions options);
 
   /**
-   * Async variant of {@link #execute(BiFunction, Object)}. Returns a {@link CompletableFuture} that
-   * completes with the typed result, or completes exceptionally if the operation fails.
-   *
-   * @param operation a method reference on {@code T} identifying the operation
-   * @param input the operation input
-   */
-  default <U, R> CompletableFuture<R> executeAsync(BiFunction<T, U, R> operation, U input) {
-    return start(operation, input).getResultAsync();
-  }
-
-  /**
-   * Async variant of {@link #execute(BiFunction, Object, StartNexusOperationOptions)}.
+   * Async variant of {@link #execute(BiFunction, Object, StartNexusOperationOptions)}. Returns a
+   * {@link CompletableFuture} that completes with the typed result, or completes exceptionally if
+   * the operation fails.
    *
    * @param operation a method reference on {@code T} identifying the operation
    * @param input the operation input

temporal-sdk/src/main/java/io/temporal/client/StartNexusOperationOptions.java

@@ -6,6 +6,7 @@
 import io.temporal.common.SearchAttributes;
 import java.time.Duration;
 import java.util.Objects;
+import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
 /**
@@ -23,13 +24,6 @@ public static Builder newBuilder(StartNexusOperationOptions options) {
     return new Builder(options);
   }
 
-  private static final StartNexusOperationOptions DEFAULT_INSTANCE = newBuilder().build();
-
-  /** Returns an options instance with no per-call fields set. */
-  public static StartNexusOperationOptions getDefaultInstance() {
-    return DEFAULT_INSTANCE;
-  }
-
   public static final class Builder {
     private @Nullable String id;
     private @Nullable Duration scheduleToCloseTimeout;
@@ -57,11 +51,11 @@ private Builder(StartNexusOperationOptions options) {
     }
 
     /**
-     * Required. Unique identifier for this operation within its namespace. If left null, the SDK
-     * generates a random UUID.
+     * Required. Unique identifier for this operation within its namespace. Callers must supply this
+     * explicitly; the SDK does not invent one on the caller's behalf.
      */
-    public Builder setId(@Nullable String id) {
-      this.id = id;
+    public Builder setId(@Nonnull String id) {
+      this.id = Objects.requireNonNull(id, "id");
       return this;
     }
 
@@ -108,11 +102,16 @@ public Builder setIdConflictPolicy(@Nullable NexusOperationIdConflictPolicy idCo
     }
 
     public StartNexusOperationOptions build() {
+      if (id == null) {
+        throw new IllegalStateException(
+            "StartNexusOperationOptions.Builder.setId(...) must be called with a non-null id "
+                + "before build(); the SDK does not generate operation IDs.");
+      }
       return new StartNexusOperationOptions(this);
     }
   }
 
-  private final @Nullable String id;
+  private final @Nonnull String id;
   private final @Nullable Duration scheduleToCloseTimeout;
   private final @Nullable Duration scheduleToStartTimeout;
   private final @Nullable Duration startToCloseTimeout;
@@ -136,7 +135,7 @@ public Builder toBuilder() {
     return new Builder(this);
   }
 
-  @Nullable
+  @Nonnull
   public String getId() {
     return id;
   }

temporal-sdk/src/main/java/io/temporal/client/UntypedNexusServiceClientImpl.java

@@ -45,12 +45,7 @@ public UntypedNexusOperationHandle start(
     Payload payload = serializeInput(arg);
     StartNexusOperationExecutionInput input =
         new StartNexusOperationExecutionInput(
-            endpoint,
-            serviceName,
-            operation,
-            payload,
-            options != null ? options : StartNexusOperationOptions.getDefaultInstance(),
-            Collections.emptyMap());
+            endpoint, serviceName, operation, payload, options, Collections.emptyMap());
     StartNexusOperationExecutionOutput output = invoker.startNexusOperationExecution(input);
     return new NexusOperationHandleImpl(
         output.getOperationId(), output.getRunId(), invoker, dataConverter);

temporal-sdk/src/main/java/io/temporal/internal/client/RootNexusClientInvoker.java

@@ -28,6 +28,7 @@
 import io.temporal.internal.common.ProtobufTimeUtils;
 import io.temporal.internal.common.WorkflowExecutionUtils;
 import io.temporal.serviceclient.StatusUtils;
+import java.util.Objects;
 import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.CompletionException;
@@ -53,7 +54,8 @@ public RootNexusClientInvoker(
   public StartNexusOperationExecutionOutput startNexusOperationExecution(
       StartNexusOperationExecutionInput input) {
     StartNexusOperationOptions options = input.getOptions();
-    String operationId = options.getId() != null ? options.getId() : UUID.randomUUID().toString();
+    // The builder validates that id is non-null; this is a defense-in-depth assertion.
+    String operationId = Objects.requireNonNull(options.getId(), "StartNexusOperationOptions.id");
     StartNexusOperationExecutionRequest.Builder request =
         StartNexusOperationExecutionRequest.newBuilder()
             .setNamespace(clientOptions.getNamespace())

temporal-sdk/src/test/java/io/temporal/client/nexus/NexusAsyncApiTest.java

@@ -16,6 +16,7 @@
 import io.temporal.workflow.shared.TestNexusServices;
 import io.temporal.workflow.shared.TestWorkflows;
 import java.time.Duration;
+import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.TimeUnit;
@@ -53,7 +54,8 @@ public static void requireServerWithStandaloneNexusSupport() {
   public void serviceClientExecuteAsyncReturnsResult() throws Exception {
     String result =
         buildServiceClient()
-            .executeAsync(TestNexusServices.TestNexusService1::operation, "hello")
+            .executeAsync(
+                TestNexusServices.TestNexusService1::operation, "hello", newOptionsWithId())
             .get(FUTURE_GET_TIMEOUT.getSeconds(), TimeUnit.SECONDS);
 
     Assert.assertEquals("echo:hello", result);
@@ -63,6 +65,7 @@ public void serviceClientExecuteAsyncReturnsResult() throws Exception {
   public void serviceClientExecuteAsyncWithOptionsReturnsResult() throws Exception {
     StartNexusOperationOptions options =
         StartNexusOperationOptions.newBuilder()
+            .setId(UUID.randomUUID().toString())
             .setScheduleToCloseTimeout(Duration.ofSeconds(30))
             .build();
 
@@ -79,7 +82,8 @@ public void serviceClientExecuteAsyncWithOptionsReturnsResult() throws Exception
   @Test
   public void typedHandleGetResultAsyncReturnsResult() throws Exception {
     NexusOperationHandle<String> handle =
-        buildServiceClient().start(TestNexusServices.TestNexusService1::operation, "typed");
+        buildServiceClient()
+            .start(TestNexusServices.TestNexusService1::operation, "typed", newOptionsWithId());
 
     String result = handle.getResultAsync().get(FUTURE_GET_TIMEOUT.getSeconds(), TimeUnit.SECONDS);
 
@@ -89,7 +93,8 @@ public void typedHandleGetResultAsyncReturnsResult() throws Exception {
   @Test
   public void typedHandleGetResultAsyncWithTimeoutReturnsResult() throws Exception {
     NexusOperationHandle<String> handle =
-        buildServiceClient().start(TestNexusServices.TestNexusService1::operation, "typed-tm");
+        buildServiceClient()
+            .start(TestNexusServices.TestNexusService1::operation, "typed-tm", newOptionsWithId());
 
     String result =
         handle
@@ -156,7 +161,8 @@ public void executeAsyncPropagatesOperationFailure() throws Exception {
         buildServiceClient()
             .executeAsync(
                 TestNexusServices.TestNexusService1::operation,
-                EchoNexusServiceImpl.FAIL_PREFIX + "boom");
+                EchoNexusServiceImpl.FAIL_PREFIX + "boom",
+                newOptionsWithId());
 
     try {
       future.get(FUTURE_GET_TIMEOUT.getSeconds(), TimeUnit.SECONDS);
@@ -207,7 +213,12 @@ private UntypedNexusOperationHandle startUntyped(String input) {
         client.newUntypedNexusServiceClient(
             endpoint.getSpec().getName(),
             TestNexusServices.TestNexusService1.class.getSimpleName());
-    return svcClient.start("operation", StartNexusOperationOptions.newBuilder().build(), input);
+    return svcClient.start("operation", newOptionsWithId(), input);
+  }
+
+  /** Builds a minimal {@link StartNexusOperationOptions} with a unique id. */
+  private static StartNexusOperationOptions newOptionsWithId() {
+    return StartNexusOperationOptions.newBuilder().setId(UUID.randomUUID().toString()).build();
   }
 
   public static class PlaceholderWorkflowImpl implements TestWorkflows.TestWorkflow1 {

temporal-sdk/src/test/java/io/temporal/client/nexus/NexusClientTest.java

@@ -82,6 +82,7 @@ public void runStandaloneNexusOperation() throws Exception {
             TestNexusServices.TestNexusService1.class.getSimpleName());
     StartNexusOperationOptions opts =
         StartNexusOperationOptions.newBuilder()
+            .setId(UUID.randomUUID().toString())
             .setScheduleToCloseTimeout(Duration.ofSeconds(30))
             .build();
     UntypedNexusOperationHandle handle = svcClient.start("operation", opts, inputValue);
@@ -161,6 +162,7 @@ private String startAndAwaitSyncOperation(String label) throws Exception {
                 TestNexusServices.TestNexusService1.class.getSimpleName());
     StartNexusOperationOptions opts =
         StartNexusOperationOptions.newBuilder()
+            .setId(UUID.randomUUID().toString())
             .setScheduleToCloseTimeout(Duration.ofSeconds(30))
             .build();
     UntypedNexusOperationHandle handle =
@@ -184,6 +186,7 @@ public void untypedExecuteByClassReturnsResult() {
             "operation",
             String.class,
             StartNexusOperationOptions.newBuilder()
+                .setId(UUID.randomUUID().toString())
                 .setScheduleToCloseTimeout(Duration.ofSeconds(30))
                 .build(),
             "untyped-exec");
@@ -209,6 +212,7 @@ public void untypedExecuteByClassAndTypeReturnsResult() {
             String.class,
             String.class,
             StartNexusOperationOptions.newBuilder()
+                .setId(UUID.randomUUID().toString())
                 .setScheduleToCloseTimeout(Duration.ofSeconds(30))
                 .build(),
             "untyped-exec-typed");

temporal-sdk/src/test/java/io/temporal/client/nexus/NexusOperationHandleTest.java

@@ -254,6 +254,7 @@ private UntypedNexusOperationHandle startOperation(
             TestNexusServices.TestNexusService1.class.getSimpleName());
     StartNexusOperationOptions opts =
         StartNexusOperationOptions.newBuilder()
+            .setId(UUID.randomUUID().toString())
             .setScheduleToCloseTimeout(Duration.ofSeconds(30))
             .build();
     UntypedNexusOperationHandle handle = svcClient.start("operation", opts, inputValue);

temporal-sdk/src/test/java/io/temporal/client/nexus/NexusServiceClientTest.java

@@ -42,7 +42,8 @@ public void executeReturnsTypedResult() {
     NexusServiceClient<TestNexusServices.TestNexusService1> client =
         buildServiceClient(testWorkflowRule.getNexusEndpoint());
 
-    String result = client.execute(TestNexusServices.TestNexusService1::operation, "hello");
+    String result =
+        client.execute(TestNexusServices.TestNexusService1::operation, "hello", newOptionsWithId());
 
     Assert.assertEquals("echo:hello", result);
   }
@@ -53,18 +54,19 @@ public void startReturnsTypedHandleAndPollsResult() {
         buildServiceClient(testWorkflowRule.getNexusEndpoint());
 
     NexusOperationHandle<String> handle =
-        client.start(TestNexusServices.TestNexusService1::operation, "world");
+        client.start(TestNexusServices.TestNexusService1::operation, "world", newOptionsWithId());
 
     Assert.assertNotNull(handle.getNexusOperationId());
     Assert.assertEquals("echo:world", handle.getResult());
   }
 
   @Test
   public void executeWithOptionsReturnsResult() {
-    // Covers the 3-arg execute(op, input, options) overload — the no-options variant is already
-    // covered by executeReturnsTypedResult.
+    // Covers the 3-arg execute(op, input, options) overload — exercises a non-default
+    // scheduleToCloseTimeout in addition to the required id.
     StartNexusOperationOptions options =
         StartNexusOperationOptions.newBuilder()
+            .setId(UUID.randomUUID().toString())
             .setScheduleToCloseTimeout(Duration.ofSeconds(30))
             .build();
 
@@ -102,7 +104,10 @@ public void clientSummaryReachesServer() {
         buildServiceClient(testWorkflowRule.getNexusEndpoint());
 
     StartNexusOperationOptions startOptions =
-        StartNexusOperationOptions.newBuilder().setSummary("per-call-summary").build();
+        StartNexusOperationOptions.newBuilder()
+            .setId(UUID.randomUUID().toString())
+            .setSummary("per-call-summary")
+            .build();
     NexusOperationHandle<String> handle =
         client.start(TestNexusServices.TestNexusService1::operation, "world", startOptions);
 
@@ -121,6 +126,11 @@ public void clientSummaryReachesServer() {
   // attribute" until the namespace's Visibility index catches up. Reintroduce once the rule
   // (or the test) synchronously waits for the mapping to propagate.
 
+  /** Builds a minimal {@link StartNexusOperationOptions} with a unique id. */
+  private static StartNexusOperationOptions newOptionsWithId() {
+    return StartNexusOperationOptions.newBuilder().setId(UUID.randomUUID().toString()).build();
+  }
+
   private NexusServiceClient<TestNexusServices.TestNexusService1> buildServiceClient(
       Endpoint endpoint) {
     return NexusServiceClient.newInstance(