Skip to main content

Service Communication

A handler can call another handler and wait for the response (request-response), or it can send a message without waiting for the response.

Exporting the service definition

Make sure you export the service definition of the service you want to call, as we did in the service example on the overview page:

export const MyService: typeof myService = { name: "MyService" };

Import this service definition in the service handler that wants to call it.

Request-response calls

Request-response calls are requests where the client waits for the response.


const response = await ctx.serviceClient(MyService).myHandler("Hi");


const response = await ctx.objectClient(MyVirtualObject, "Mary").myHandler("Hi");

  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".
  2. Specify the handler you want to call and supply the request.
  3. Await the call to retrieve the response.
No need for manual retry logic

These calls are proxied by Restate, and get logged in the journal. In case of failures, Restate takes care of retries.

Deadlocks with Virtual Objects

Request-response calls to Virtual Object can lead to deadlocks. When this happens, the Virtual Object remains locked and the system can't process any more requests. In this situation you'll have to unblock the Virtual Object manually by cancelling invocations. Some example cases:

  • Cross deadlock between Virtual Object A and B: A calls B, and B calls A, both using same keys.
  • Cyclical deadlock: A calls B, and B calls C, and C calls A again.

Sending messages

Handlers can send messages (a.k.a. one-way calls, or fire-and-forget calls), as follows:




ctx.objectSendClient(MyVirtualObject, "Mary").myHandler("Hi");

No need for message queues

Without Restate, you would usually put a message queue in between the two services, to guarantee the message delivery. Restate eliminates the need for a message queue because Restate durably logs the request and makes sure it gets executed.

Delayed calls

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:


ctx.serviceSendClient(MyService, { delay: 5000 }).myHandler("Hi");


ctx.objectSendClient(MyVirtualObject, "Mary", { delay: 5000 }).myHandler("Hi");

Scheduling async tasks

You can also use this functionality to schedule async tasks. Restate will make sure the task gets executed at the desired time.

Ordering guarantees in Virtual Objects

Invocations to a Virtual Object are executed serially. Invocations will execute in the same order in which they arrive at Restate. For example, assume a handler calls the same Virtual Object twice:

ctx.objectSendClient(MyVirtualObject, "Mary").myHandler("Hi!");
ctx.objectSendClient(MyVirtualObject, "Mary").myHandler("Hi again!");

It is guaranteed that the invocation on line 1 will execute before the invocation on line 2. It is not guaranteed though that invocation 2 will be executed immediately after invocation 1, as invocations coming from other handlers/sources, could interleave these two calls.