Add getRandomStream and isSubjectToReplay

CHANGELOG.md

@@ -27,6 +27,10 @@ to docs, or any other relevant information.
   Child workflow overrides and one-time routing require Temporal Server 1.32.0 or later.
 - `WorkerFactoryOptions.Builder.setLoggerTagPrefix` that can be used to customized structured logging tags (MDC keys)
   set by Temporal SDK in worker context.
+- Added experimental `Workflow.getRandomStream(String name)`, which returns a deterministic pseudorandom stream private
+  to the given name.
+- Added experimental `WorkflowUnsafe.isSubjectToReplay()`, which reports whether the calling code is re-executed on
+  replay.
 
 ### Changed
 - Release notes for all future releases are now in a single CHANGELOG.md file. `releases` directory with old release

temporal-sdk/src/main/java/io/temporal/internal/replay/ReplayWorkflowContext.java

@@ -293,6 +293,9 @@ Integer getVersion(
   /** Replay safe random. */
   Random newRandom();
 
+  /** Replay safe named random stream. */
+  Random getRandomStream(String name);
+
   /**
    * @return scope to be used for metrics reporting.
    */

temporal-sdk/src/main/java/io/temporal/internal/replay/ReplayWorkflowContextImpl.java

@@ -82,6 +82,11 @@ public Random newRandom() {
     return workflowStateMachines.newRandom();
   }
 
+  @Override
+  public Random getRandomStream(String name) {
+    return workflowStateMachines.getRandomStream(name);
+  }
+
   @Override
   public Scope getMetricsScope() {
     return replayAwareWorkflowMetricsScope;
@@ -351,9 +356,11 @@ public Integer getVersion(
             : (min, max) ->
                 WorkflowInternal.readOnly(
                     () ->
-                        preferredVersionProvider.getPreferredVersion(
-                            new PreferredVersionProviderInput(
-                                WorkflowInternal.getWorkflowInfo(), changeId, min, max))),
+                        WorkflowInternal.notSubjectToReplay(
+                            () ->
+                                preferredVersionProvider.getPreferredVersion(
+                                    new PreferredVersionProviderInput(
+                                        WorkflowInternal.getWorkflowInfo(), changeId, min, max)))),
         callback);
   }
 

temporal-sdk/src/main/java/io/temporal/internal/statemachines/WorkflowRandomStreams.java

@@ -0,0 +1,31 @@
+package io.temporal.internal.statemachines;
+
+import com.google.common.hash.HashCode;
+import com.google.common.hash.Hashing;
+import java.nio.ByteBuffer;
+import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Random;
+import javax.annotation.Nonnull;
+
+final class WorkflowRandomStreams {
+  private static final String SEED_VERSION = "temporal.sdk.random.v1";
+
+  private final Map<String, Random> streams = new HashMap<>();
+
+  long deriveSeed(@Nonnull String runId, @Nonnull String name) {
+    // The separators keep ("ab", "c") from colliding with ("a", "bc")
+    String seed = String.join("\0", SEED_VERSION, runId, name);
+    HashCode hash = Hashing.sha256().hashString(seed, StandardCharsets.UTF_8);
+    return ByteBuffer.wrap(hash.asBytes()).getLong();
+  }
+
+  Random get(@Nonnull String runId, @Nonnull String name) {
+    return streams.computeIfAbsent(name, key -> new Random(deriveSeed(runId, key)));
+  }
+
+  void reseed(@Nonnull String runId) {
+    streams.forEach((name, stream) -> stream.setSeed(deriveSeed(runId, name)));
+  }
+}

temporal-sdk/src/main/java/io/temporal/internal/statemachines/WorkflowStateMachines.java

