Spin Framework

The componentize process utilizes specific adapters to transform plain WebAssembly (Wasm) modules into Wasm components that are compatible with WASI Preview 2. Depending on the version of wit-bindgen being used, different adapters are required:

1. Upstream WASI Preview 1 Adapters: Used for both commands and reactors when working with wit-bindgen version 0.5 and above. These are based on the Wasmtime 18.0.1 release.
2. Modified Spin Adapter: A custom adapter used for compatibility with wit-bindgen version 0.2. This adapter includes specific knowledge of Spin APIs to handle the different ABI used by older wit-bindgen modules.

The spin-componentize library converts a Spin module into a WebAssembly component.

Note that while the world specification may include both inbound-redis and inbound-http exports, spin-componentize will only export the specific interfaces that the original module actually exported.

Spin Factors is a redesigned inversion of control system used to organize independent feature sets (formerly loosely-coupled 'host components') into modular 'factors'. This architecture allows for better integration across different Spin embeddings, such as the Spin CLI and SpinKube, by providing standardized lifecycle hooks and managing an acyclic dependency graph between features.

Key lifecycle integration points include:

• Runtime startup
• Application initialization
• Runtime config parsing
• Component pre-instantiation
• Component instantiation
• Cleanup (post-execution)

When building release infrastructure (e.g., in GitHub Actions), you can sign blobs using cosign sign-blob. This method uses OIDC identities to generate short-lived certificates, eliminating the need for manual private key management.

To use this in a CI environment like GitHub Actions, ensure the job has id-token: write permissions. Use the --output-certificate flag to save the certificate and --output-signature to save the signature, which should then be released alongside the artifact.

$ cosign sign-blob \
    --output-certificate out/spin-v1.0.0-linux-amd64-keyless.pem \
    --output-signature out/spin-v1.0.0-linux-amd64-keyless.sig \
    --yes \
    spin

Run a Spin application directly from an OCI registry using the --oci flag with the spin up command. This will pull the necessary artifacts before serving the application.

$ spin up --oci ghcr.io/<username>/my-spin-application:v1

Note: The Spin documentation website is deprecated and primarily serves as a redirect to new documentation. To run the website locally:

1. Build Spin following the contributing guide.
2. Execute spin up from the documentation directory.
3. Access the website at http://localhost:3000.

$ spin up

Because Spin may process WebSocket frames using different instances or nodes in a cluster, you cannot rely on in-memory state (like mutexes) to manage connection or shared state. You must use a persistent store outside of the instance's memory.

Consistency Considerations:

• If using distributed, eventually consistent stores, users may not see each other's state changes immediately (e.g., in a chat app).
• To ensure reliability, you can use a store with global, strict serializability, or use an eventually consistent store that supports asynchronous notifications.

Spin Built-in Stores: As of the current implementation, Spin's built-in SQLite and key-value stores do not provide explicit consistency guarantees. For applications requiring strict consistency, you should provide your own external store such as PostgreSQL, MySQL, or Redis.

Distribute your Spin application to a compatible OCI registry using spin oci push. You can specify a custom reference and tag, or derive them from your spin.toml file.

Custom Reference/Tag: Provide the full registry path and tag as an argument.

Derived Reference/Tag: If you omit the argument, Spin derives the reference and tag from the name and version fields in spin.toml. For this to work, the name in spin.toml must contain the fully qualified reference (e.g., myregistry.com/myusername/myapp).

The spin login and spin deploy commands are implemented as part of the spin cloud plugin. To maintain backwards compatibility, the core Spin CLI aliases the standard spin login and spin deploy commands to their spin cloud counterparts. If the plugin is not installed, Spin will attempt to install it automatically upon the first invocation of these commands.

$ spin deploy
The `cloud` plugin is required. Installing now.
Plugin 'cloud' was installed successfully!
Uploading cloud_start version 0.1.0+XXXXXXXX...
Deploying...
Waiting for application to become ready... ready
Available Routes:
  cloud-start: https://cloud-start-xxxxxxxx.fermyon.app/ (wildcard)