The Spin Rust SDK

The Spin Rust SDK makes it easy to build Spin components in Rust.

Spin documentation

This README file provides a few examples, such as writing Spin HTTP components in Rust and making outbound HTTP requests. For comprehensive information, visit the official Spin Documentation website. This resource includes a page on installing Spin, a quickstart guide, and a language support overview page. The latter lists all of Spin's features—including key-value storage, SQLite, MySQL, Redis, Serverless AI, etc.—and their implementation in specific languages such as Rust, TS/JS, Python, and TinyGo.

Writing Spin HTTP Components in Rust

This library simplifies writing Spin HTTP components. Below is an example of such a component:

// lib.rs
use spin_sdk::http::{IntoResponse, Request};
use spin_sdk::http_service;

/// A simple Spin HTTP component.
#[http_service]
async fn hello_world(_req: Request) -> impl IntoResponse {
    "Hello, Spin"
}

The important things to note about the function above are:

• the spin_sdk::http_service macro marks the function as the entry point for the Spin component,
• in the function signature, req can be the built-in Request type (a re-export of http::Request) or any type that implements FromRequest,
• the response type can be anything that implements IntoResponse, including &str, String, http::StatusCode, http::Response<T>, a tuple of (StatusCode, body), or Result<impl IntoResponse>.

Making Outbound HTTP Requests

Let's see an example where the component makes an outbound HTTP request to a server, modifies the result, and then returns it:

use spin_sdk::http::{send, EmptyBody, IntoResponse, Request, Response};
use spin_sdk::http_service;

#[http_service]
async fn handle_hello_world(_req: Request) -> anyhow::Result<impl IntoResponse> {
    // Create the outbound request object
    let outgoing = Request::get("https://random-data-api.fermyon.app/animals/json")
        .body(EmptyBody::new())
        .unwrap();

    // Send the request and await the response
    let resp: Response = send(outgoing).await?;

    Ok(resp)
}

For the component above to be allowed to make the outbound HTTP request, the destination host must be declared, using the allowed_outbound_hosts configuration, in the Spin application's manifest (the spin.toml file):

spin_manifest_version = 2

[application]
name = "hello_world"
version = "0.1.0"
authors = ["Your Name <your-name@example.com>"]
description = "An example application"

[[trigger.http]]
route = "/..."
component = "hello-world"

[component.hello-world]
source = "target/wasm32-wasip2/release/hello_world.wasm"
allowed_outbound_hosts = ["https://random-data-api.fermyon.app"]
[component.hello-world.build]
command = "cargo build --target wasm32-wasip2 --release"
watch = ["src/**/*.rs", "Cargo.toml"]

Building and Running the Spin Application

Spin build can be used to build all components defined in the Spin manifest file at the same time, and also has a flag that starts the application after finishing the compilation, spin build --up:

$ spin build --up
Building component hello-world with `cargo build --target wasm32-wasip2 --release`
    Finished release [optimized] target(s) in 0.12s
Finished building all Spin components
Logging component stdio to ".spin/logs/"

Serving http://127.0.0.1:3000
Available Routes:
  hello-world: http://127.0.0.1:3000 (wildcard)

Once our application is running, we can make a request (by visiting http://localhost:3000/ in a web browser) or using curl as shown below:

$ curl -i localhost:3000
HTTP/1.1 200 OK
content-length: 77
content-type: application/json

{"timestamp":1702599575198,"fact":"Sharks lay the biggest eggs in the world"}