Skip to main content

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​

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.

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.

JaegerJaeger

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.