Merge pull request #29 from itowlson/spin-3.2-backports

Spin 3.2 backports

Author: itowlson

content/v3/ai-sentiment-analysis-api-tutorial.md

@@ -736,9 +736,6 @@ func performSentimentAnalysis(w http.ResponseWriter, r *http.Request, ps spinhtt
 		return
 	}
 }
-
-func main() {}
-
 ```
 
 {{ blockEnd }}

content/v3/build.md

@@ -135,7 +135,7 @@ The build command calls TinyGo with the WASI backend and appropriate options:
 
 ```toml
 [component.hello.build]
-command = "tinygo build -target=wasi -gc=leaking -no-debug -o main.wasm main.go"
+command = "tinygo build -target=wasip1 -gc=leaking -buildmode=c-shared -no-debug -o main.wasm ."
 ```
 
 {{ blockEnd }}

content/v3/go-components.md

@@ -30,7 +30,7 @@ Using TinyGo to compile components for Spin is currently required, as the
 
 ## Versions
 
-TinyGo `0.30.0` is recommended, which requires Go `v1.19+`.
+TinyGo `0.35.0` is recommended, which requires Go `v1.22+`. Older versions of TinyGo may not support the command-line flags used when building Spin applications.
 
 ## HTTP Components
 
@@ -61,16 +61,14 @@ func init() {
   fmt.Fprintln(w, "Hello Fermyon!")
  })
 }
-
-func main() {}
 ```
 
 The Spin HTTP component (written in Go) can be built using the `tingygo` toolchain:
 
 <!-- @selectiveCpy -->
 
 ```bash
-$ tinygo build -o main.wasm -target=wasi main.go
+$ tinygo build -target=wasip1 -gc=leaking -buildmode=c-shared -no-debug -o main.wasm .
 ```
 
 Once built, we can run our Spin HTTP component using the Spin up command:
@@ -141,16 +139,14 @@ func init() {
   }
  })
 }
-
-func main() {}
 ```
 
 The Outbound HTTP Request example above can be built using the `tingygo` toolchain:
 
 <!-- @selectiveCpy -->
 
 ```bash
-$ tinygo build -o main.wasm -target=wasi main.go
+$ tinygo build -target=wasip1 -gc=leaking -buildmode=c-shared -no-debug -o main.wasm .
 ```
 
 Before we can execute this component, we need to add the
@@ -228,9 +224,6 @@ func init() {
   return nil
  })
 }
-
-// main function must be included for the compiler but is not executed.
-func main() {}
 ```
 
 The manifest for a Redis application must contain the address of the Redis instance. This is set at the application level:
@@ -255,7 +248,7 @@ component = "echo-message"
 [component.echo-message]
 source = "main.wasm"
 [component.echo-message.build]
-command = "tinygo build -target=wasi -gc=leaking -no-debug -o main.wasm main.go"
+command = "tinygo build -target=wasip1 -gc=leaking -buildmode=c-shared -no-debug -o main.wasm ."
 ```
 
 The application will connect to `redis://localhost:6379`, and for every new message
@@ -351,8 +344,6 @@ func init() {
   }
  })
 }
-
-func main() {}
 ```
 
 As with all networking APIs, you must grant access to Redis hosts via the `allowed_outbound_hosts` field in the application manifest:

content/v3/http-outbound.md

@@ -7,6 +7,7 @@ url = "https://github.com/spinframework/spin-docs/blob/main/content/spin/v3/http
 
 ---
 - [Using HTTP From Applications](#using-http-from-applications)
+- [Restrictions](#restrictions)
 - [Granting HTTP Permissions to Components](#granting-http-permissions-to-components)
   - [Configuration-Based Permissions](#configuration-based-permissions)
 - [Making HTTP Requests Within an Application](#making-http-requests-within-an-application)
@@ -232,10 +233,14 @@ However, the wildcard implies that the component requires _all other_ components
 
 To make an HTTP request to another route with your application, you can pass just the route as the URL. For example, if you make an outbound HTTP request to `/api/customers/`, Spin prepends the route with whatever host the application is running on. It also replaces the URL scheme (`http` or `https`) with the scheme of the current HTTP request. For example, if the application is running in the cloud, Spin changes `/api` to `https://.../api`.
 
