Restate Rust SDK

Restate is a system for easily building resilient applications using distributed durable async/await. This repository contains the Restate SDK for writing services using Rust.

Community

• 🤗️ Join our online community for help, sharing feedback and talking to the community.
• 📖 Check out our documentation to get quickly started!
• 📣 Follow us on Twitter for staying up to date.
• 🙋 Create a GitHub issue for requesting a new feature or reporting a problem.
• 🏠 Visit our GitHub org for exploring other repositories.

Using the SDK

Add Restate and Tokio as dependencies:

[dependencies]
restate-sdk = "0.1"
tokio = { version = "1", features = ["full"] }

Then you're ready to develop your Restate service using Rust:

use restate_sdk::prelude::*;

#[restate_sdk::service]
trait Greeter {
    async fn greet(name: String) -> HandlerResult<String>;
}

struct GreeterImpl;

impl Greeter for GreeterImpl {
    async fn greet(&self, _: Context<'_>, name: String) -> HandlerResult<String> {
        Ok(format!("Greetings {name}"))
    }
}

#[tokio::main]
async fn main() {
    // To enable logging/tracing
    // tracing_subscriber::fmt::init();
    HttpServer::new(
        Endpoint::builder()
            .with_service(GreeterImpl.serve())
            .build(),
    )
    .listen_and_serve("0.0.0.0:9080".parse().unwrap())
    .await;
}

Running on Lambda

The Restate Rust SDK supports running services on AWS Lambda using Lambda Function URLs. This allows you to deploy your Restate services as serverless functions.

Setup

First, enable the lambda feature in your Cargo.toml:

[dependencies]
restate-sdk = { version = "0.1", features = ["lambda"] }
tokio = { version = "1", features = ["full"] }

Basic Lambda Service

Here's how to create a simple Lambda service:

use restate_sdk::prelude::*;

#[restate_sdk::service]
trait Greeter {
    async fn greet(name: String) -> HandlerResult<String>;
}

struct GreeterImpl;

impl Greeter for GreeterImpl {
    async fn greet(&self, _: Context<'_>, name: String) -> HandlerResult<String> {
        Ok(format!("Greetings {name}"))
    }
}

#[tokio::main]
async fn main() {
    // To enable logging/tracing
    // check https://docs.aws.amazon.com/lambda/latest/dg/rust-logging.html#rust-logging-tracing

    // Build and run the Lambda endpoint
    LambdaEndpoint::run(
        Endpoint::builder()
            .bind(GreeterImpl.serve())
            .build(),
    )
    .await
    .unwrap();
}

Deployment

1. Install cargo-lambda

   cargo install cargo-lambda
   

2. Build your Lambda function:

   cargo lambda build --release --arm64 --output-format zip
   

3. Create a Lambda function with the following configuration:

   • Runtime: Amazon Linux 2023
   • Architecture: arm64

4. Upload your zip file to the Lambda function.

Logging

The SDK uses tokio's tracing crate to generate logs. Just configure it as usual through tracing_subscriber to get your logs.

Testing

The SDK uses Testcontainers to support integration testing using a Docker-deployed restate server. The restate-sdk-testcontainers crate provides a framework for initializing the test environment, and an integration test example in testcontainers/tests/test_container.rs.

#[tokio::test]
async fn test_container() {
    tracing_subscriber::fmt::fmt()
        .with_max_level(tracing::Level::INFO) // Set the maximum log level
        .init();

    let endpoint = Endpoint::builder().bind(MyServiceImpl.serve()).build();

    // simple test container intialization with default configuration
    //let test_container = TestContainer::default().start(endpoint).await.unwrap();

    // custom test container initialization with builder
    let test_container = TestContainer::builder()
        // optional passthrough logging from the resstate server testcontainer
        // prints container logs to tracing::info level
        .with_container_logging()
        .with_container(
            "docker.io/restatedev/restate".to_string(),
            "latest".to_string(),
        )
        .build()
        .start(endpoint)
        .await
        .unwrap();

    let ingress_url = test_container.ingress_url();

    // call container ingress url for /MyService/my_handler
    let response = reqwest::Client::new()
        .post(format!("{}/MyService/my_handler", ingress_url))
        .header("Accept", "application/json")
        .header("Content-Type", "*/*")
        .header("idempotency-key", "abc")
        .send()
        .await
        .unwrap();

    assert_eq!(response.status(), StatusCode::OK);

    info!(
        "/MyService/my_handler response: {:?}",
        response.text().await.unwrap()
    );
}

Versions

The Rust SDK is currently in active development, and might break across releases.

The compatibility with Restate is described in the following table:

(1) Note bind_with_options works only from Restate 1.4 onward.

(2) Note the new retry_policy options work only from Restate 1.5 onward. Check the in-code documentation for more details.

(3) Warning SDK versions < 0.4 are deprecated, and cannot be registered anymore. Check the Restate 1.5 release notes for more info.

Contributing

We’re excited if you join the Restate community and start contributing! Whether it is feature requests, bug reports, ideas & feedback or PRs, we appreciate any and all contributions. We know that your time is precious and, therefore, deeply value any effort to contribute!

Building the SDK locally

Prerequisites:

• Rust
• Just

To build and test the SDK:

just verify

Releasing

You need the Rust toolchain. To verify:

just verify

To release we use cargo-release:

cargo release <VERSION> --exclude test-services --workspace