FerrousPath

Nivel 3 · Sistemas· Lección 10 de 11 · 30 min

WebAssembly

Compilar Rust para el navegador y más allá — memoria lineal, la ABI en bruto que usa el laboratorio de este sitio, wasm-bindgen y WASI.

Qué es WebAssembly

WebAssembly (Wasm) es un formato binario compacto de instrucciones para una máquina de pila aislada (sandbox). Los navegadores lo ejecutan a una velocidad casi nativa junto a JavaScript; los runtimes independientes (Wasmtime, Wasmer) lo ejecutan en servidores, en el edge y como formato de plugins. Rust es uno de los lenguajes de origen mejor soportados porque no necesita recolector de basura ni un runtime grande.

Un módulo:

  • exporta e importa funciones cuyos parámetros y resultados son números: i32, i64, f32, f64;
  • es dueño de una memoria lineal: un array de bytes redimensionable que el anfitrión puede leer y escribir;
  • no puede tocar nada más, salvo lo que el anfitrión le pase como importación.

Todo lo que sea más rico que un número —cadenas, structs, arrays— es una convención construida sobre «un puntero y una longitud dentro de la memoria lineal».

El enfoque en bruto

El Laboratorio Wasm de este sitio está construido así, sin más herramientas que cargo. El crate está en wasm-labs/, en el repositorio.

# Cargo.toml
[lib]
crate-type = ["cdylib"]

[profile.release]
opt-level = 3
lto = true
panic = "abort"
strip = true
// src/lib.rs (extracto)

/// Reserva `len` bytes en la memoria lineal y devuelve el puntero a JavaScript.
#[unsafe(no_mangle)]
pub extern "C" fn buf_alloc(len: usize) -> *mut u8 {
    let mut v = Vec::<u8>::with_capacity(len);
    let p = v.as_mut_ptr();
    std::mem::forget(v); // la propiedad pasa a quien llama
    p
}

/// # Safety
/// `ptr` debe venir de `buf_alloc(len)`.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn buf_free(ptr: *mut u8, len: usize) {
    drop(unsafe { Vec::from_raw_parts(ptr, 0, len) });
}

/// Cuenta los primos menores que `n` con una criba.
#[unsafe(no_mangle)]
pub extern "C" fn count_primes(n: u32) -> u32 {
    let n = n as usize;
    if n < 2 { return 0; }
    let mut composite = vec![false; n];
    let mut count = 0;
    for i in 2..n {
        if !composite[i] {
            count += 1;
            // usize tiene 32 bits en wasm32: un simple `i * i` daría la vuelta para i > 65535.
            let mut j = i.saturating_mul(i);
            while j < n { composite[j] = true; j += i; }
        }
    }
    count
}

Es otra vez, exactamente, la lección de FFI: extern "C", nombres sin decorar, punteros crudos, transferencia explícita de la propiedad. Compílalo con:

rustup target add wasm32-unknown-unknown
cargo build --release --target wasm32-unknown-unknown

y cárgalo desde JavaScript:

const { instance } = await WebAssembly.instantiateStreaming(fetch('/wasm/labs.wasm'));
const { memory, buf_alloc, mandelbrot, count_primes } = instance.exports;

console.log(count_primes(1_000_000)); // los números pasan directamente

const len = 720 * 480 * 4;
const ptr = buf_alloc(len);                       // un entero: un desplazamiento en la memoria lineal
mandelbrot(ptr, 720, 480, -0.6, 0, 0.0044, 300);  // Rust escribe ahí los bytes RGBA
// Crea la vista DESPUÉS de la llamada: al crecer la memoria se desconectan las vistas anteriores.
const pixels = new Uint8ClampedArray(memory.buffer, ptr, len);
ctx.putImageData(new ImageData(pixels.slice(), 720, 480), 0, 0);

Abre el laboratorio y después lee en paralelo src/pages/[...locale]/labs.astro y wasm-labs/src/lib.rs. El módulo compilado completo ocupa unos 16 KiB.

wasm-bindgen: el enfoque ergonómico

Escribir a mano las convenciones de punteros no escala. wasm-bindgen genera el código de unión en las dos direcciones, y la herramienta wasm-pack compila y empaqueta el resultado para npm o para un empaquetador (bundler).

// crate: wasm-bindgen
use wasm_bindgen::prelude::*;

#[wasm_bindgen]
extern "C" {
    #[wasm_bindgen(js_namespace = console)]
    fn log(s: &str); // importa una función de JavaScript
}