@@ -115,6 +115,8 @@ enum HandleEventStatus {
   /** Used Workflow.newRandom and randomUUID together with currentRunId. */
   private long idCounter;
 
+  private final WorkflowRandomStreams randomStreams = new WorkflowRandomStreams();
+
   /** Current workflow time. */
   private long currentTimeMillis = -1;
 
@@ -1195,6 +1197,11 @@ public Random newRandom() {
     return new Random(randomUUID().getLeastSignificantBits());
   }
 
+  public Random getRandomStream(String name) {
+    checkEventLoopExecuting();
+    return randomStreams.get(currentRunId, name);
+  }
+
   public void sideEffect(
       Functions.Func<Optional<Payloads>> func,
       UserMetadata userMetadata,
@@ -1548,6 +1555,7 @@ public void workflowTaskStarted(
     @Override
     public void updateRunId(String currentRunId) {
       WorkflowStateMachines.this.currentRunId = currentRunId;
+      randomStreams.reseed(currentRunId);
     }
   }
 

temporal-sdk/src/main/java/io/temporal/internal/sync/QueryDispatcher.java

@@ -99,6 +99,7 @@ public Optional<Payloads> handleQuery(
     }
     try {
       replayContext.setReadOnly(true);
+      replayContext.setSubjectToReplay(false);
       queryHandlerWorkflowContext.set(replayContext);
       Object result =
           inboundCallsInterceptor
@@ -107,6 +108,7 @@ public Optional<Payloads> handleQuery(
       return dataConverterWithWorkflowContext.toPayloads(result);
     } finally {
       replayContext.setReadOnly(false);
+      replayContext.setSubjectToReplay(true);
       queryHandlerWorkflowContext.set(null);
     }
   }

temporal-sdk/src/main/java/io/temporal/internal/sync/SyncWorkflow.java

@@ -159,6 +159,7 @@ public void handleUpdate(
             if (!callbacks.isReplaying()) {
               try {
                 workflowContext.setReadOnly(true);
+                workflowContext.setSubjectToReplay(false);
                 workflowProc.handleValidateUpdate(updateName, updateId, input, eventId, header);
               } catch (ReadOnlyException r) {
                 // Rethrow instead on rejecting the update to fail the WFT
@@ -174,6 +175,7 @@ public void handleUpdate(
                 return;
               } finally {
                 workflowContext.setReadOnly(false);
+                workflowContext.setSubjectToReplay(true);
               }
             }
             callbacks.accept();

temporal-sdk/src/main/java/io/temporal/internal/sync/SyncWorkflowContext.java

@@ -102,6 +102,7 @@ final class SyncWorkflowContext implements WorkflowContext, WorkflowOutboundCall
   private NexusServiceOptions defaultNexusServiceOptions = null;
   private Map<String, NexusServiceOptions> nexusServiceOptionsMap;
   private boolean readOnly = false;
+  private boolean subjectToReplay = true;
   private final WorkflowThreadLocal<UpdateInfo> currentUpdateInfo = new WorkflowThreadLocal<>();
   @Nullable private String currentDetails;
 
@@ -1094,10 +1095,12 @@ public <R> R sideEffect(
           () -> {
             try {
               readOnly = true;
+              subjectToReplay = false;
               R r = func.apply();
               return dataConverterWithCurrentWorkflowContext.toPayloads(r);
             } finally {
               readOnly = false;
+              subjectToReplay = true;
             }
           },
           userMetadata,
@@ -1153,13 +1156,14 @@ private <R> R mutableSideEffectImpl(
         id,
         metadata,
         (storedBinary) -> {
-          Optional<R> stored =
-              storedBinary.map(
-                  (b) ->
-                      dataConverterWithCurrentWorkflowContext.fromPayloads(
-                          0, Optional.of(b), resultClass, resultType));
           try {
             readOnly = true;
+            subjectToReplay = false;
+            Optional<R> stored =
+                storedBinary.map(
+                    (b) ->
+                        dataConverterWithCurrentWorkflowContext.fromPayloads(
+                            0, Optional.of(b), resultClass, resultType));
             R funcResult =
                 Objects.requireNonNull(
                     func.apply(), "mutableSideEffect function " + "returned null");
@@ -1170,6 +1174,7 @@ private <R> R mutableSideEffectImpl(
             return Optional.empty(); // returned only when value doesn't need to be updated
           } finally {
             readOnly = false;
+            subjectToReplay = true;
           }
         },
         (p) ->
@@ -1312,6 +1317,14 @@ void setReadOnly(boolean readOnly) {
     this.readOnly = readOnly;
   }
 
+  boolean isSubjectToReplay() {
+    return subjectToReplay;
+  }
+
+  void setSubjectToReplay(boolean subjectToReplay) {
+    this.subjectToReplay = subjectToReplay;
+  }
+
   @Override
   public Map<Long, SignalHandlerInfo> getRunningSignalHandlers() {
     return signalDispatcher.getRunningSignalHandlers();

temporal-sdk/src/main/java/io/temporal/internal/sync/WorkflowInternal.java

@@ -735,6 +735,17 @@ public static <T> T readOnly(Functions.Func<T> func) {
     }
   }
 
+  public static <T> T notSubjectToReplay(Functions.Func<T> func) {
+    SyncWorkflowContext workflowContext = getRootWorkflowContext();
+    boolean previousSubjectToReplay = workflowContext.isSubjectToReplay();
+    workflowContext.setSubjectToReplay(false);
+    try {
+      return func.apply();
+    } finally {
+      workflowContext.setSubjectToReplay(previousSubjectToReplay);
+    }
+  }
+
   public static WorkflowInfo getWorkflowInfo() {
     return new WorkflowInfoImpl(getRootWorkflowContext().getReplayContext());
   }
@@ -761,6 +772,10 @@ public static Random newRandom() {
     return getRootWorkflowContext().newRandom();
   }
 
+  public static Random getRandomStream(String name) {
+    return getRootWorkflowContext().getReplayContext().getRandomStream(name);
+  }
+
   public static Logger getLogger(Class<?> clazz) {
     Logger logger = LoggerFactory.getLogger(clazz);
     return new ReplayAwareLogger(
@@ -946,6 +961,11 @@ static void assertNotReadOnly(String action) {
     }
   }
 
+  public static boolean isSubjectToReplay() {
+    Optional<WorkflowThread> thread = DeterministicRunnerImpl.currentThreadInternalIfPresent();
+    return thread.isPresent() && getRootWorkflowContext().isSubjectToReplay();
+  }
+
   static void assertNotInUpdateHandler(String message) {
     if (getCurrentUpdateInfo().isPresent()) {
       throw new UnsupportedContinueAsNewRequest(message);

temporal-sdk/src/main/java/io/temporal/workflow/Workflow.java

@@ -1003,6 +1003,24 @@ public static Random newRandom() {
     return WorkflowInternal.newRandom();
   }
 
+  /**
+   * Returns a deterministic pseudorandom stream private to {@code name}.
+   *
+   * <p>Calling this method again with the same name returns the same logical stream where earlier
+   * draws left it. A Workflow Reset replays the same values up to the reset point, then reseeds the
+   * stream for the new Run. Each Continue-As-New Run gets a new sequence.
+   *
+   * <p>Draws are not recorded in Workflow History, so only draw where the code is re-executed on
+   * replay. Use {@link WorkflowUnsafe#isSubjectToReplay()} to gate draws.
+   *
+   * <p>Use a stable package-style name. Stream names are retained for the life of the Workflow Run.
+   * The stream is deterministic pseudorandomness and is not cryptographically secure.
+   */
+  @Experimental
+  public static Random getRandomStream(String name) {
+    return WorkflowInternal.getRandomStream(name);
+  }
+
   /**
    * True if workflow code is being replayed.
    *

temporal-sdk/src/main/java/io/temporal/workflow/unsafe/WorkflowUnsafe.java

@@ -1,5 +1,6 @@
 package io.temporal.workflow.unsafe;
 
+import io.temporal.common.Experimental;
 import io.temporal.internal.sync.WorkflowInternal;
 import io.temporal.workflow.Functions;
 
@@ -46,6 +47,23 @@ public static boolean isReplaying() {
     return WorkflowInternal.isReplaying();
   }
 
+  /**
+   * Reports whether the currently executing code is re-executed when the Workflow replays.
+   *
+   * <p>Unlike {@link #isReplaying()}, this is a property of the calling context rather than of the
+   * Workflow's current state. The Workflow method and its constructor, signal and update handlers,
+   * and Await conditions are subject to replay. Query handlers, Update validators, and Side Effect
+   * functions run once against the current state and are never re-executed, so they are not subject
+   * to replay even while {@link #isReplaying()} reports true.
+   *
+   * @return true if the calling context is re-executed on replay. This method always returns false
+   *     if called from a non workflow thread.
+   */
+  @Experimental
+  public static boolean isSubjectToReplay() {
+    return WorkflowInternal.isSubjectToReplay();
+  }
+
   /**
    * Runs the supplied procedure in the calling thread with disabled deadlock detection if called
    * from the workflow thread. Does nothing except the procedure execution if called from a