Rename ctx.sideEffect in ctx.run (#267)

Author: slinkydeveloper

examples/src/main/java/my/restate/sdk/examples/LoanWorkflow.java

@@ -103,7 +103,7 @@ public void run(WorkflowContext ctx, LoanRequest loanRequest) {
     LOG.info("Loan request submitted");
 
     // 2. Ask human approval
-    ctx.sideEffect(() -> askHumanApproval(ctx.workflowKey()));
+    ctx.run(() -> askHumanApproval(ctx.workflowKey()));
     ctx.set(STATUS, Status.WAITING_HUMAN_APPROVAL);
 
     // 3. Wait human approval

sdk-api-kotlin/src/main/kotlin/dev/restate/sdk/kotlin/ContextImpl.kt

@@ -130,10 +130,7 @@ internal class ContextImpl internal constructor(private val syscalls: Syscalls)
     }
   }
 
-  override suspend fun <T : Any?> sideEffect(
-      serde: Serde<T>,
-      sideEffectAction: suspend () -> T
-  ): T {
+  override suspend fun <T : Any?> run(serde: Serde<T>, sideEffectAction: suspend () -> T): T {
     val exitResult =
         suspendCancellableCoroutine { cont: CancellableContinuation<CompletableDeferred<ByteString>>
           ->

sdk-api-kotlin/src/main/kotlin/dev/restate/sdk/kotlin/api.kt

@@ -17,8 +17,8 @@ import kotlin.time.Duration
 
 /**
  * This interface exposes the Restate functionalities to Restate services. It can be used to
- * interact with other Restate services, record side effects, execute timers and synchronize with
- * external systems.
+ * interact with other Restate services, record non-deterministic closures, execute timers and
+ * synchronize with external systems.
  *
  * To use it within your Restate service, implement [RestateKtComponent] and get an instance with
  * [RestateKtComponent.restateContext].
@@ -114,9 +114,9 @@ sealed interface Context {
    * Errors occurring within this closure won't be propagated to the caller, unless they are
    * [TerminalException]. Consider the following code:
    * ```
-   * // Bad usage of try-catch outside the side effect
+   * // Bad usage of try-catch outside the run
    * try {
-   *     ctx.sideEffect {
+   *     ctx.run {
    *         throw IllegalStateException();
    *     };
    * } catch (e: IllegalStateException) {
@@ -125,29 +125,28 @@ sealed interface Context {
    *     // following the invocation retry policy.
    * }
    *
-   * // Good usage of try-catch outside the side effect
+   * // Good usage of try-catch outside the run
    * try {
-   *     ctx.sideEffect {
+   *     ctx.run {
    *         throw TerminalException("my error");
    *     };
    * } catch (e: TerminalException) {
    *     // This is invoked
    * }
    * ```
    *
-   * To propagate side effects failures to the side effect call-site, make sure to wrap them in
-   * [TerminalException].
+   * To propagate failures to the run call-site, make sure to wrap them in [TerminalException].
    *
    * @param serde the type tag of the return value, used to serialize/deserialize it.
-   * @param action to execute for its side effects.
+   * @param action closure to execute.
    * @param T type of the return value.
-   * @return value of the side effect operation.
+   * @return value of the run operation.
    */
-  suspend fun <T : Any?> sideEffect(serde: Serde<T>, sideEffectAction: suspend () -> T): T
+  suspend fun <T : Any?> run(serde: Serde<T>, sideEffectAction: suspend () -> T): T
 
-  /** Like [sideEffect] without a return value. */
-  suspend fun sideEffect(sideEffectAction: suspend () -> Unit) {
-    sideEffect(KtSerdes.UNIT, sideEffectAction)
+  /** Like [run] without a return value. */
+  suspend fun run(sideEffectAction: suspend () -> Unit) {
+    run(KtSerdes.UNIT, sideEffectAction)
   }
 
   /**
@@ -177,9 +176,9 @@ sealed interface Context {
    *
    * This instance is useful to generate identifiers, idempotency keys, and for uniform sampling
    * from a set of options. If a cryptographically secure value is needed, please generate that
-   * externally using [sideEffect].
+   * externally using [run].
    *
-   * You MUST NOT use this [Random] instance inside a [sideEffect].
+   * You MUST NOT use this [Random] instance inside a [run].
    *
    * @return the [Random] instance.
    */
@@ -234,7 +233,7 @@ class RestateRandom(seed: Long, private val syscalls: Syscalls) : Random() {
   private val r = Random(seed)
 
   override fun nextBits(bitCount: Int): Int {
-    check(!syscalls.isInsideSideEffect) { "You can't use RestateRandom inside a side effect!" }
+    check(!syscalls.isInsideSideEffect) { "You can't use RestateRandom inside ctx.run!" }
     return r.nextBits(bitCount)
   }
 

sdk-api-kotlin/src/test/kotlin/dev/restate/sdk/kotlin/RandomTest.kt

@@ -21,7 +21,7 @@ class RandomTest : RandomTestSuite() {
 
   override fun randomInsideSideEffect(): TestInvocationBuilder =
       testDefinitionForService<Unit, Int>("RandomInsideSideEffect") { ctx, _: Unit ->
-        ctx.sideEffect { ctx.random().nextInt() }
+        ctx.run { ctx.random().nextInt() }
         throw IllegalStateException("This should not unreachable")
       }
 

sdk-api-kotlin/src/test/kotlin/dev/restate/sdk/kotlin/SideEffectTest.kt

@@ -23,15 +23,15 @@ class SideEffectTest : SideEffectTestSuite() {
 
   override fun sideEffect(sideEffectOutput: String): TestInvocationBuilder =
       testDefinitionForService("SideEffect") { ctx, _: Unit ->
-        val result = ctx.sideEffect(CoreSerdes.JSON_STRING) { sideEffectOutput }
+        val result = ctx.run(CoreSerdes.JSON_STRING) { sideEffectOutput }
         "Hello $result"
       }
 
   override fun consecutiveSideEffect(sideEffectOutput: String): TestInvocationBuilder =
       testDefinitionForService("ConsecutiveSideEffect") { ctx, _: Unit ->
-        val firstResult = ctx.sideEffect(CoreSerdes.JSON_STRING) { sideEffectOutput }
+        val firstResult = ctx.run(CoreSerdes.JSON_STRING) { sideEffectOutput }
         val secondResult =
-            ctx.sideEffect(CoreSerdes.JSON_STRING) { firstResult.uppercase(Locale.getDefault()) }
+            ctx.run(CoreSerdes.JSON_STRING) { firstResult.uppercase(Locale.getDefault()) }
         "Hello $secondResult"
       }
 
@@ -43,9 +43,7 @@ class SideEffectTest : SideEffectTestSuite() {
                   Dispatchers.Unconfined + CoroutineName("CheckContextSwitchingTestCoroutine"))) {
                 handler("run") { ctx, _: Unit ->
                   val sideEffectCoroutine =
-                      ctx.sideEffect(CoreSerdes.JSON_STRING) {
-                        coroutineContext[CoroutineName]!!.name
-                      }
+                      ctx.run(CoreSerdes.JSON_STRING) { coroutineContext[CoroutineName]!!.name }
                   check(sideEffectCoroutine == "CheckContextSwitchingTestCoroutine") {
                     "Side effect thread is not running within the same coroutine context of the handler method: $sideEffectCoroutine"
                   }
@@ -56,7 +54,7 @@ class SideEffectTest : SideEffectTestSuite() {
 
   override fun sideEffectGuard(): TestInvocationBuilder =
       testDefinitionForService<Unit, String>("SideEffectGuard") { ctx, _: Unit ->
-        ctx.sideEffect { ctx.send(GREETER_SERVICE_TARGET, KtSerdes.json(), "something") }
+        ctx.run { ctx.send(GREETER_SERVICE_TARGET, KtSerdes.json(), "something") }
         throw IllegalStateException("This point should not be reached")
       }
 }

sdk-api-kotlin/src/test/kotlin/dev/restate/sdk/kotlin/StateMachineFailuresTest.kt

@@ -47,7 +47,7 @@ class StateMachineFailuresTest : StateMachineFailuresTestSuite() {
 
   override fun sideEffectFailure(serde: Serde<Int>): TestInvocationBuilder =
       testDefinitionForService("SideEffectFailure") { ctx, _: Unit ->
-        ctx.sideEffect(serde) { 0 }
+        ctx.run(serde) { 0 }
         "Francesco"
       }
 }

sdk-api-kotlin/src/test/kotlin/dev/restate/sdk/kotlin/UserFailuresTest.kt

@@ -26,7 +26,7 @@ class UserFailuresTest : UserFailuresTestSuite() {
   ): TestInvocationBuilder =
       testDefinitionForService<Unit, Unit>("SideEffectThrowIllegalStateException") { ctx, _: Unit ->
         try {
-          ctx.sideEffect { throw IllegalStateException("Whatever") }
+          ctx.run { throw IllegalStateException("Whatever") }
         } catch (e: Throwable) {
           if (e !is CancellationException && e !is TerminalException) {
             nonTerminalExceptionsSeen.addAndGet(1)
@@ -44,7 +44,7 @@ class UserFailuresTest : UserFailuresTestSuite() {
 
   override fun sideEffectThrowTerminalException(code: Int, message: String): TestInvocationBuilder =
       testDefinitionForService<Unit, Unit>("SideEffectThrowTerminalException") { ctx, _: Unit ->
-        ctx.sideEffect { throw TerminalException(code, message) }
+        ctx.run { throw TerminalException(code, message) }
         throw IllegalStateException("Not expected to reach this point")
       }
 }

sdk-api/src/main/java/dev/restate/sdk/Context.java

@@ -15,8 +15,8 @@
 
 /**
  * This interface exposes the Restate functionalities to Restate services. It can be used to
- * interact with other Restate services, record side effects, execute timers and synchronize with
- * external systems.
+ * interact with other Restate services, record non-deterministic closures, execute timers and
+ * synchronize with external systems.
  *
  * <p>All methods of this interface, and related interfaces, throws either {@link TerminalException}
  * or {@link AbortedExecutionException}, where the former can be caught and acted upon, while the
@@ -109,9 +109,9 @@ default void sleep(Duration duration) {
    * TerminalException}. Consider the following code:
    *
    * <pre>{@code
-   * // Bad usage of try-catch outside the side effect
+   * // Bad usage of try-catch outside the run
    * try {
-   *     ctx.sideEffect(() -> {
+   *     ctx.run(() -> {
    *         throw new IllegalStateException();
    *     });
    * } catch (IllegalStateException e) {
@@ -120,29 +120,29 @@ default void sleep(Duration duration) {
    *     // following the invocation retry policy.
    * }
    *
-   * // Good usage of try-catch outside the side effect
+   * // Good usage of try-catch outside the run
    * try {
-   *     ctx.sideEffect(() -> {
+   *     ctx.run(() -> {
    *         throw new TerminalException("my error");
    *     });
    * } catch (TerminalException e) {
    *     // This is invoked
    * }
    * }</pre>
    *
-   * To propagate side effects failures to the side effect call-site, make sure to wrap them in
-   * {@link TerminalException}.
+   * To propagate run failures to the call-site, make sure to wrap them in {@link
+   * TerminalException}.
    *
    * @param serde the type tag of the return value, used to serialize/deserialize it.
-   * @param action to execute for its side effects.
+   * @param action closure to execute.
    * @param <T> type of the return value.
-   * @return value of the side effect operation.
+   * @return value of the run operation.
    */
-  <T> T sideEffect(Serde<T> serde, ThrowingSupplier<T> action) throws TerminalException;
+  <T> T run(Serde<T> serde, ThrowingSupplier<T> action) throws TerminalException;
 
-  /** Like {@link #sideEffect(Serde, ThrowingSupplier)}, but without returning a value. */
-  default void sideEffect(ThrowingRunnable runnable) throws TerminalException {
-    sideEffect(
+  /** Like {@link #run(Serde, ThrowingSupplier)}, but without returning a value. */
+  default void run(ThrowingRunnable runnable) throws TerminalException {
+    run(
         CoreSerdes.VOID,
         () -> {
           runnable.run();

sdk-api/src/main/java/dev/restate/sdk/ContextImpl.java

@@ -110,7 +110,7 @@ public <T> void send(Target target, Serde<T> inputSerde, T parameter, Duration d
   }
 
   @Override
-  public <T> T sideEffect(Serde<T> serde, ThrowingSupplier<T> action) {
+  public <T> T run(Serde<T> serde, ThrowingSupplier<T> action) {
     CompletableFuture<CompletableFuture<ByteString>> enterFut = new CompletableFuture<>();
     syscalls.enterSideEffectBlock(
         new EnterSideEffectSyscallCallback() {

sdk-api/src/main/java/dev/restate/sdk/RestateRandom.java

@@ -21,10 +21,9 @@
  *
  * <p>This instance is useful to generate identifiers, idempotency keys, and for uniform sampling
  * from a set of options. If a cryptographically secure value is needed, please generate that
- * externally using {@link ObjectContext#sideEffect(Serde, ThrowingSupplier)}.
+ * externally using {@link ObjectContext#run(Serde, ThrowingSupplier)}.
  *
- * <p>You MUST NOT use this object inside a {@link ObjectContext#sideEffect(Serde,
- * ThrowingSupplier)}.
+ * <p>You MUST NOT use this object inside a {@link ObjectContext#run(Serde, ThrowingSupplier)}.
  */
 public class RestateRandom extends Random {
 
@@ -58,7 +57,7 @@ public UUID nextUUID() {
   @Override
   protected int next(int bits) {
     if (this.syscalls.isInsideSideEffect()) {
-      throw new IllegalStateException("You can't use RestateRandom inside a side effect!");
+      throw new IllegalStateException("You can't use RestateRandom inside ctx.run!");
     }
 
     return super.next(bits);