How me-diru/spin works
Project Type and Purpose
• Spin is an open-source Rust monorepo implementing a CLI and runtime framework for composing and running WebAssembly microservices.
• It provides commands to build, serve, and manage “Spin applications” (Wasm components + manifests), and a runtime that loads those components into a Wasmtime engine, wires up triggers (HTTP, Redis, etc.), host interfaces (KV, SQL, variables), and handles inbound/outbound calls.
High-Level System Components
a. CLI Layer (src/bin + src/commands)
• Parses user commands (spin build, spin up, spin new, etc.)
• Delegates to subcommands: build, up, doctor, plugins, templates, etc.
b. Build & Package (crates/build + crates/componentize + crates/common)
• Reads spin.toml manifest (crates/manifest)
• Invokes language toolchains (Cargo, Go, etc.) to compile Wasm
• Generates OCI images or local bundles
c. Loader (crates/loader + crates/oci)
• Reads manifests, resolves component binaries (local files, HTTP, OCI registry)
• Caches artifacts
• Verifies digests, applies file preopens and mounts
d. Runtime Core (crates/core + crates/trigger + crates/trigger-http + crates/trigger-redis + …)
• Initializes Wasmtime engine with component model
• Instantiates host interfaces / host components for:
• HTTP inbound triggers (crates/trigger-http)
• Redis inbound triggers (crates/trigger-redis)
• Outbound HTTP, Redis, MQTT, SQL (crates/outbound-*)
• KV storage, SQLite, MySQL, Postgres (crates/key-value-*, crates/sqlite-*)
• Variables provider (crates/variables, azure, env, vault)
• Telemetry (crates/telemetry)
• Manages component lifecycles, call routing, concurrency
e. Application Components (user Wasm binaries)
• Conform to the WebAssembly Component ABI (Wit interfaces in wit/)
• Invoked by runtime in response to triggers or API calls
f. External Services
• HTTP clients & servers
• Redis, SQL databases
• OCI registries
• Vault / environment variable stores
• Observability stack (Prometheus, Grafana, etc., under hack/o11y-stack)
Relationships and Data Flows
• CLI → Build submodule: reads spin.toml → invokes Cargo/Go → outputs .wasm + updated manifest
• CLI (spin up) → Loader: loads manifest & component binaries → Runtime Core
• Runtime Core → Wasmtime Engine → Instantiates component with host components
• Inbound Trigger (e.g., HTTP) → Runtime Core → Component’s exported handler → host interfaces
• Component calls host interface → Runtime Core → External service (e.g., writes KV) → returns to component
• Telemetry hooks intercept calls for metrics/traces
Architectural Patterns & Principles
• Microkernel/Plugin: Core engine + pluggable host interfaces (crates/outbound-*, crates/trigger-*)
• Component Model: uses WebAssembly component model (Wit definitions) to decouple language SDKs
• Layered CLI: command dispatch layers in src/commands
• Monorepo: each concern in a separate crate under crates/
• Clear separation of concerns: build vs. load vs. runtime vs. triggers vs. host protocols
Essential Elements
• Wasmtime engine at the center, since it’s the “kernel.”
• Manifest → loader → runtime path.
• Extensibility: plugin manager (crates/plugins) hooking into CLI and runtime.