+> You can also use the special host `self.alt` to perform self-requests by route. This is important for the JavaScript `fetch` wrapper, which handles relative requests in a way that doesn't work with `allowed_outbound_hosts`. For example, you would write `fetch('http://self.alt/api')`.
+> 
 In this way of doing self-requests, the request undergoes normal HTTP processing once Spin has prepended the host. For example, in a cloud deployment, the request passes through the network, and potentially back in through a load balancer or other gateway. The benefit of this is that it allows load to be distributed across the environment, but it may count against your use of bandwidth.
 
-You must still grant permission by including `self` in `allowed_outbound_hosts`:
+You must still grant permission by including `self` or `self.alt` in `allowed_outbound_hosts`:
 
 ```toml
-allowed_outbound_hosts = ["http://self", "https://self"]
+allowed_outbound_hosts = ["http://self", "https://self.alt"]
 ```
+
+> It doesn't matter which you use - either 'allow' form enables both relative and `self.alt` URLs.

content/v3/http-trigger.md

@@ -300,8 +300,6 @@ class IncomingHandler(http.IncomingHandler):
 
 In Go, you register the handler as a callback in your program's `init` function.  Call `spinhttp.Handle`, passing your handler as the sole argument.  Your handler takes a `http.Request` record, from the standard `net/http` package, and a `ResponseWriter` to construct the response.
 
-> The do-nothing `main` function is required by TinyGo but is not used; the action happens in the `init` function and handler callback.
-
 ```go
 package main
 

content/v3/javascript-components.md

@@ -11,6 +11,7 @@ url = "https://github.com/spinframework/spin-docs/blob/main/content/spin/v3/java
 - [Building and Running the Template](#building-and-running-the-template)
 - [HTTP Components](#http-components)
 - [Sending Outbound HTTP Requests](#sending-outbound-http-requests)
+  - [Intra-Application Requests in JavaScript](#intra-application-requests-in-javascript)
 - [Storing Data in Redis From JS/TS Components](#storing-data-in-redis-from-jsts-components)
 - [Storing Data in the Spin Key-Value Store](#storing-data-in-the-spin-key-value-store)
 - [Storing Data in SQLite](#storing-data-in-sqlite)
@@ -155,7 +156,7 @@ addEventListener('fetch', async (event: FetchEvent) => {
 
 ## Sending Outbound HTTP Requests
 
-If allowed, Spin components can send outbound HTTP requests.
+If allowed, Spin components can send outbound HTTP requests using the `fetch` function.
 Let's see an example of a component that makes a request to [an API that returns random animal facts](https://random-data-api.fermyon.app/animals/json)
 
 ```javascript
@@ -238,6 +239,19 @@ This can be the basis for building components that communicate with external
 databases or storage accounts, or even more specialized components like HTTP
 proxies or URL shorteners.
 
+### Intra-Application Requests in JavaScript
+
+JavaScript's `fetch` function handles relative URLs in a way that doesn't work well with Spin's fine-grained outbound HTTP permissions.
+Therefore, when [making a request to another route within the same application](./http-outbound#intra-application-http-requests-by-route),
+you must use the special pseudo-host `self.alt` rather than a relative route.  For example:
+
+```javascript
+await fetch('/api');  // Avoid!
+await fetch('http://self.alt/api');  // Prefer!
+```
+
+You must [add `http://self` or `http://self.alt` to the component's `allowed_outbound_hosts`](./http-outbound#intra-application-http-requests-by-route).
+
 ---
 
 ## Storing Data in Redis From JS/TS Components

content/v3/key-value-store-tutorial.md

@@ -399,9 +399,6 @@ func init() {
 		}
 	})
 }
