Invocations

An invocation is a request to execute a handler that is part of either a service, or a virtual object.

There are three ways to invoke a handler:

HTTP requests

Send a request to the Restate Server (port 8080), with the handler name in the path, and the payload body.
Learn more

Programmatically

Use the SDK to send requests within Restate handlers. Or use generated HTTP clients anywhere else.
Learn more

Kafka events

Restate subscribes to a Kafka topic, and invokes a handler should for each message that arrives.
Learn more

All invocations are proxied through the Restate Server, which registers the request, routes the request to the correct handler, and drives the execution of the handler.

Invocations get a unique identifier. This identifier is used to track the progress of the invocation, and lets you correlate logs and metrics.

Invocation types

TypeScript
Java
Go
Python
Shell

Request-response invocations allow you to wait on a response from the handler.

restate_service.ts


async function myRestateHandler(ctx: restate.Context) {
  const greet = await ctx
    .serviceClient(greeter)
    .greet({ greeting: "Hi" });
}

plain_node_app.ts


const myPlainTSFunction = async () => {
  const rs = restate.connect({ url: "http://localhost:8080" });
  const greet = await rs
    .serviceClient(greeter)
    .greet({ greeting: "Hi" });
};

One-way invocations allow you to trigger an asynchronous action.

restate_service.ts


async function myRestateHandler(ctx: restate.Context) {
  ctx
    .serviceSendClient(greeter)
    .greet({ greeting: "Hi" });
}

plain_node_app.ts


const myPlainTSFunction = async () => {
  const rs = restate.connect({ url: "http://localhost:8080" });
  await rs
    .serviceSendClient(greeter)
    .greet({ greeting: "Hi" });
};

Delayed invocations allow you to schedule an invocation for a later point in time.

restate_service.ts


async function myRestateHandler(ctx: restate.Context) {
  ctx
    .serviceSendClient(greeter)
    .greet({ greeting: "Hi" }, restate.rpc.sendOpts({ delay: 1000 }));
}

plain_node_app.ts


const myPlainTSFunction = async () => {
  const rs = restate.connect({ url: "http://localhost:8080" });
  await rs
    .serviceSendClient(greeter)
    .greet({ greeting: "Hi" }, restate.rpc.sendOpts({ delay: 1000 }));
};

Request-response invocations allow you to wait on a response from the handler.

One-way invocations allow you to trigger an asynchronous action.

Delayed invocations allow you to schedule an invocation for a later point in time.

restate_service.ts


async function myRestateHandler(ctx: restate.Context) {
  ctx
    .serviceSendClient(greeter)
    .greet({ greeting: "Hi" });
}

plain_node_app.ts


const myPlainTSFunction = async () => {
  const rs = restate.connect({ url: "http://localhost:8080" });
  await rs
    .serviceSendClient(greeter)
    .greet({ greeting: "Hi" });
};

Learn more about service communication and the SDK clients in the TypeScript SDK.

Request-response invocations allow you to wait on a response from the handler.

RestateService.java


@Handler
public void myRestateHandler(Context ctx) {
  String greet =
      GreeterServiceClient.fromContext(ctx)
          .greet("Hi")
          .await();
}

PlainJavaService.java


