Ejecutar Rust en Wippy

Compila un componente WebAssembly en Rust y ejecútalo como funciones, comandos CLI y endpoints HTTP.

Qué Vamos a Construir

Un componente Rust con cuatro funciones exportadas:

greet - Recibe un nombre, retorna un saludo
add - Suma dos enteros
fibonacci - Calcula el n-ésimo número de Fibonacci
list-files - Lista archivos en un directorio montado

Expondremos estas como funciones invocables, un comando CLI y un endpoint HTTP.

Prerrequisitos

Rust toolchain con el target wasm32-wasip1
cargo-component

rustup target add wasm32-wasip1
cargo install cargo-component

Estructura del Proyecto

rust-wasm-demo/
├── demo/                    # Rust component
│   ├── Cargo.toml
│   ├── wit/
│   │   └── world.wit       # WIT interface
│   └── src/
│       └── lib.rs           # Implementation
└── app/                     # Wippy application
    ├── wippy.lock
    └── src/
        ├── _index.yaml      # Infrastructure
        └── demo/
            ├── _index.yaml  # CLI processes
            └── wasm/
                ├── _index.yaml          # WASM entries
                └── demo_component.wasm  # Compiled binary

Paso 1: Crear la Interfaz WIT

WIT (WebAssembly Interface Types) define el contrato entre el host y el guest:

Crea demo/wit/world.wit:

package component:demo;

world demo {
    export greet: func(name: string) -> string;
    export add: func(a: s32, b: s32) -> s32;
    export fibonacci: func(n: u32) -> u64;
    export list-files: func(path: string) -> string;
}

Cada export se convierte en una función que Wippy puede invocar.

Paso 2: Implementar en Rust

Crea demo/Cargo.toml:

[package]
name = "demo"
version = "0.1.0"
edition = "2024"

[dependencies]
wit-bindgen-rt = { version = "0.44.0", features = ["bitflags"] }

[lib]
crate-type = ["cdylib"]

[profile.release]
opt-level = "s"
lto = true

[package.metadata.component]
package = "component:demo"

Crea demo/src/lib.rs:

#[allow(warnings)]
mod bindings;

use bindings::Guest;

struct Component;

impl Guest for Component {
    fn greet(name: String) -> String {
        format!("Hello, {}!", name)
    }

    fn add(a: i32, b: i32) -> i32 {
        a + b
    }

    fn fibonacci(n: u32) -> u64 {
        if n <= 1 {
            return n as u64;
        }
        let (mut a, mut b) = (0u64, 1u64);
        for _ in 2..=n {
            let next = a + b;
            a = b;
            b = next;
        }
        b
    }

    fn list_files(path: String) -> String {
        let mut result = String::new();
        match std::fs::read_dir(&path) {
            Ok(entries) => {
                for entry in entries {
                    match entry {
                        Ok(e) => {
                            let name = e.file_name().to_string_lossy().to_string();
                            let meta = e.metadata();
                            let (kind, size) = match meta {
                                Ok(m) => {
                                    let kind = if m.is_dir() { "dir" } else { "file" };
                                    (kind, m.len())
                                }
                                Err(_) => ("?", 0),
                            };
                            let line = format!("{:<6} {:>8}  {}", kind, size, name);
                            println!("{}", line);
                            result.push_str(&line);
                            result.push('\n');
                        }
                        Err(e) => {
                            let line = format!("error: {}", e);
                            eprintln!("{}", line);
                            result.push_str(&line);
                            result.push('\n');
                        }
                    }
                }
            }
            Err(e) => {
                let line = format!("cannot read {}: {}", path, e);
                eprintln!("{}", line);
                result.push_str(&line);
                result.push('\n');
            }
        }
        result
    }
}

bindings::export!(Component with_types_in bindings);

El módulo bindings es generado por cargo-component a partir de la definición WIT.

Paso 3: Compilar el Componente

cd demo
cargo component build --release

Esto produce target/wasm32-wasip1/release/demo.wasm. Cópialo a tu aplicación Wippy:

mkdir -p ../app/src/demo/wasm
cp target/wasm32-wasip1/release/demo.wasm ../app/src/demo/wasm/demo_component.wasm

Obtiene el hash SHA-256 para verificación de integridad:

sha256sum ../app/src/demo/wasm/demo_component.wasm

Paso 4: Aplicación Wippy

Infraestructura

Crea app/src/_index.yaml:

version: "1.0"
namespace: demo

entries:
  - name: gateway
    kind: http.service
    meta:
      comment: HTTP server
    addr: ":8090"
    lifecycle:
      auto_start: true

  - name: api
    kind: http.router
    meta:
      comment: Public API router
      server: demo:gateway
    prefix: /

  - name: processes
    kind: process.host
    lifecycle:
      auto_start: true

  - name: terminal
    kind: terminal.host
    lifecycle:
      auto_start: true

Funciones WASM

Crea app/src/demo/wasm/_index.yaml:

version: "1.0"
namespace: demo.wasm

entries:
  - name: assets
    kind: fs.directory
    meta:
      comment: Filesystem with WASM binaries
    directory: ./src/demo/wasm

  - name: greet_function
    kind: function.wasm
    meta:
      comment: Greet function via payload transport
    fs: demo.wasm:assets
    path: /demo_component.wasm
    hash: sha256:YOUR_HASH_HERE
    method: greet
    pool:
      type: inline

  - name: add_function
    kind: function.wasm
    meta:
      comment: Add function via payload transport
    fs: demo.wasm:assets
    path: /demo_component.wasm
    hash: sha256:YOUR_HASH_HERE
    method: add
    pool:
      type: inline

  - name: fibonacci_function
    kind: function.wasm
    meta:
      comment: Fibonacci function via payload transport
    fs: demo.wasm:assets
    path: /demo_component.wasm
    hash: sha256:YOUR_HASH_HERE
    method: fibonacci
    pool:
      type: inline

Puntos clave:

Una sola entrada fs.directory proporciona el binario WASM
Múltiples funciones referencian el mismo binario con diferentes valores de method
El campo hash verifica la integridad del binario al momento de carga
El pool inline crea una instancia nueva por llamada

Funciones con WASI

La función list-files accede al sistema de archivos, por lo que necesita imports WASI:

  - name: list_files_function
    kind: function.wasm
    meta:
      comment: Filesystem listing with WASI mounts
    fs: demo.wasm:assets
    path: /demo_component.wasm
    hash: sha256:YOUR_HASH_HERE
    method: list-files
    imports:
      - wasi:cli
      - wasi:io
      - wasi:clocks
      - wasi:filesystem
    wasi:
      mounts:
        - fs: demo.wasm:assets
          guest: /data
    pool:
      type: inline

La sección wasi.mounts mapea una entrada del sistema de archivos de Wippy a una ruta del guest. Dentro del módulo WASM, /data apunta al directorio demo.wasm:assets.

Comandos CLI

Crea app/src/demo/_index.yaml:

version: "1.0"
namespace: demo.cli

entries:
  - name: greet
    kind: process.wasm
    meta:
      comment: Greet someone via WASM
      command:
        name: greet
        short: Greet someone via WASM
    fs: demo.wasm:assets
    path: /demo_component.wasm
    hash: sha256:YOUR_HASH_HERE
    method: greet

  - name: ls
    kind: process.wasm
    meta:
      comment: List files from mounted WASI filesystem
      command:
        name: ls
        short: List files from mounted directory
    fs: demo.wasm:assets
    path: /demo_component.wasm
    hash: sha256:YOUR_HASH_HERE
    method: list-files
    imports:
      - wasi:cli
      - wasi:io
      - wasi:clocks
      - wasi:filesystem
    wasi:
      mounts:
        - fs: demo.wasm:assets
          guest: /data

El bloque meta.command registra el proceso como un comando CLI con nombre. El comando greet no necesita imports WASI ya que sólo usa operaciones de strings. El comando ls necesita acceso al sistema de archivos.

Endpoint HTTP

Agrega a app/src/demo/wasm/_index.yaml:

  - name: http_greet
    kind: function.wasm
    meta:
      comment: Greet exposed via wasi-http transport
    fs: demo.wasm:assets
    path: /demo_component.wasm
    hash: sha256:YOUR_HASH_HERE
    method: greet
    transport: wasi-http
    pool:
      type: inline

  - name: http_greet_endpoint
    kind: http.endpoint
    meta:
      comment: HTTP POST endpoint for WASM greet
      router: demo:api
    method: POST
    path: /greet
    func: http_greet

El transporte wasi-http mapea el contexto de solicitud/respuesta HTTP a los argumentos y resultados WASM.

Paso 5: Inicializar y Ejecutar

cd app
wippy init

Ejecutar Comandos CLI

# List available commands
wippy run list

Available commands:
  greet    Greet someone via WASM
  ls       List files from mounted directory

# Run greet
wippy run greet

# Run ls to list mounted directory
wippy run ls

Ejecutar como Servicio

wippy run

Esto inicia el servidor HTTP en el puerto 8090. Prueba el endpoint:

curl -X POST http://localhost:8090/greet

Llamar desde Lua

Las funciones WASM se invocan de la misma manera que las funciones Lua:

local funcs = require("funcs")

local greeting, err = funcs.call("demo.wasm:greet_function", "World")
-- greeting: "Hello, World!"

local sum, err = funcs.call("demo.wasm:add_function", 6, 7)
-- sum: 13

local fib, err = funcs.call("demo.wasm:fibonacci_function", 10)
-- fib: 55

Siguientes Pasos

Descripción General de WASM - Descripción general del runtime WebAssembly
Funciones WASM - Referencia de configuración de funciones
Procesos WASM - Referencia de configuración de procesos
Funciones Host - Imports WASI disponibles
Referencia CLI - Documentación de comandos CLI