#[wasm_bindgen]
pub fn greet(name: &str) -> String {
    log(&format!("greet called with {name}"));
    format!("Hello, {name}!")
}

#[wasm_bindgen]
pub struct Counter {
    count: u32,
}

#[wasm_bindgen]
impl Counter {
    #[wasm_bindgen(constructor)]
    pub fn new() -> Counter {
        Counter { count: 0 }
    }
    pub fn increment(&mut self) -> u32 {
        self.count += 1;
        self.count
    }
}

Desde JavaScript esto es greet("Ferris") y new Counter().increment(); las cadenas se copian por ti hacia y desde la memoria lineal. Los crates complementarios js-sys y web-sys exponen la biblioteca estándar de JavaScript y el DOM, y frameworks como Leptos, Yew y Dioxus construyen interfaces completas sobre ellos.

Restricciones prácticas

  • La frontera tiene un coste. Cada llamada cruza entre dos mundos, y las cadenas hay que transcodificarlas (UTF-8 ↔ UTF-16) y copiarlas. Diseña interfaces gruesas: una llamada que procese un búfer, no un millón de llamadas que procesen un byte.
  • Los hilos hay que activarlos. std::thread::spawn no funciona en wasm32-unknown-unknown. El paralelismo usa Web Workers con memoria compartida, tras las cabeceras de aislamiento entre orígenes (cross-origin isolation).
  • Nada de bloquear. El hilo principal del navegador no debe bloquearse; la E/S es asíncrona. wasm-bindgen-futures conecta los futuros de Rust con las promesas de JavaScript.
  • El tamaño importa. Usa opt-level = "s" o "z", LTO, panic = "abort" y ejecuta wasm-opt. Evita arrastrar la maquinaria de formato a módulos diminutos. twiggy muestra qué está ocupando espacio.
  • Pánicos. Instala console_error_panic_hook durante el desarrollo para que los pánicos impriman un mensaje en lugar de una trampa unreachable opaca.
  • 32 bits. usize tiene 32 bits; un módulo puede direccionar como máximo 4 GiB.

¿Es más rápido que JavaScript? En bucles numéricos ajustados sobre memoria tipada, normalmente sí, por un factor modesto: los JIT de JavaScript son excelentes. Prueba los benchmarks del laboratorio en dos navegadores distintos. Los argumentos más fuertes son un rendimiento predecible (sin calentamiento del JIT ni pausas del recolector), la reutilización en la web de bibliotecas de Rust existentes y el aislamiento.

Más allá del navegador: WASI y componentes

WASI es una interfaz de sistema estándar, así que std::fs, std::env y compañía funcionan fuera de un navegador:

rustup target add wasm32-wasip1
cargo build --release --target wasm32-wasip1
wasmtime run --dir . target/wasm32-wasip1/release/app.wasm

El anfitrión decide qué directorios y qué capacidades recibe el módulo: un aislamiento basado en capacidades. El Component Model (el target wasm32-wasip2, con las interfaces descritas en WIT) añade interfaces ricas y tipadas entre módulos escritos en lenguajes distintos, lo que convierte a Wasm en un formato serio para plugins y para serverless.

Ejercicios

  1. Compila wasm-labs tú mismo con npm run build:wasm. Añade una función exportada sum_bytes(ptr, len) -> u32 y llámala desde la consola del navegador con un búfer que rellenes desde JavaScript.
  2. Porta el count_primes del laboratorio a wasm-bindgen y compara el código de unión de JavaScript generado con el cargador escrito a mano.
  3. Escribe un programa WASI que cuente las líneas de un archivo, ejecútalo con Wasmtime y observa qué pasa cuando omites --dir.
  4. Mide el coste de la frontera: llama diez millones de veces desde JavaScript a una función exportada trivial add(a, b) y compáralo con una sola llamada que itere diez millones de veces dentro de Rust.

Comprueba lo que has entendido

Elige una respuesta para ver la explicación.

  1. 1.¿Cómo lee JavaScript un búfer de bytes producido por un módulo WebAssembly de Rust sin un generador de bindings?

  2. 2.¿Por qué JavaScript debe volver a crear su vista de array tipado después de llamar a un módulo que puede reservar memoria?

  3. 3.¿Qué plataforma (target) elegirías para una herramienta de línea de comandos que se ejecuta en Wasmtime con acceso a archivos?

Términos clave de esta lección

¿Has terminado la lección y los ejercicios?