Serving

Restate services can run in two ways: as an HTTP endpoint or as AWS Lambda functions.

Creating an HTTP endpoint

Java

1. Create a RestateHttpEndpointBuilder
2. Bind one or multiple services to it
3. Listen on the specified port (default 9080) for connections and requests.

import dev.restate.sdk.http.vertx.RestateHttpEndpointBuilder;

class MyApp {
  public static void main(String[] args) {
    RestateHttpEndpointBuilder.builder()
        .bind(new MyService())
        .bind(new MyVirtualObject())
        .bind(new MyWorkflow())
        .buildAndListen();
  }
}

Kotlin

1. Create a RestateHttpEndpointBuilder
2. Bind one or multiple services to it
3. Listen on the specified port (default 9080) for connections and requests.

import dev.restate.sdk.http.vertx.RestateHttpEndpointBuilder

fun main() {
  RestateHttpEndpointBuilder.builder()
      .bind(MyService())
      .bind(MyVirtualObject())
      .bind(MyWorkflow())
      .buildAndListen()
}

Creating a Lambda handler

Java

1. Add the dependency dev.restate:sdk-lambda:1.1.1.
2. Extend the class BaseRestateLambdaHandler
3. Override the register method
4. Bind one or multiple services to the builder

import dev.restate.sdk.lambda.BaseRestateLambdaHandler;
import dev.restate.sdk.lambda.RestateLambdaEndpointBuilder;

class MyLambdaHandler extends BaseRestateLambdaHandler {
  @Override
  public void register(RestateLambdaEndpointBuilder builder) {
    builder.bind(new MyService()).bind(new MyVirtualObject());
  }
}

Kotlin

1. Add the dependency dev.restate:sdk-lambda:1.1.1.
2. Extend the class BaseRestateLambdaHandler
3. Override the register method
4. Bind one or multiple services to the builder

import dev.restate.sdk.lambda.BaseRestateLambdaHandler
import dev.restate.sdk.lambda.RestateLambdaEndpointBuilder

class MyLambdaHandler : BaseRestateLambdaHandler() {
  override fun register(builder: RestateLambdaEndpointBuilder) {
    builder.bind(MyService()).bind(MyVirtualObject())
  }
}

Have a look at the deployment section for guidance on how to deploy your services on AWS Lambda.

Run on Lambda without handler changes

The implementation of your services and handlers remains the same for both deployment options.

Using Java 21 Virtual Threads

If you use a JVM >= 21, you can use virtual threads to run your services:

Java

builder.bind(
    // This is the class generated by the annotation processor
    new GreeterServiceDefinitionFactory().create(new Greeter()),
    new HandlerRunner.Options(Executors.newVirtualThreadPerTaskExecutor()));

Kotlin

builder.bind(
    // This is the class generated by the annotation processor
    GreeterServiceDefinitionFactory().create(Greeter()),
    HandlerRunner.Options(
        coroutineContext = Executors.newVirtualThreadPerTaskExecutor().asCoroutineDispatcher(),
    ),
)

Validating request identity

SDKs can validate that incoming requests come from a particular Restate instance. You can find out more about request identity in the Security docs. You will need to use the request identity dependency, for example in Gradle:

implementation("dev.restate:sdk-request-identity:1.1.1")

Java

import dev.restate.sdk.auth.signing.RestateRequestIdentityVerifier;
import dev.restate.sdk.http.vertx.RestateHttpEndpointBuilder;

class MySecureApp {
  public static void main(String[] args) {
    RestateHttpEndpointBuilder.builder()
        .bind(new MyService())
        // withClass(1:3) highlight-line
        .withRequestIdentityVerifier(
            RestateRequestIdentityVerifier.fromKeys(
                "publickeyv1_w7YHemBctH5Ck2nQRQ47iBBqhNHy4FV7t2Usbye2A6f"))
        .buildAndListen();
  }
}

Kotlin

import dev.restate.sdk.auth.signing.RestateRequestIdentityVerifier
import dev.restate.sdk.http.vertx.RestateHttpEndpointBuilder

fun main() {
  RestateHttpEndpointBuilder.builder()
      .bind(MyService())
      // withClass(1:5) highlight-line
      .withRequestIdentityVerifier(
          RestateRequestIdentityVerifier.fromKeys(
              "publickeyv1_w7YHemBctH5Ck2nQRQ47iBBqhNHy4FV7t2Usbye2A6f",
          ),
      )
      .buildAndListen()
}