DOCSEARCHbyAlgolia
Submit Docs

Spin Framework

repository·main·Indexed 11 days ago

https://github.com/fermyon/spin

An open-source framework for building, deploying, and running fast, secure, and composable cloud microservices using WebAssembly (Wasm) and the WebAssembly component model. It includes the spin-cli for application scaffolding, building, and local execution, as well as the spin-componentize library for transforming Wasm modules into WASI Preview 2 compatible components.

Tokens
138.6K
Snippets
456
Records
607
Agent score
91%

What's inside Spin

  2. What is the Test Codegen Macro?

    main
    The test-codegen-macro is a Rust macro designed to automate the creation of #[test] annotated functions. It generates these test functions dynamically based on the existing file directory structure. This is primarily used within the Spin runtime tests to reduce boilerplate: when a new runtime test is added to the directory, the macro automatically produces the corresponding test function, eliminating the need for manual test function implementation for every new runtime test.

  4. Understand Host headers during service chaining

    main

    When a request is chained via spin.internal, Spin manages the Host header to prevent spoofing and ensure correct routing:

    1. Header Overwriting: Spin will overwrite any Host header set in the original request with Host: <component>.spin.internal.
    2. Stripping: Spin strips any incoming Host: *.spin.internal headers from routed requests to maintain security.
    3. Metadata: Spin may set additional headers like spin-full-url (e.g., spin-path-info) to assist the receiving component in understanding the request context.

  5. Configure dependency configuration inheritance

    main

    By default, Spin components are isolated. Dependencies do not inherit the configuration (capabilities) of the parent component. If a dependency attempts to use a capability (like an outbound host) that isn't explicitly granted to it, it will fail.

    To allow dependencies to use the parent component's configuration, set dependencies_inherit_configuration = true at the component level.

    Inheritable configurations include:

    • allowed_outbound_hosts
    • key_value_stores
    • variables
    • ai_models
    • files
    • environment
    [component."infra-dashboard"]
allowed_outbound_hosts = ["https://s3.us-west-2.amazonaws.com"]
dependencies_inherit_configuration = true

[component."infra-dashboard".dependencies]
"aws:client" = "1.0.0"

  6. Enable service chaining for in-process HTTP requests

    main

    Service chaining allows Spin components to make HTTP requests to other components within the same application in-memory, bypassing the network stack. This reduces overhead and avoids network latency or bandwidth charges.

    To use service chaining, you must explicitly declare the destination components in your allowed_outbound_hosts configuration.

    Note: For the initial release, service chaining is only supported when calling from an HTTP component to another HTTP component.

    # Example of allowing chaining to a specific component
allowed_outbound_hosts = [
    "http://accounts.spin.internal",
    "http://*.spin.internal"
]

  7. How the `spin cloud` plugin architecture works

    main

    To allow the core Spin runtime to remain stable while the Fermyon Cloud API evolves, cloud-specific functionality is decoupled into a plugin.

    • Core Spin CLI: Handles the runtime and local development.
    • spin cloud plugin: Handles packaging, distribution, and communication with the Fermyon Cloud API.

    Users can access cloud functionality via the direct plugin commands or the legacy aliases:

    • spin login $\rightarrow$ spin cloud login
    • spin deploy $\rightarrow$ spin cloud deploy

    If you need to update the plugin to access new cloud features, use the standard plugin management command.

    spin plugin update

  8. How Spin uses Sigstore for keyless signing

    main

    Spin uses Sigstore (specifically Cosign v2.0) to provide keyless signatures for its releases. This approach avoids the complexities and risks of long-lived private key management (like OpenPGP) by using ephemeral keys bound to an OIDC identity.

    The Workflow

    1. Identity: The build process uses an OIDC provider (GitHub Actions) to prove identity.
    2. Certificate Issuance: Fulcio issues a short-lived x509 certificate bound to that OIDC identity.
    3. Signing: cosign sign-blob uses the certificate to sign the artifact.
    4. Transparency: The signing event is recorded in Rekor, a transparency log that allows users to audit the signature.

    This ensures that a user can verify not just that the file hasn't changed, but that it was specifically produced by the official Spin project GitHub infrastructure.

  9. Handle failures in chained components

    main
    If a component being called via service chaining fails (e.g., it 'traps'), the error is caught by the Spin HTTP infrastructure. Instead of the failure taking down the calling component, the caller will receive a standard 500 HTTP response. This allows the application to handle downstream failures gracefully using standard HTTP error handling logic.

  10. Define configuration slots in Spin applications

    main

    Configuration in Spin is managed through "slots" defined within a parent (either a component or an application). Each slot is identified by a unique string key.

    Key Constraints:

    • Must start with a letter.
    • Must consist only of lowercase ASCII alphanumerics and underscores ([a-z0-9_]).
    • Only one underscore is allowed at a time, and it cannot be at the end of the key (to ensure compatibility with environment variable delimiters like __).

    Slot Properties:

    • Required vs. Optional: A slot must either be marked as required = true or provided with a default value.
    • Secrets: A slot can be marked as secret = true. Values for secret slots should be handled with care and should not be logged.
    • Template Strings: Default values can use template strings to reference other slots using the {{ key_name }} syntax.
    [variables]
required_key = { required = true }
optional_key = { default = "default_value" }
secret_key = { required = true, secret = true }

# Using template strings in defaults
key1 = { required = true }
key2 = { default = "prefix-{{ key1 }}-suffix" }

  11. Understand middleware capability inheritance and permissions

    main

    In Spin, capabilities (like network access or key-value stores) are owned by application components. Dependencies and middleware can only inherit these capabilities.

    How it works for Middleware

    1. Detection: spin deps add inspects the middleware's component-level imports and matches them against capability sets (e.g., wasi:http/outgoing-handler matches allowed_outbound_hosts) using semver-compatible matching.
    2. Inheritance: When adding middleware to a trigger, you select which capabilities to inherit from the trigger's component.
    3. Validation: If the middleware requires a capability (e.g., allowed_outbound_hosts) but the component it is attached to does not declare it in its manifest, spin deps add will issue a warning.

    Example Warning: WARNING: This middleware inherits 'allowed_outbound_hosts' but component 'admin-ops' does not currently declare any allowed_outbound_hosts. The middleware will have no network access at runtime until you configure allowed_outbound_hosts on 'admin-ops'.

  12. Extend Spin functionality with plugins

    main

    Spin plugins allow users to add new subcommands and functionality to the Spin CLI. While current plugins are primarily executables that add subcommands, the architecture is designed to eventually support extending Spin's internal features, such as adding new Spin triggers (e.g., a timer trigger that executes components at specific intervals).

    Users can install these extensions using the spin plugin install command.

    spin plugin install <plugin-name>