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

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.

restate_service.ts

plain_node_app.ts

async function myRestateHandler(ctx: restate.Context) {

const greet = await ctx.serviceClient(greeterService)

.greet({greeting: "Hi"});

const count = await ctx.objectClient(greetCounterObject, "Mary")

.greet({greeting: "Hi"});

}

Java

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

PlainJavaService.java

@Handler

public void myRestateHandler(Context ctx){

String greet = GreeterServiceClient.fromContext(ctx)

.greet("Hi")

.await();

int count = GreetCounterObjectClient.fromContext(ctx, "Mary")

.greet("Hi")

.await();

}

Shell

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 \

-H 'content-type: application/json' \

-d '"Hi"'

curl localhost:8080/GreetCounter/Mary/greet \

-H 'content-type: application/json' \

-d '"Hi"'

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.