Merge pull request #137 from itowlson/spin-3.5

Spin 3.5 updates

Author: itowlson

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,14 +111,15 @@ Build the Spin application
 * `-c`, `--component-id <COMPONENT_ID>` — Component ID to build. This can be specified multiple times. The default is all components
 * `-f`, `--from <APP_MANIFEST_FILE>` — 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 <HELP>` — Print help information
+* `--skip-target-checks <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 <UP>` — Run the application after building
 * `--version <VERSION>` — Print version information
 
 
 
 ## `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 <FORMAT>` — The format in which to list the templates
 
   Default value: `plain`
-
-  Possible values: `plain`, `json`
-
 * `--help <HELP>` — Print help information
 * `--installed <INSTALLED>` — List only installed plugins
 * `--summary <SUMMARY>` — List latest and installed versions of plugins
@@ -285,9 +283,6 @@ Search for plugins by name
 * `--format <FORMAT>` — The format in which to list the plugins
 
   Default value: `plain`
-
-  Possible values: `plain`, `json`
-
 * `--help <HELP>` — Print help information
 * `--version <VERSION>` — Print version information
 
@@ -444,7 +439,7 @@ Push a Spin application to a registry
 ###### **Options:**
 
 * `--annotation <ANNOTATIONS>` — Specifies the OCI image manifest annotations (in key=value format). Any existing value will be overwritten. Can be used multiple times
-* `--build <BUILD>` — Specifies to perform `spin build` before pushing the application
+* `--build <BUILD>` — Specifies to perform `spin build` (with the default options) before pushing the application
 * `--cache-dir <CACHE_DIR>` — Cache directory for downloaded registry data
 * `--compose <COMPOSE>` — Compose component dependencies before pushing the application.
 
@@ -566,7 +561,7 @@ Start the Spin application
 
 ###### **Options:**
 
-* `--build <BUILD>` — For local apps, specifies to perform `spin build` before running the application.
+* `--build <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 <COMPONENTS>` — [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
     <a href="https://crates.io/crates/clap-markdown"><code>clap-markdown</code></a>.
 </i></small>
-

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 = "<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.

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

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:<br/><br/>* `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}`<br/><br/>* `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).<br/><br/>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:<br/><br/>* `status_code`: The HTTP status code. Default is 200.<br/><br/>* `headers`: Table of header names and values. Default is no headers.<br/><br/>* `body`: The response body. Default is no response body. | { status_code = 404, body = "not found" } |
 
 ### Additional Fields for `trigger.redis` Tables
 

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: