From cf4923b04eb5668512ac5c6ac486fd804a18a55a Mon Sep 17 00:00:00 2001 From: itowlson Date: Tue, 28 Oct 2025 11:08:53 +1300 Subject: [PATCH] Spin 3.5 updates Signed-off-by: itowlson --- content/v3/cli-reference.md | 22 ++++++++-------------- content/v3/dynamic-configuration.md | 15 +++++++++++++-- content/v3/http-trigger.md | 19 +++++++++++++++++++ content/v3/manifest-reference.md | 1 + content/v3/writing-apps.md | 14 +++++++++++++- 5 files changed, 54 insertions(+), 17 deletions(-) diff --git a/content/v3/cli-reference.md b/content/v3/cli-reference.md index de1e32bf..355152e5 100644 --- a/content/v3/cli-reference.md +++ b/content/v3/cli-reference.md @@ -49,9 +49,9 @@ The Spin CLI * `add` — Scaffold a new component into an existing application * `build` — Build the Spin application -* `deploy` — Package and upload an application to the Fermyon Cloud. +* `deploy` — Package and upload an application to a deployment environment. * `doctor` — Detect and fix problems with Spin applications -* `login` — Log into the Fermyon Cloud. +* `login` — Log into a deployment environment. * `new` — Scaffold a new application based on a template * `plugins` — Install/uninstall Spin plugins * `registry` — Commands for working with OCI registries to distribute applications @@ -100,7 +100,7 @@ Scaffold a new component into an existing application Build the Spin application **Usage:** `spin USAGE: - build [OPTIONS] [--] [UP_ARGS]...` + build [OPTIONS] [UP_ARGS]...` ###### **Arguments:** @@ -111,6 +111,7 @@ Build the Spin application * `-c`, `--component-id ` — Component ID to build. This can be specified multiple times. The default is all components * `-f`, `--from ` — The application to build. This may be a manifest (spin.toml) file, or a directory containing a spin.toml file. If omitted, it defaults to "spin.toml" * `--help ` — Print help information +* `--skip-target-checks ` — By default, if the application manifest specifies one or more deployment targets, Spin checks that all components are compatible with those deployment targets. Specify this option to bypass those target checks * `-u`, `--up ` — Run the application after building * `--version ` — Print version information @@ -118,7 +119,7 @@ Build the Spin application ## `spin deploy` -Package and upload an application to the Fermyon Cloud. +Package and upload an application to a deployment environment. **Usage:** `spin USAGE: deploy` @@ -151,7 +152,7 @@ Detect and fix problems with Spin applications ## `spin login` -Log into the Fermyon Cloud. +Log into a deployment environment. **Usage:** `spin USAGE: login` @@ -259,9 +260,6 @@ List available or installed plugins * `--format ` — The format in which to list the templates Default value: `plain` - - Possible values: `plain`, `json` - * `--help ` — Print help information * `--installed ` — List only installed plugins * `--summary ` — List latest and installed versions of plugins @@ -285,9 +283,6 @@ Search for plugins by name * `--format ` — The format in which to list the plugins Default value: `plain` - - Possible values: `plain`, `json` - * `--help ` — Print help information * `--version ` — Print version information @@ -444,7 +439,7 @@ Push a Spin application to a registry ###### **Options:** * `--annotation ` — Specifies the OCI image manifest annotations (in key=value format). Any existing value will be overwritten. Can be used multiple times -* `--build ` — Specifies to perform `spin build` before pushing the application +* `--build ` — Specifies to perform `spin build` (with the default options) before pushing the application * `--cache-dir ` — Cache directory for downloaded registry data * `--compose ` — Compose component dependencies before pushing the application. @@ -566,7 +561,7 @@ Start the Spin application ###### **Options:** -* `--build ` — For local apps, specifies to perform `spin build` before running the application. +* `--build ` — For local apps, specifies to perform `spin build` (with the default options) before running the application. This is ignored on remote applications, as they are already built. * `-c`, `--component-id ` — [Experimental] Component ID to run. This can be specified multiple times. The default is all components @@ -614,4 +609,3 @@ Build and run the Spin application, rebuilding and restarting it when files chan This document was generated automatically by clap-markdown. - diff --git a/content/v3/dynamic-configuration.md b/content/v3/dynamic-configuration.md index a4e16463..210bdd16 100644 --- a/content/v3/dynamic-configuration.md +++ b/content/v3/dynamic-configuration.md @@ -23,6 +23,8 @@ url = "https://github.com/spinframework/spin-docs/blob/main/content/v3/dynamic-c - [LibSQL Storage Provider](#libsql-storage-provider) - [LLM Runtime Configuration](#llm-runtime-configuration) - [Remote Compute Provider](#remote-compute-provider) + - [`default` API](#default-api) + - [`open_ai` API](#open_ai-api) You can change the configuration for Spin application features such as [application variables](./variables), [key value storage](./kv-store-api-guide), [SQL storage](./sqlite-api-guide) @@ -389,10 +391,19 @@ The following is an example of how an application's `runtime-config.toml` file c type = "remote_http" url = "http://example.com" auth_token = "" +api_type = "default" ``` -Currently, the remote compute option requires an user to deploy their own LLM proxy service. You can find a reference implementation of a proxy service in the [`spin-cloud-gpu plugin repository`](https://github.com/fermyon/spin-cloud-gpu/blob/main/fermyon-cloud-gpu/src/index.ts). +By default, components will not have access to the LLM models unless granted explicit access through the `component.ai_models` entry in the component manifest within `spin.toml`. See [Serverless AI](./serverless-ai-api-guide) for more details. + +Remote compute supports two APIs, selected using the `api_type` field. + +#### `default` API + +If the `api_type` is `default`, Spin uses its own "Cloud GPU" API. This requires you to deploy your own LLM proxy service. You can find a reference implementation of a proxy service in the [`spin-cloud-gpu plugin repository`](https://github.com/fermyon/spin-cloud-gpu/blob/main/fermyon-cloud-gpu/src/index.ts). > If you have a Fermyon Cloud account, you can deploy a proxy service there using the [`cloud-gpu` plugin](https://github.com/fermyon/spin-cloud-gpu). -By default, components will not have access to the LLM models unless granted explicit access through the `component.ai_models` entry in the component manifest within `spin.toml`. See [Serverless AI](./serverless-ai-api-guide) for more details. +#### `open_ai` API + +If the `api_type` is `open_ai`, Spin uses the [OpenAI API](https://github.com/openai/openai-openapi). This API is offered by some commercial LLM providers. diff --git a/content/v3/http-trigger.md b/content/v3/http-trigger.md index 0ace3f5d..1b453e7f 100644 --- a/content/v3/http-trigger.md +++ b/content/v3/http-trigger.md @@ -16,6 +16,7 @@ url = "https://github.com/spinframework/spin-docs/blob/main/content/v3/http-trig - [Getting Request and Response Information](#getting-request-and-response-information) - [Additional Request Information](#additional-request-information) - [Inside HTTP Components](#inside-http-components) +- [Static Responses with the HTML Trigger](#static-responses-with-the-html-trigger) - [HTTP With Wagi (WebAssembly Gateway Interface)](#http-with-wagi-webassembly-gateway-interface) - [Wagi Component Requirements](#wagi-component-requirements) - [Request Handling in Wagi](#request-handling-in-wagi) @@ -393,6 +394,24 @@ But if you wish, and if your language supports it, you can implement the `incomi > The WASI family of specifications, and tool support for some component model features that WASI depends on, are not yet fully stabilized. If you implement `wasi-http` directly, you may need to do some trialing to find tool versions which work together and with Spin. +## Static Responses with the HTML Trigger + +You can write short, static responses within the HTTP trigger by setting `static_response` (instead of `component`): + +```toml +# Example use case: fallback 404 handling +[[trigger.http]] +route = "/..." +static_response = { status_code = 404, body = "not found" } + +# Example use case: redirect +[[trigger.http]] +route = "/bob" +static_response = { status_code = 302, headers = { location = "/users/bob" } } +``` + +Static responses may have only text or empty bodies. + ## HTTP With Wagi (WebAssembly Gateway Interface) A number of languages support WASI Preview 1 but not the component model. To enable developers to use these languages, Spin supports an diff --git a/content/v3/manifest-reference.md b/content/v3/manifest-reference.md index f65a474f..ca0d69f8 100644 --- a/content/v3/manifest-reference.md +++ b/content/v3/manifest-reference.md @@ -151,6 +151,7 @@ Each array entry contains a mix of common fields and trigger-specific fields. | `executor` | Optional | Table | How Spin should invoke the component. If present, this is a table. The `type` key is required and may have the values `"spin"` or `"wagi"`. If omitted. the default is `{ type = "spin"}`. See [the HTTP trigger documentation](http-trigger) for details. | `{ type = "wagi" }` | | | | | If `type = "spin"` there are no other keys defined. In this case, Spin calls the component using a standard Wasm component interface. Components built using Spin SDKs or Spin interface files use this convention. | `{ type = "spin" }` | | | | | If `type = "wagi"`, Spin calls the component's "main" (`_start`) function using [a CGI-like interface](https://github.com/deislabs/wagi). Components built using languages or toolchains that do not support Wasm interfaces will need to be called in this way. In this case, the following additional keys may be set:

* `argv` (optional): The string representation of the `argv` list that should be passed into the handler. `${SCRIPT_NAME}` will be replaced with the script name, and `${ARGS}` will be replaced with the query parameters of the request, formatted as arguments. The default is to follow the CGI specification, and pass `${SCRIPT_NAME} ${ARGS}`

* `entrypoint` (optional): The name of the function to call as the entry point to this handler. By default, it is `_start` (which in most languages translates to `main` in the source code).

See [the HTTP trigger documentation](http-trigger) for details. | `{ type = "wagi" }` | +| `static_response` | Optional | Table | The response Spin should give to requests on this route. A route may not specify both `static_response` and `component`. The response may contain the following fields, all optional:

* `status_code`: The HTTP status code. Default is 200.

* `headers`: Table of header names and values. Default is no headers.

* `body`: The response body. Default is no response body. | { status_code = 404, body = "not found" } | ### Additional Fields for `trigger.redis` Tables diff --git a/content/v3/writing-apps.md b/content/v3/writing-apps.md index 14747288..2312fbfd 100644 --- a/content/v3/writing-apps.md +++ b/content/v3/writing-apps.md @@ -27,6 +27,7 @@ url = "https://github.com/spinframework/spin-docs/blob/main/content/v3/writing-a - [Specifying Dependencies](#specifying-dependencies) - [Dependencies from a Registry](#dependencies-from-a-registry) - [Dependencies from a Local Component](#dependencies-from-a-local-component) + - [Dependencies from a Component in the Application](#dependencies-from-a-component-in-the-application) - [Dependencies from a URL](#dependencies-from-a-url) - [Mapping All Imports from a Package](#mapping-all-imports-from-a-package) - [Dependency Permissions](#dependency-permissions) @@ -454,7 +455,7 @@ During loading, Spin will download the package from the registry, locate its `se ### Specifying Dependencies -Spin supports three sources for dependencies. +Spin supports four sources for dependencies. #### Dependencies from a Registry @@ -483,6 +484,17 @@ To use a dependency from a component on your file system, specify the following | `path` | Required | The path to the Wasm file containing the component. | `"../validation/request-checker.wasm"` | | `export` | Optional | The name of the export in the package. If omitted, this defaults to the name of the import. | `"more-secure:checking-it-out/web"` | +#### Dependencies from a Component in the Application + +You can use a component in your application as a dependency by specifying the following fields: + +| Field | Required? | Description | Example | +|------------|-------------|----------------------------------------------------------------------------------------------|---------| +| `component` | Required | The name (ID) of the component. | `"request-checker"` | +| `export` | Optional | The name of the export in the package. If omitted, this defaults to the name of the import. | `"more-secure:checking-it-out/web"` | + +Components referenced as dependencies may not have any Spin runtime configuration, such as `files`, `allowed_outbound_hosts`, `variables`, etc., because these are determined by the 'main' component. They may have `build` sections. + #### Dependencies from a URL To use a dependency from an HTTP URL, such as a GitHub release, specify the following fields: