diff --git a/code_snippets/java/src/main/java/operate/invocations/GreetCounterObject.java b/code_snippets/java/src/main/java/develop/clients/GreetCounterObject.java similarity index 100% rename from code_snippets/java/src/main/java/operate/invocations/GreetCounterObject.java rename to code_snippets/java/src/main/java/develop/clients/GreetCounterObject.java diff --git a/code_snippets/java/src/main/java/operate/invocations/GreeterService.java b/code_snippets/java/src/main/java/develop/clients/GreeterService.java similarity index 100% rename from code_snippets/java/src/main/java/operate/invocations/GreeterService.java rename to code_snippets/java/src/main/java/develop/clients/GreeterService.java diff --git a/code_snippets/java/src/main/java/operate/invocations/Ingress.java b/code_snippets/java/src/main/java/develop/clients/Ingress.java similarity index 94% rename from code_snippets/java/src/main/java/operate/invocations/Ingress.java rename to code_snippets/java/src/main/java/develop/clients/Ingress.java index ce7b1b15..9c8cfee2 100644 --- a/code_snippets/java/src/main/java/operate/invocations/Ingress.java +++ b/code_snippets/java/src/main/java/develop/clients/Ingress.java @@ -28,12 +28,14 @@ public void myOneWayCallHandler(Context ctx) { // Client rs = Client.connect("http://localhost:8080"); GreeterServiceClient.fromClient(rs) - .send() - .greet("Hi"); + // mark + .send() + .greet("Hi"); GreetCounterObjectClient.fromClient(rs, "Mary") - .send() - .greet("Hi"); + // mark + .send() + .greet("Hi"); // } @@ -41,10 +43,12 @@ public void myDelayedOneWayCallHandler(Context ctx) { // Client rs = Client.connect("http://localhost:8080"); GreeterServiceClient.fromClient(rs) + // mark .send(Duration.ofMillis(1000)) .greet("Hi"); GreetCounterObjectClient.fromClient(rs, "Mary") + // mark .send(Duration.ofMillis(1000)) .greet("Hi"); // diff --git a/code_snippets/java/src/main/java/develop/workflows/SignupWorkflow.java b/code_snippets/java/src/main/java/develop/workflows/SignupWorkflow.java index 1f3cd547..597f573f 100644 --- a/code_snippets/java/src/main/java/develop/workflows/SignupWorkflow.java +++ b/code_snippets/java/src/main/java/develop/workflows/SignupWorkflow.java @@ -14,7 +14,6 @@ // @Workflow public class SignupWorkflow { - private static final DurablePromiseKey EMAIL_CLICKED = DurablePromiseKey.of("email_clicked", JsonSerdes.STRING); private static final StateKey STATUS = diff --git a/code_snippets/ts/src/operate/invocations/ingress.ts b/code_snippets/ts/src/develop/clients/ingress.ts similarity index 100% rename from code_snippets/ts/src/operate/invocations/ingress.ts rename to code_snippets/ts/src/develop/clients/ingress.ts diff --git a/code_snippets/ts/src/operate/invocations/utils.ts b/code_snippets/ts/src/develop/clients/utils.ts similarity index 100% rename from code_snippets/ts/src/operate/invocations/utils.ts rename to code_snippets/ts/src/develop/clients/utils.ts diff --git a/docs/concepts/durable_building_blocks.mdx b/docs/concepts/durable_building_blocks.mdx index f3a420f4..068e9df8 100644 --- a/docs/concepts/durable_building_blocks.mdx +++ b/docs/concepts/durable_building_blocks.mdx @@ -29,118 +29,106 @@ Let's have a look at a handler that processes food orders: - + + ### Durable functions + Handlers take part in durable execution, meaning that Restate keeps track of their progress and recovers them to the previously reached state in case of failures. - ```ts order_processor.ts - CODE_LOAD::ts/src/concepts/food_ordering.ts - ``` - - --- ```ts order_processor.ts CODE_LOAD::ts/src/concepts/food_ordering_functions.ts ``` - ### Durable functions - Handlers take part in durable execution, meaning that Restate keeps track of their progress and recovers them to the previously reached state in case of failures. - --- - ```ts order_processor.ts - CODE_LOAD::ts/src/concepts/food_ordering_rpc.ts - ``` - ### Durable RPCs and queues Handlers can call other handlers in a resilient way, with or without waiting for the response. When a failure happens, Restate handles retries and recovers partial progress. - --- - ```ts order_processor.ts - CODE_LOAD::ts/src/concepts/food_ordering_awakeables.ts + CODE_LOAD::ts/src/concepts/food_ordering_rpc.ts ``` + --- + ### Durable promises and timers Register promises in Restate to make them resilient to failures (e.g. webhooks, timers). Restate lets the handler suspend while awaiting the promise, and invokes it again when the result is available. A great match for function-as-a-service platforms. - --- - ```ts order_processor.ts - CODE_LOAD::ts/src/concepts/food_ordering_state.ts + CODE_LOAD::ts/src/concepts/food_ordering_awakeables.ts ``` + --- + ### Consistent K/V state Persist application state in Restate with a simple concurrency model and no extra setup. Restate makes sure state remains consistent amid failures. - --- ```ts order_processor.ts - CODE_LOAD::ts/src/concepts/food_ordering_side_effect.ts + CODE_LOAD::ts/src/concepts/food_ordering_state.ts ``` + --- ### Journaling actions Store the result of an action in Restate. The result gets replayed in case of failures and the action is not executed again. - + ```ts order_processor.ts + CODE_LOAD::ts/src/concepts/food_ordering_side_effect.ts + ``` + + - + - ```java OrderWorkflow.java - CODE_LOAD::java/src/main/java/concepts/buildingblocks/part0/OrderWorkflow.java - ``` + ### Durable functions + Handlers take part in durable execution, meaning that Restate keeps track of their progress and recovers them to the previously reached state in case of failures. - --- ```java OrderWorkflow.java CODE_LOAD::java/src/main/java/concepts/buildingblocks/part1_functions/OrderWorkflow.java ``` - ### Durable functions - Handlers take part in durable execution, meaning that Restate keeps track of their progress and recovers them to the previously reached state in case of failures. - --- - ```java OrderWorkflow.java - CODE_LOAD::java/src/main/java/concepts/buildingblocks/part2_rpc/OrderWorkflow.java - ``` - ### Durable RPCs and queues Handlers can call other handlers in a resilient way, with or without waiting for the response. When a failure happens, Restate handles retries and recovers partial progress. - --- - ```java OrderWorkflow.java - CODE_LOAD::java/src/main/java/concepts/buildingblocks/part3_promises/OrderWorkflow.java + CODE_LOAD::java/src/main/java/concepts/buildingblocks/part2_rpc/OrderWorkflow.java ``` + --- + ### Durable promises and timers Register promises in Restate to make them resilient to failures (e.g. webhooks, timers). Restate lets the handler suspend while awaiting the promise, and invokes it again when the result is available. A great match for function-as-a-service platforms. - --- - ```java OrderWorkflow.java - CODE_LOAD::java/src/main/java/concepts/buildingblocks/part4_state/OrderWorkflow.java + CODE_LOAD::java/src/main/java/concepts/buildingblocks/part3_promises/OrderWorkflow.java ``` + --- + ### Consistent K/V state Persist application state in Restate with a simple concurrency model and no extra setup. Restate makes sure state remains consistent amid failures. - --- - ```java OrderWorkflow.java - CODE_LOAD::java/src/main/java/concepts/buildingblocks/part5_sideeffects/OrderWorkflow.java + CODE_LOAD::java/src/main/java/concepts/buildingblocks/part4_state/OrderWorkflow.java ``` + --- + ### Journaling actions Store the result of an action in Restate. The result gets replayed in case of failures and the function is not executed again. + ```java OrderWorkflow.java + CODE_LOAD::java/src/main/java/concepts/buildingblocks/part5_sideeffects/OrderWorkflow.java + ``` - + diff --git a/docs/concepts/invocations.mdx b/docs/concepts/invocations.mdx index b0ead97a..17cb9707 100644 --- a/docs/concepts/invocations.mdx +++ b/docs/concepts/invocations.mdx @@ -58,8 +58,9 @@ Invocations get a unique identifier. This identifier is used to track the progre - + + **Request-response invocations** allow you to wait on a response from the handler. @@ -75,9 +76,8 @@ Invocations get a unique identifier. This identifier is used to track the progre --- - **Request-response invocations** allow you to wait on a response from the handler. - - --- + **One-way invocations** allow you to trigger an asynchronous action. + This returns an invocation ID with which you can retrieve the result of the invocation later, if desired. @@ -91,11 +91,10 @@ Invocations get a unique identifier. This identifier is used to track the progre - **One-way invocations** allow you to trigger an asynchronous action. - This returns an invocation ID with which you can retrieve the result of the invocation later, if desired. - --- + **Delayed invocations** allow you to schedule an invocation for a later point in time. + ```typescript restate_service.ts @@ -108,13 +107,13 @@ Invocations get a unique identifier. This identifier is used to track the progre - **Delayed invocations** allow you to schedule an invocation for a later point in time. - - + - + + + **Request-response invocations** allow you to wait on a response from the handler. @@ -130,9 +129,8 @@ Invocations get a unique identifier. This identifier is used to track the progre --- - **Request-response invocations** allow you to wait on a response from the handler. - - --- + **One-way invocations** allow you to trigger an asynchronous action. + This returns an invocation ID with which you can retrieve the result of the invocation later, if desired. @@ -147,11 +145,10 @@ Invocations get a unique identifier. This identifier is used to track the progre - **One-way invocations** allow you to trigger an asynchronous action. - This returns an invocation ID with which you can retrieve the result of the invocation later, if desired. - --- + **Delayed invocations** allow you to schedule an invocation for a later point in time. + ```java RestateService.java @@ -164,15 +161,15 @@ Invocations get a unique identifier. This identifier is used to track the progre - **Delayed invocations** allow you to schedule an invocation for a later point in time. - - + - + + + **Request-response invocations** allow you to wait on a response from the handler. ```bash curl localhost:8080/GreeterService/greet \ @@ -190,9 +187,8 @@ Invocations get a unique identifier. This identifier is used to track the progre --- - **Request-response invocations** allow you to wait on a response from the handler. - - --- + **One-way invocations** allow you to trigger an asynchronous action. + This returns an invocation ID with which you can retrieve the result of the invocation later, if desired. ```bash curl localhost:8080/GreeterService/greet/send \ @@ -208,11 +204,10 @@ Invocations get a unique identifier. This identifier is used to track the progre -d '"Hi"' ``` - **One-way invocations** allow you to trigger an asynchronous action. - This returns an invocation ID with which you can retrieve the result of the invocation later, if desired. - --- + **Delayed invocations** allow you to schedule an invocation for a later point in time. + ```bash curl localhost:8080/GreeterService/greet/send?delay=10s \ -H 'content-type: application/json' \ @@ -223,10 +218,7 @@ Invocations get a unique identifier. This identifier is used to track the progre -d '"Hi"' ``` - **Delayed invocations** allow you to schedule an invocation for a later point in time. - - - + diff --git a/docs/concepts/services.mdx b/docs/concepts/services.mdx index adba78b7..dd58502e 100644 --- a/docs/concepts/services.mdx +++ b/docs/concepts/services.mdx @@ -37,90 +37,75 @@ Services expose a collection of handlers: - - - ```typescript - CODE_LOAD::ts/src/concepts/services.ts#- - ``` - - --- - - ```diff mark=10,16 - ``` + Restate makes sure that **handlers run to completion**, even in the presence of failures. Restate logs the **results of actions** in the system. Restate takes care of retries and recovers the handler to the point where it failed. + ```typescript mark=10,16 + CODE_LOAD::ts/src/concepts/services.ts#- + ``` + --- + The handlers of services are **independent** and can be **invoked concurrently**. + ```diff mark=4,6,7,18,19,20 ``` - The handlers of services are **independent** and can be **invoked concurrently**. - --- + Handlers use the regular code and control flow, no custom DSLs. + ```diff mark=11:13,15,17 ``` - Handlers use the regular code and control flow, no custom DSLs. - --- - ```diff - ``` - Service handlers **don't have access to Restate's K/V store**. + ```diff + ``` - + + - + Restate makes sure that **handlers run to completion**, even in the presence of failures. + Restate logs the **results of actions** in the system. + Restate takes care of retries and recovers the handler to the point where it failed. - ```java + ```java mark=6:7,13:14 CODE_LOAD::java/src/main/java/concepts/services/RoleUpdateService.java ``` --- - ```diff mark=6:7,13:14 - ``` - - Restate makes sure that **handlers run to completion**, even in the presence of failures. - Restate logs the **results of actions** in the system. - Restate takes care of retries and recovers the handler to the point where it failed. - - --- + The handlers of services are **independent** and can be **invoked concurrently**. ```diff mark=1:5,16,19,20,23 ``` - The handlers of services are **independent** and can be **invoked concurrently**. - --- + Handlers use the regular code and control flow, no custom DSLs. + ```diff mark=8:10,12,14,15 ``` - Handlers use the regular code and control flow, no custom DSLs. - --- - ```diff - ``` - Service handlers **don't have access to Restate's K/V store**. + ```diff + ``` - - + - In the example, we use a Restate service to update different systems and to make sure all updates are applied. During retries, the service will not reapply the same update twice. @@ -130,75 +115,62 @@ Virtual objects expose a set of handlers with access to K/V state stored in Rest + - + A virtual object is **uniquely identified and accessed by its key**. - ```typescript + ```typescript mark=4,6,7,11,12,14,20,21,22 CODE_LOAD::ts/src/concepts/virtual_objects.ts#- ``` --- - ```diff mark=4,6,7,11,12,14,20,21,22 - ``` - - A virtual object is **uniquely identified and accessed by its key**. - - --- - - ```diff mark=8:10,15,17,19 - ``` - Each virtual object has access to its own **isolated K/V state**, stored in Restate. The handlers of a virtual object can read and write to the state of the object. Restate delivers the state together with the request to the virtual object, so virtual objects have their state locally accessible without requiring any database connection or lookup. State is exclusive, and atomically committed with the method execution. - --- - - ```diff mark=4,6,7,9,12,14,17,21,22,23 + ```diff mark=8:10,15,17,19 ``` + --- + To ensure consistent writes to the state, Restate provides **concurrency guarantees**: at most one handler can execute at a time for a given virtual object. This can also be used for example to implement a locking mechanism or to ensure single writer to a database row. + ```diff mark=4,6,7,9,12,14,17,21,22,23 + ``` - + - + - ```java - CODE_LOAD::java/src/main/java/concepts/services/Greeter.java - ``` - - --- + A virtual object is **uniquely identified and accessed by its key**. - ```diff mark=1,2,7,8,12,13,15,16,22,23 + ```java mark=1,2,7,8,12,13,15,16,22,23 + CODE_LOAD::java/src/main/java/concepts/services/Greeter.java ``` - A virtual object is **uniquely identified and accessed by its key**. - --- - ```diff mark=9:11,17,19,21 - ``` - Each virtual object has access to its own **isolated K/V state**, stored in Restate. The handlers of a virtual object can read and write to the state of the object. Restate delivers the state together with the request to the virtual object, so virtual objects have their state locally accessible without requiring any database connection or lookup. State is exclusive, and atomically committed with the method execution. - --- - - ```diff mark=1,2,7,8,13,15,16,23 + ```diff mark=9:11,17,19,21 ``` + --- + **Concurrency guarantees**: to ensure consistent writes to the state, at most one handler can execute at a time for a given virtual object. This can also be used, for example, to implement a locking mechanism or to ensure single writer to a database row. + ```diff mark=1,2,7,8,13,15,16,23 + ``` - + @@ -209,72 +181,60 @@ They have some added capabilities such as signaling, querying, additional invoca + - + A workflow has a **`run` handler** that implements the **workflow logic**. + The `run` handler runs exactly once per workflow ID (object). - ```typescript + ```typescript mark=4:25 CODE_LOAD::ts/src/concepts/workflow.ts#- ``` --- - ```diff mark=4:25 - ``` - - A workflow has a **`run` handler** that implements the **workflow logic**. - The `run` handler runs exactly once per workflow ID (object). - - --- + You can **query the workflow** by defining other handlers in the same object. + For example, you can store state in the workflow object, and query it from other handlers. ```diff mark=16,22,31 ``` - You can **query the workflow** by defining other handlers in the same object. - For example, you can store state in the workflow object, and query it from other handlers. - --- - ```diff mark=15,27:29 - ``` - You can **signal the workflow**, to send information to it, via [Durable Promises](/develop/ts/workflows#signaling-workflows). For example, the payment provider signals the workflow that the payment was successful by calling the `paymentWebhook`. + ```diff mark=15,27:29 + ``` - + - + - ```java + A workflow has a **`run` handler** that implements the **workflow logic**. + The `run` handler runs exactly once per workflow ID (object). + + ```java mark=8:28 CODE_LOAD::java/src/main/java/concepts/services/Payment.java#- ``` --- - ```diff mark=8:28 - ``` - - A workflow has a **`run` handler** that implements the **workflow logic**. - The `run` handler runs exactly once per workflow ID (object). - - --- + You can **query the workflow** by defining other handlers in the same object. + For example, you can store state in the workflow object, and query it from other handlers. ```diff mark=20,25,35:38 ``` - You can **query the workflow** by defining other handlers in the same object. - For example, you can store state in the workflow object, and query it from other handlers. - --- - ```diff mark=18,30:33 - ``` - You can **signal the workflow**, to send information to it, via [Durable Promises](/develop/ts/workflows#signaling-workflows). For example, the payment provider signals the workflow that the payment was successful by calling the `paymentWebhook`. - + ```diff mark=18,30:33 + ``` + + diff --git a/docs/develop/java/clients.mdx b/docs/develop/java/clients.mdx index a58668a9..d17c825d 100644 --- a/docs/develop/java/clients.mdx +++ b/docs/develop/java/clients.mdx @@ -5,6 +5,7 @@ description: "Use the clients to invoke handlers programmatically." import Admonition from '@theme/Admonition'; import {Step} from "../../../src/components/Stepper"; +import clsx from "clsx"; # Clients The Restate SDK client library lets you invoke Restate handlers from anywhere in your application. @@ -26,33 +27,33 @@ Invoke a handler programmatically with the SDK clients as follows: Register the service you want to invoke.}/> - + + + **Request-response invocations** allow you to wait on a response from the handler. ```java - CODE_LOAD::java/src/main/java/operate/invocations/Ingress.java#- + CODE_LOAD::java/src/main/java/develop/clients/Ingress.java#- ``` - --- + + - **Request-response invocations** allow you to wait on a response from the handler. - - --- + **One-way invocations** allow you to send a message without waiting for a response. ```java - CODE_LOAD::java/src/main/java/operate/invocations/Ingress.java#- + CODE_LOAD::java/src/main/java/develop/clients/Ingress.java#- ``` - **One-way invocations** allow you to send a message without waiting for a response. + + - --- + **Delayed invocations** allow you to schedule an invocation for a later point in time. ```java - CODE_LOAD::java/src/main/java/operate/invocations/Ingress.java#- + CODE_LOAD::java/src/main/java/develop/clients/Ingress.java#- ``` - **Delayed invocations** allow you to schedule an invocation for a later point in time. - - + @@ -65,7 +66,7 @@ To make a service call idempotent, you can use the idempotency key feature. Add the idempotency key [to the header](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/) via: ```java -CODE_LOAD::java/src/main/java/operate/invocations/Ingress.java#- +CODE_LOAD::java/src/main/java/develop/clients/Ingress.java#- ``` After the invocation completes, Restate persists the response for a retention period of one day (24 hours). @@ -105,7 +106,7 @@ You can: You can use the invocation ID to attach or peek at a service/object invocation that used an idempotency key: ```java -CODE_LOAD::java/src/main/java/operate/invocations/Ingress.java#- +CODE_LOAD::java/src/main/java/develop/clients/Ingress.java#- ``` diff --git a/docs/develop/java/journaling-results.mdx b/docs/develop/java/journaling-results.mdx index 93a324ab..0020d7b4 100644 --- a/docs/develop/java/journaling-results.mdx +++ b/docs/develop/java/journaling-results.mdx @@ -6,6 +6,7 @@ description: "Learn how to store the results of non-deterministic operations." import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import Admonition from '@theme/Admonition'; +import clsx from "clsx"; # Journaling Results @@ -59,32 +60,27 @@ Operations such as calls, awakeables, and sleep return a `Awaitable`. The SDK provides combinators for working with `Awaitable`. Restate then logs the order in which they are resolved or rejected, to make them deterministic on replay. - - - + **Await all** creates an `Awaitable` that awaits for all of the provided Awaitables to resolve. The semantics are similar to [`CompleteableFuture.allOf()`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/CompletableFuture.html#allOf(java.util.concurrent.CompletableFuture...)), but the outcome is stored in the Restate journal to be deterministically replayable. ```java CODE_LOAD::java/src/main/java/develop/SideEffects.java#- ``` - - - - + + **Await any** creates an `Awaitable` that awaits any of the provided Awaitables to resolve. The semantics are similar to [`CompleteableFuture.anyOf()`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/CompletableFuture.html#anyOf(java.util.concurrent.CompletableFuture...)), but the outcome is stored in the Restate journal to be deterministically replayable. ```java CODE_LOAD::java/src/main/java/develop/SideEffects.java#- ``` - - + - + ### Await all Creates an `Awaitable` that awaits for all of the provided Awaitables to resolve. @@ -94,9 +90,8 @@ Restate then logs the order in which they are resolved or rejected, to make them ```kotlin CODE_LOAD::kotlin/src/main/kotlin/develop/SideEffects.kt#- ``` - - - + + ### Await any Creates an `Awaitable` that awaits any of the provided Awaitables to resolve. @@ -106,7 +101,7 @@ Restate then logs the order in which they are resolved or rejected, to make them ```kotlin CODE_LOAD::kotlin/src/main/kotlin/develop/SideEffects.kt#- ``` - + @@ -119,8 +114,7 @@ Restate seeds the random number generator with the invocation ID, so it always r - - + ### Generating UUIDs You can use these UUIDs to generate stable idempotency keys, to deduplicate operations. For example, you can use this to let a payment service avoid duplicate payments during retries. @@ -131,8 +125,8 @@ Restate seeds the random number generator with the invocation ID, so it always r CODE_LOAD::java/src/main/java/develop/SideEffects.java#- ``` - - + + ### Generating random numbers @@ -145,12 +139,12 @@ Restate seeds the random number generator with the invocation ID, so it always r CODE_LOAD::java/src/main/java/develop/SideEffects.java#- ``` - + - + ### Generating UUIDs You can use these UUIDs to generate stable idempotency keys, to deduplicate operations. For example, you can use this to let a payment service avoid duplicate payments during retries. @@ -161,8 +155,8 @@ Restate seeds the random number generator with the invocation ID, so it always r CODE_LOAD::kotlin/src/main/kotlin/develop/SideEffects.kt#- ``` - - + + ### Generating random numbers @@ -175,7 +169,7 @@ Restate seeds the random number generator with the invocation ID, so it always r CODE_LOAD::kotlin/src/main/kotlin/develop/SideEffects.kt#- ``` - + diff --git a/docs/develop/java/service-communication.mdx b/docs/develop/java/service-communication.mdx index f3c5b20b..a2453179 100644 --- a/docs/develop/java/service-communication.mdx +++ b/docs/develop/java/service-communication.mdx @@ -33,51 +33,51 @@ Use the generated client's of the SDK to do the request-response call: - + To a Service: ```java CODE_LOAD::java/src/main/java/develop/ServiceCommunication.java#- ``` - - + + To a Virtual Object: ```java CODE_LOAD::java/src/main/java/develop/ServiceCommunication.java#- ``` - + - + To a Workflow: ```java CODE_LOAD::java/src/main/java/develop/ServiceCommunication.java#- ``` - + - + To a Service: ```kotlin CODE_LOAD::kotlin/src/main/kotlin/develop/ServiceCommunication.kt#- ``` - - + + To a Virtual Object: ```kotlin CODE_LOAD::kotlin/src/main/kotlin/develop/ServiceCommunication.kt#- ``` - - + + To a Workflow: ```kotlin CallWorkflow.kt CODE_LOAD::kotlin/src/main/kotlin/develop/ServiceCommunication.kt#- ``` - + diff --git a/docs/develop/java/workflows.mdx b/docs/develop/java/workflows.mdx index 9fc203cc..2a76f49e 100644 --- a/docs/develop/java/workflows.mdx +++ b/docs/develop/java/workflows.mdx @@ -81,7 +81,7 @@ Have a look at the code example to get a better understanding of how workflows a ## Submitting workflows with SDK clients - + [**Submit**](/develop/java/clients): This returns a handle to the workflow once it has been registered in Restate. You can only submit once per workflow ID (here `"someone"`). @@ -89,9 +89,9 @@ Have a look at the code example to get a better understanding of how workflows a ```java CODE_LOAD::java/src/main/java/develop/workflows/WorkflowSubmitter.java#- ``` - + - + [**Query/signal**](/develop/java/clients): Call the other handlers of the workflow in the same way as for Virtual Object handlers. Use `send()` for one-way calls. @@ -99,9 +99,9 @@ Have a look at the code example to get a better understanding of how workflows a ```java CODE_LOAD::java/src/main/java/develop/workflows/WorkflowSubmitter.java#- ``` - + - + [**Attach/peek**](/develop/java/clients#retrieve-result-of-invocations-and-workflows): This lets you retrieve the result of a workflow or check if it's finished. @@ -110,11 +110,11 @@ Have a look at the code example to get a better understanding of how workflows a ```java CODE_LOAD::java/src/main/java/develop/workflows/WorkflowSubmitter.java#- ``` - + ## Submitting workflows from a Restate service - + [**Submit/query/signal**](/develop/java/service-communication): Use the generated client to call any workflow handler in the same way as for Services and Virtual Objects. @@ -125,11 +125,11 @@ Have a look at the code example to get a better understanding of how workflows a ```java CODE_LOAD::java/src/main/java/develop/workflows/UserManagementService.java ``` - + ## Submitting workflows over HTTP - + [**Submit/query/signal**](/invoke/http): Call any handler of the workflow in the same way as for Services and Virtual Objects. This returns the result of the handler once it has finished. @@ -141,9 +141,9 @@ Have a look at the code example to get a better understanding of how workflows a -H 'content-type: application/json' \ -d '{"email": "someone@restate.dev"}' ``` - + - + [**Attach/peek**](/invoke/http#retrieve-result-of-invocations-and-workflows): This lets you retrieve the result of a workflow or check if it's finished. @@ -153,7 +153,7 @@ Have a look at the code example to get a better understanding of how workflows a curl localhost:8080/restate/workflow/SignupWorkflow/someone/output ``` - + ## Inspecting workflows diff --git a/docs/develop/local_dev.mdx b/docs/develop/local_dev.mdx index 483c7109..c94b3592 100644 --- a/docs/develop/local_dev.mdx +++ b/docs/develop/local_dev.mdx @@ -6,49 +6,52 @@ description: "Learn how to set up your local dev environment" import Admonition from '@theme/Admonition'; import TabItem from "@theme/TabItem"; import Tabs from "@theme/Tabs"; +import clsx from "clsx"; # Local Dev ## Running Restate Server & CLI locally + + - - Install Restate Server and run it: + + Install Restate Server and run it: ```shell npm install --global @restatedev/restate-server@latest && restate-server ``` - - - Or use npx, without installation: + + + Or use npx, without installation: ```shell npx @restatedev/restate-server ``` - - - Install the Restate CLI via: + + + Install the Restate CLI via: ```shell npm install --global @restatedev/restate@latest ``` - + - + Install Restate Server and run it with: ```shell brew install restatedev/tap/restate-server && restate-server ``` - + - + Install the CLI via: ```shell brew install restatedev/tap/restate ``` - + @@ -124,22 +127,22 @@ import Tabs from "@theme/Tabs"; ## Useful dev CLI commands - + Check if the CLI is installed correctly and can find the server: ```shell restate whoami ``` - - + + Register a new service deployment.
When running Restate in a Docker, replace localhost with host.docker.internal. ```shell restate deployments register localhost:9080 ``` - - + + [Cancel](/operate/invocation#cancelling-invocations) a single invocation or a batch of invocations. Use `--kill` to [kill](/operate/invocation#killing-invocations) the invocation. @@ -150,8 +153,8 @@ import Tabs from "@theme/Tabs"; # also works with // or a subset of it ``` - - + + Purge completed invocations from the state: @@ -160,8 +163,8 @@ import Tabs from "@theme/Tabs"; # also works with // or a subset of it ``` - - + + Clear the K/V state of a Virtual Object or Workflows. To clear all state, restart the server with `--wipe all`. @@ -171,8 +174,8 @@ import Tabs from "@theme/Tabs"; restate kv clear / ``` - - + + Execute a SQL query on the invocation or application state. See [SQL introspection docs](/operate/introspection?interface=psql#inspecting-invocations) for example queries. @@ -182,8 +185,7 @@ import Tabs from "@theme/Tabs"; restate sql "query" ``` - - + Have a look at the [introspection page](/operate/introspection) for a list of useful commands. diff --git a/docs/develop/ts/clients.mdx b/docs/develop/ts/clients.mdx index 5eb27219..41b2071e 100644 --- a/docs/develop/ts/clients.mdx +++ b/docs/develop/ts/clients.mdx @@ -5,6 +5,7 @@ description: "Use the clients to invoke handlers programmatically." import Admonition from '@theme/Admonition'; import {Step} from "../../../src/components/Stepper"; +import clsx from "clsx"; # Clients @@ -25,32 +26,32 @@ Restate then attaches information about the invocation to the parent invocation. Register the service you want to invoke.}/> - + + + **Request-response invocations** allow you to wait on a response from the handler. ```typescript - CODE_LOAD::ts/src/operate/invocations/ingress.ts#- + CODE_LOAD::ts/src/develop/clients/ingress.ts#- ``` - --- + + - **Request-response invocations** allow you to wait on a response from the handler. - - --- + **One-way invocations** allow you to send a message without waiting for a response. ```typescript - CODE_LOAD::ts/src/operate/invocations/ingress.ts#- + CODE_LOAD::ts/src/develop/clients/ingress.ts#- ``` - **One-way invocations** allow you to send a message without waiting for a response. + + - --- + **Delayed invocations** allow you to schedule an invocation for a later point in time. ```typescript - CODE_LOAD::ts/src/operate/invocations/ingress.ts#- + CODE_LOAD::ts/src/develop/clients/ingress.ts#- ``` - - **Delayed invocations** allow you to schedule an invocation for a later point in time. - + @@ -63,7 +64,7 @@ To make a service call idempotent, you can use the idempotency key feature. Add the idempotency key [to the header](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/) via: ```typescript -CODE_LOAD::ts/src/operate/invocations/ingress.ts#- +CODE_LOAD::ts/src/develop/clients/ingress.ts#- ``` After the invocation completes, Restate persists the response for a retention period of one day (24 hours). @@ -100,7 +101,7 @@ You can use the client library to retrieve the results of invocations **with an Attach to them by using the handle that is returned from the invocation: ```typescript -CODE_LOAD::ts/src/operate/invocations/ingress.ts#- +CODE_LOAD::ts/src/develop/clients/ingress.ts#- ``` diff --git a/docs/develop/ts/journaling-results.mdx b/docs/develop/ts/journaling-results.mdx index 5b085c1b..3c9cc5f4 100644 --- a/docs/develop/ts/journaling-results.mdx +++ b/docs/develop/ts/journaling-results.mdx @@ -4,6 +4,7 @@ description: "Learn how to store the results of non-deterministic operations." --- import Admonition from '@theme/Admonition'; +import clsx from "clsx"; # Journaling Results @@ -41,21 +42,14 @@ The SDK provides combinators for working with `CombineablePromise`. Restate then logs the order in which they are resolved or rejected, to make them deterministic on replay. - - - - ```typescript - CODE_LOAD::ts/src/develop/side_effects.ts#- - ``` - - --- + **Await all** creates a promise that is similar to [`Promise.all()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all), but the outcome is stored in the Restate journal to be deterministically replayable: - Resolves with an array of results, once all input promises are resolved. - Rejects when any input promise is rejected. - ```typescript focus=1:6 mark=5:6 + CODE_LOAD::ts/src/develop/side_effects.ts#- ``` --- @@ -90,12 +84,12 @@ Restate then logs the order in which they are resolved or rejected, to make them ```typescript focus=1:3,14,15 mark=14,15 ``` - + ## Generating randoms The SDK provides helper functions for the deterministic generation of UUIDs and random numbers. Restate seeds the random number generator with the invocation ID, so it always returns the same value on retries. - + ### Generating UUIDs You can use these UUIDs to generate stable idempotency keys, to deduplicate operations. For example, you can use this to let a payment service avoid duplicate payments during retries. @@ -106,8 +100,8 @@ The SDK provides helper functions for the deterministic generation of UUIDs and CODE_LOAD::ts/src/develop/side_effects.ts#- ``` - - + + ### Generating random numbers @@ -118,4 +112,4 @@ The SDK provides helper functions for the deterministic generation of UUIDs and ```typescript CODE_LOAD::ts/src/develop/side_effects.ts#- ``` - + diff --git a/docs/develop/ts/service-communication.mdx b/docs/develop/ts/service-communication.mdx index c47c2cc1..98be3a06 100644 --- a/docs/develop/ts/service-communication.mdx +++ b/docs/develop/ts/service-communication.mdx @@ -27,7 +27,7 @@ Import this service definition in the service handler that wants to call it. Request-response calls are requests where the client waits for the response. - + To a Service: @@ -35,9 +35,8 @@ Request-response calls are requests where the client waits for the response. CODE_LOAD::ts/src/develop/service_communication.ts#- ``` - - - + + To a Virtual Object: @@ -45,8 +44,8 @@ Request-response calls are requests where the client waits for the response. CODE_LOAD::ts/src/develop/service_communication.ts#- ``` - - + + To a Workflow: @@ -54,7 +53,7 @@ Request-response calls are requests where the client waits for the response. CODE_LOAD::ts/src/develop/service_communication.ts#- ``` - + 1. **Create a service client** and supply the service definition of the service you want to call. For Virtual Objects, you also need to supply the key of the Virtual Object you want to call, here `"Mary"`. @@ -85,7 +84,7 @@ Request-response calls are requests where the client waits for the response. Handlers can send messages (a.k.a. one-way calls, or fire-and-forget calls), as follows: - + To a Service: @@ -93,9 +92,9 @@ Handlers can send messages (a.k.a. one-way calls, or fire-and-forget calls), as CODE_LOAD::ts/src/develop/service_communication.ts#- ``` - + - + To a Virtual Object: @@ -103,9 +102,9 @@ Handlers can send messages (a.k.a. one-way calls, or fire-and-forget calls), as CODE_LOAD::ts/src/develop/service_communication.ts#- ``` - + - + To a Workflow: @@ -113,7 +112,7 @@ Handlers can send messages (a.k.a. one-way calls, or fire-and-forget calls), as CODE_LOAD::ts/src/develop/service_communication.ts#- ``` - + Without Restate, you would usually put a message queue in between the two services, to guarantee the message delivery. @@ -126,7 +125,7 @@ A delayed call is a one-way call that gets executed after a specified delay. To schedule a delayed call, send a message with a delay parameter, as follows: - + To a Service: @@ -134,9 +133,8 @@ To schedule a delayed call, send a message with a delay parameter, as follows: CODE_LOAD::ts/src/develop/service_communication.ts#- ``` - - - + + To a Virtual Object: @@ -144,7 +142,7 @@ To schedule a delayed call, send a message with a delay parameter, as follows: CODE_LOAD::ts/src/develop/service_communication.ts#- ``` - + You can also use this functionality to schedule async tasks. diff --git a/docs/develop/ts/workflows.mdx b/docs/develop/ts/workflows.mdx index e0948d7b..8d759ef6 100644 --- a/docs/develop/ts/workflows.mdx +++ b/docs/develop/ts/workflows.mdx @@ -3,6 +3,7 @@ sidebar_position: 7 description: "Find out how Restate services can send requests to each other." --- +import clsx from "clsx"; import Admonition from '@theme/Admonition'; # Workflows @@ -78,7 +79,7 @@ Have a look at the code example to get a better understanding of how workflows a ## Submitting workflows with SDK clients - + [**Submit**](/develop/ts/clients): This returns a handle to the workflow once has been registered in Restate. @@ -88,9 +89,9 @@ Have a look at the code example to get a better understanding of how workflows a CODE_LOAD::ts/src/develop/workflows/submit.ts#- ``` - + - + [**Query/signal**](/develop/ts/clients): Call the other handlers of the workflow in the same way as for Virtual Object handlers. For now, you can only do request-response calls. @@ -98,9 +99,9 @@ Have a look at the code example to get a better understanding of how workflows a ```ts CODE_LOAD::ts/src/develop/workflows/submit.ts#- ``` - + - + [**Attach/peek**](/develop/ts/clients#retrieve-result-of-invocations-and-workflows): This lets you retrieve the result of a workflow or check if it's finished. @@ -108,10 +109,10 @@ Have a look at the code example to get a better understanding of how workflows a ```ts CODE_LOAD::ts/src/develop/workflows/submit.ts#- ``` - + ## Submitting workflows from a Restate service - + [**Submit/query/signal**](/develop/ts/service-communication): Call the workflow handlers in the same way as for Services and Virtual Objects. @@ -122,10 +123,10 @@ Have a look at the code example to get a better understanding of how workflows a ```ts CODE_LOAD::ts/src/develop/workflows/service.ts ``` - + ## Submitting workflows over HTTP - + [**Submit/query/signal**](/invoke/http#request-response-calls-over-http): Call any handler of the workflow in the same way as for Services and Virtual Objects. This returns the result of the handler once it has finished. @@ -137,9 +138,9 @@ Have a look at the code example to get a better understanding of how workflows a -H 'content-type: application/json' \ -d '{"email": "someone@restate.dev"}' ``` - + - + [**Attach/peek**](/invoke/http#retrieve-result-of-invocations-and-workflows): This lets you retrieve the result of a workflow or check if it's finished. @@ -149,7 +150,7 @@ Have a look at the code example to get a better understanding of how workflows a curl localhost:8080/restate/workflow/signup/someone/output ``` - + ## Inspecting workflows diff --git a/docs/invoke/http.mdx b/docs/invoke/http.mdx index 7eb96a66..e594b535 100644 --- a/docs/invoke/http.mdx +++ b/docs/invoke/http.mdx @@ -17,7 +17,7 @@ You can invoke handlers over HTTP with or without waiting for a response, and wi You can invoke services over HTTP 1.1 or higher. Request/response bodies should be encoded as JSON. - + ### Invoking Services Invoke `myHandler` of `myService` as follows: @@ -27,8 +27,8 @@ Request/response bodies should be encoded as JSON. -d '{"name": "Mary", "age": 25}' ``` - - + + ### Invoking Virtual Objects Invoke `myHandler` of `myVirtualObject` for `myKey` as follows: @@ -39,8 +39,8 @@ Request/response bodies should be encoded as JSON. -d '{"name": "Mary", "age": 25}' ``` - - + + ### Invoke Workflows Call the `run` handler of the `MyWorkflow` as follows: @@ -51,7 +51,7 @@ Request/response bodies should be encoded as JSON. -d '{"name": "Mary", "age": 25}' ``` - + Follow the same pattern for calling the other handlers of the workflow. diff --git a/docs/use-cases/workflows.mdx b/docs/use-cases/workflows.mdx index f1f4a1e9..6d186dd3 100644 --- a/docs/use-cases/workflows.mdx +++ b/docs/use-cases/workflows.mdx @@ -6,6 +6,7 @@ hide_table_of_contents: true hide_title: true --- +import clsx from "clsx"; import FeatureWidget from "../../src/components/FeatureWidget" import FeatureSpotlight from "../../src/components/FeatureSpotlight" import TwoColumnText from "../../src/components/TwoColumnText"; @@ -133,7 +134,7 @@ Implement the `run` function of your workflow, using the Restate SDK. ]}/> - + ### Latch on to a workflow A workflow runs exactly one time. @@ -142,7 +143,7 @@ Implement the `run` function of your workflow, using the Restate SDK. ```ts submit.ts CODE_LOAD::ts/src/use_cases/submit.ts ``` - +