Journaling Results

Restate uses an execution log for replay after failures and suspensions. This means that non-deterministic results (e.g. database responses, UUID generation) need to be stored in the execution log. The SDK offers some functionalities to help you with this:

1. Journaled actions: Run any block of code and store the result in Restate. Restate replays the result instead of re-executing the block on retries.
2. CombineablePromise combinators: Log the order in which CombineablePromises are resolved/rejected, to ensure deterministic replay.
3. Random generators: Built-in helpers for generating stable UUIDs and random numbers.

Journaled actions

You can store the result of a (non-deterministic) operation in the Restate execution log (e.g. database requests, HTTP calls, etc). Restate replays the result instead of re-executing the operation on retries.

Here is an example of a database request for which the string response is stored in Restate:

const result = await ctx.run<string>(async () => doDbRequest());

You cannot invoke any methods on the Restate context within a side effect. This includes actions such as getting state, calling another service, and nesting other journaled actions.

You can store any result value that can be serialized as a Buffer with Buffer.from(JSON.stringify(yourObject)) and deserialized with JSON.parse(result.toString()) as T.

Immediately await journaled actions

Always immediately await ctx.run, before doing any other context calls. If not, you might bump into non-determinism errors during replay, because the journaled result can get interleaved with the other context calls in the journal in a non-deterministic way.

Combineable Promise combinators

Operations such as calls, awakeables, and sleep return a CombineablePromise. 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.

const sleepPromise = ctx.sleep(100);
const callPromise = ctx.serviceClient(MyService).myHandler("Hi");
const resultArray = await CombineablePromise.all([
  sleepPromise,
  callPromise,
]);

Restate provides the following deterministic combinators:

• CombineablePromise.all: similar to Promise.all().
• CombineablePromise.any: similar to Promise.any().
• CombineablePromise.race: similar to Promise.race().
• CombineablePromise.allSettled: similar to Promise.allSettled().

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.

Do not use this in cryptographic contexts.

const uuid = ctx.rand.uuidv4();

Generating random numbers

This returns a new pseudorandom float within the range [0,1]. This is the equivalent of JS Math.random() but deterministically replayable.

const randomNumber = ctx.rand.random();