-
-func main() {}
-
 ```
 
 {{ blockEnd }}

content/v3/quickstart.md

@@ -628,7 +628,7 @@ component = "hello-go"
 source = "main.wasm"
 allowed_outbound_hosts = []
 [component.hello-go.build]
-command = "tinygo build -target=wasi -gc=leaking -no-debug -o main.wasm main.go"
+command = "tinygo build -target=wasip1 -gc=leaking -buildmode=c-shared -no-debug -o main.wasm ."
 ```
 
 This represents a simple Spin HTTP application (triggered by an HTTP request).  It has:
@@ -639,8 +639,8 @@ This represents a simple Spin HTTP application (triggered by an HTTP request).
 [Learn more about the manifest here.](./writing-apps)
 
 Now let's have a look at the code. Below is the complete source
-code for a Spin HTTP component written in Go. Notice where the work is done.  The
-`main` function is empty (and Spin never calls it).  Instead, the `init` function
+code for a Spin HTTP component written in Go. Notice where the work is done.  Because this is a component
+rather than an application, there is no `main` function.  Instead, the `init` function
 sets up a callback, and passes that callback to `spinhttp.Handle` to register it as
 the handler for HTTP requests.  You can learn more about this structure
 in the [Go language guide](go-components).
@@ -661,8 +661,6 @@ func init() {
                 fmt.Fprintln(w, "Hello Fermyon!")
         })
 }
-
-func main() {}
 ```
 
 {{ blockEnd }}
@@ -817,7 +815,7 @@ You can always run this command manually; `spin build` is a shortcut.
 
 ```bash
 $ spin build
-Executing the build command for component hello-go: tinygo build -target=wasi -gc=leaking -no-debug -o main.wasm main.go
+Executing the build command for component hello-go: tinygo build -target=wasip1 -gc=leaking -buildmode=c-shared -no-debug -o main.wasm .
 go: downloading github.com/fermyon/spin/sdk/go v0.10.0
 Finished building all Spin components
 ```
@@ -826,14 +824,14 @@ If the build fails, check:
 
 * Are you in the `hello_go` directory?
 * Did you successfully [install TinyGo](#install-the-tools)?
-* Are your versions of Go and TinyGo up to date?  The Spin SDK needs TinyGo 0.27 or above.
+* Are your versions of Go and TinyGo up to date? The Spin SDK needs TinyGo 0.35 or above and Go 1.22 or above.
 * Set Environment Variable `CGO_ENABLED=1`. (Since the Go SDK is built using CGO, it requires the CGO_ENABLED=1 environment variable to be set.)
 
 If you would like to know what build command Spin runs for a component, you can find it in the manifest, in the `component.(id).build` section:
 
 ```toml
 [component.hello-go.build]
-command = "tinygo build -target=wasi -gc=leaking -no-debug -o main.wasm main.go"
+command = "tinygo build -target=wasip1 -gc=leaking -buildmode=c-shared -no-debug -o main.wasm ."
 ```
 
 You can always run this command manually; `spin build` is a shortcut to save you having to remember it.

content/v3/rdbms-storage.md

@@ -201,8 +201,6 @@ func init() {
 		json.NewEncoder(w).Encode(pets)
 	})
 }
-
-func main() {}
 ```
 
 {{ blockEnd }}

content/v3/redis-trigger.md

@@ -137,8 +137,6 @@ func init() {
 		return nil
 	})
 }
-
-func main() {}
 ```
 
 {{ blockEnd }}

content/v3/sqlite-api-guide.md

@@ -233,8 +233,6 @@ func init() {
 		json.NewEncoder(w).Encode(todos)
 	})
 }
-
-func main() {}
 ```
 
 **General Notes**

content/v3/variables.md

@@ -242,8 +242,6 @@ func init() {
 		fmt.Fprintln(w, "Used an API")
 	})
 }
-
-func main() {}
 ```
 
 {{ blockEnd }}