Project Spin

Spin is a tool that allows developers to build, publish, and deploy WebAssembly workloads. It is the next version of the Fermyon runtime.

Take Spin for a spin

• Take Spin for a spin
• Build Spin CLI
• Build and Run an HTTP Application with Spin
  • Generate an HTTP Application Using a Spin Template
  • Build the Application
  • Run the Application Locally
• Publishing Interfaces
  • Publish the Spin HTTP Interface
  • Use Interface in HTTP Application

Build Spin CLI

Clone this repository and build the Spin CLI:

$ git clone https://github.com/fermyon/spin
$ cd spin && cargo build --release

Build and Run an HTTP Application with Spin

Generate an HTTP Application Using a Spin Template

Add a new Spin template based on the templates/spin-http directory from this repo:

$ spin templates add --local templates/spin-http --name spin-http
$ spin templates list
+---------------------------------------+
| Name        Repository   URL   Branch |
+=======================================+
| spin-http   local                     |
+---------------------------------------+

Create the application:

$ mkdir helloworld
# TODO: the name and path where the app is generated is wrong.
$ spin new --repo local --template spin-http --path .

Build the Application

In the application directory:

$ cargo build --release

Run the Application Locally

The configuration file spin.toml contains the information required for Spin to run the application locally:

$ export RUST_LOG=spin_engine=info,spin_http,wact=info
$ spin up --app spin.toml

2022-02-06T02:44:08.810806Z  INFO spin_http_engine: Processing request for application spin-hello-world on path /hello
2022-02-06T02:44:08.810897Z  INFO execute{component="hello"}: spin_http_engine: Executing request for component hello
2022-02-06T02:44:08.810918Z  INFO execute{component="hello"}: prepare_component{component="hello"}: spin_engine: Preparing component hello
2022-02-06T02:44:08.810936Z  INFO execute{component="hello"}: prepare_component{component="hello"}: store: spin_engine: Creating store.
2022-02-06T02:44:08.811318Z  INFO execute{component="hello"}: spin_http_engine: Request URI: "/hello"
2022-02-06T02:44:08.811553Z  INFO execute{component="hello"}: spin_http_engine: Response status code: 200
2022-02-06T02:44:08.811715Z  INFO execute{component="hello"}: spin_http_engine: Request finished, sending response.

The application is now ready, after starting, send a request using curl -i localhost:3000/hello:

$ curl -i localhost:3000/hello
HTTP/1.1 200 OK
content-length: 12
date: Sun, 06 Feb 2022 02:44:08 GMT

I'm a teapot

Publishing Interfaces

In the example above, the interface (.wit file) was copied over to the local HTTP application directory. You can also publish interfaces to a bindle registry for others to consume as well as pull interfaces from a bindle registry to use. The example below creates and publishes the spin http interface and then walks through how to consume it in the HTTP application from the previous example.

Publish the Spin HTTP Interface

Push the Spin HTTP interface to the registry (from the root of this repository). This step, together with starting the registry, will not be required once we set up a canonical registry instance:

$ wact interface publish --name fermyon/http --version 0.1.0 wit/ephemeral/spin-http.wit

Use Interface in HTTP Application

1. Update Cargo.toml to include the following dependency, component and interface information:

[...]
[dependencies]
    # The Wact dependency generates bindings that simplify working with interfaces.
    wact = { git = "https://github.com/fermyon/wact", rev = "93a9eaeba9205918dc214a6310c0bb6e33c0e3c8" }

[workspace]

# Metadata about this component.
[package.metadata.component]
    name = "spinhelloworld"

# This component implements the fermyon/http interface.
[package.metadata.component.exports]
    fermyon-http = { name = "fermyon/http", version = "0.1.0" }

2. Update the application to use wact to generate and use rust bindings. In src/lib.rs:

// Import the HTTP objects from the generated bindings.
use fermyon_http::{Request, Response};

// Generate Rust bindings for all interfaces in Cargo.toml.
wact::component!();

struct FermyonHttp {}
impl fermyon_http::FermyonHttp for FermyonHttp {
    // Implement the `handler` entrypoint for Spin HTTP components.
    fn handler(req: Request) -> Response {
        println!("Request: {:?}", req);
        Response {
            status: 418,
            headers: None,
            body: Some("I'm a teapot".as_bytes().to_vec()),
        }
    }
}

3. Remove *.wit files from local HTTP application directory

4. In the application directory, build the component:

$ cargo build --target wasm32-wasi --release
# OR
$ cargo component build --release

Run the application locally to test.