public void myJavaHandler(Context ctx) {
  Client restate = Client.connect("http://localhost:8080");
  String greet =
      GreeterServiceClient.fromClient(restate)
          .greet("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.

RestateService.java


@Handler
public void myRestateHandler(Context ctx) {
  GreeterServiceClient.fromContext(ctx)
      .send()
      .greet("Hi");
}

PlainJavaService.java


public void myJavaHandler(Context ctx) {
  Client restate = Client.connect("http://localhost:8080");
  GreeterServiceClient.fromClient(restate)
      .send()
      .greet("Hi");
}

Delayed invocations allow you to schedule an invocation for a later point in time.

RestateService.java


@Handler
public void myRestateHandler(Context ctx) {
  GreeterServiceClient.fromContext(ctx)
      .send(Duration.ofMillis(1000))
      .greet("Hi");
}

PlainJavaService.java


public void myJavaHandler(Context ctx) {
  Client restate = Client.connect("http://localhost:8080");
  GreeterServiceClient.fromClient(restate)
      .send(Duration.ofMillis(1000))
      .greet("Hi");
}

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.

Delayed invocations allow you to schedule an invocation for a later point in time.

RestateService.java


@Handler
public void myRestateHandler(Context ctx) {
  String greet =
      GreeterServiceClient.fromContext(ctx)
          .greet("Hi")
          .await();
}

PlainJavaService.java


public void myJavaHandler(Context ctx) {
  Client restate = Client.connect("http://localhost:8080");
  String greet =
      GreeterServiceClient.fromClient(restate)
          .greet("Hi");
}

Learn more about service communication and the SDK clients in the TypeScript SDK.

Request-response invocations allow you to wait on a response from the handler.

restateservice.go


func (MyService) MyRestateHandler(ctx restate.Context) error {
	greet, err := restate.
		Service[string](ctx, "Greeter", "Greet").
		Request("Hi")
	return err
}

One-way invocations allow you to trigger an asynchronous action.

restateservice.go


func (MyService) MyRestateHandler(ctx restate.Context) error {
	restate.
		ServiceSend(ctx, "Greeter", "Greet").
		Send("Hi")
	return nil
}

Delayed invocations allow you to schedule an invocation for a later point in time.

restateservice.go


func (MyService) MyRestateHandler(ctx restate.Context) error {
	restate.
		ServiceSend(ctx, "Greeter", "Greet").
		Send("Hi", restate.WithDelay(1*time.Second))
	return nil
}

Request-response invocations allow you to wait on a response from the handler.

One-way invocations allow you to trigger an asynchronous action.

Delayed invocations allow you to schedule an invocation for a later point in time.

restateservice.go


func (MyService) MyRestateHandler(ctx restate.Context) error {
	restate.
		ServiceSend(ctx, "Greeter", "Greet").
		Send("Hi")
	return nil
}

Learn more about service communication in the Go SDK.

Request-response invocations allow you to wait on a response from the handler.

restate_service.py


@my_service.handler()
async def my_handler(ctx: Context, arg):
    greeting = await ctx.service_call(greet, arg="Hi")

One-way invocations allow you to trigger an asynchronous action.

restate_service.py


@my_service.handler()
async def my_handler(ctx: Context, arg):
    ctx.service_send(greet, arg="Hi")

Delayed invocations allow you to schedule an invocation for a later point in time.

restate_service.py


@my_service.handler()
async def my_handler(ctx: Context, arg):
    ctx.service_send(greet, arg="Hi", send_delay=timedelta(seconds=1))

Request-response invocations allow you to wait on a response from the handler.

One-way invocations allow you to trigger an asynchronous action.

Delayed invocations allow you to schedule an invocation for a later point in time.

restate_service.py


@my_service.handler()
async def my_handler(ctx: Context, arg):
    ctx.service_send(greet, arg="Hi")

Learn more about service communication and the SDK clients in the TypeScript SDK.

Request-response invocations allow you to wait on a response from the handler.


curl localhost:8080/GreeterService/greet \
-H 'content-type: application/json' \
-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.


curl localhost:8080/GreeterService/greet/send \
-H 'content-type: application/json' \
-d '"Hi"'

Delayed invocations allow you to schedule an invocation for a later point in time.


curl localhost:8080/GreeterService/greet/send?delay=10s \
-H 'content-type: application/json' \
-d '"Hi"'

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.

Delayed invocations allow you to schedule an invocation for a later point in time.


curl localhost:8080/GreeterService/greet/send \
-H 'content-type: application/json' \
-d '"Hi"'

Learn more about invoking services over HTTP.

Idempotent invocations

For HTTP requests, you can add an idempotency key to the header to make the invocation idempotent. Restate will then deduplicate requests with the same idempotency key, and will only execute the handler once. Duplicate requests will get the same response as the first request, or will latch on to the first invocation if it's still running.


curl localhost:8080/GreeterService/greet \
  -H 'idempotency-key: ad5472esg4dsg525dssdfa5loi' \
  -H 'content-type: application/json' \
  -d '"Hi"'

Note that, you don't need idempotency tokens for invocations that are invoked programmatically or via Kafka, as Restate will make sure that they are executed only once.

Inspecting invocations

Restate proxies and manages inbound as well as service-to-service invocations. This makes it a great source of observability data for your application. You can inspect invocations via the CLI.

terminal

$ restate services list
     NAME             REVISION  FLAVOR    DEPLOYMENT TYPE  DEPLOYMENT ID
 🌎  CartObject       1         ⬅️ 🚶🚶🚶  HTTP 2           dp_11pXug0mWsff2NOoRBZbOcV
 🌎  CheckoutService  1                   HTTP 2           dp_11pXug0mWsff2NOoRBZbOcV
 🌎  TicketObject     1         ⬅️ 🚶🚶🚶  HTTP 2           dp_11pXug0mWsff2NOoRBZbOcV

Restate also exposes traces via OpenTelemetry, which can be sent to your observability platform of choice (e.g. Jaeger). Have a look at the tracing documentation for more information.

Cancelling and killing invocations

The Restate CLI allows you to cancel or kill invocations. If necessary, you can register compensating actions in your handlers to ensure that the system remains consistent amid cancellations (blog post on graceful cancellations).

For cancellations, Restate will gracefully stop the handler by executing all compensation actions. For kills, Restate will immediately stop the handler without executing any compensation actions.

Invocations

HTTP requests

Programmatically

Kafka events

Invocation types​

Idempotent invocations​

Inspecting invocations​

Cancelling and killing invocations​

Invocation types

Idempotent invocations

Inspecting invocations

Cancelling and killing invocations