diff --git a/content/spin/v3/http-outbound.md b/content/spin/v3/http-outbound.md index b0490c489..f69fcd0ec 100644 --- a/content/spin/v3/http-outbound.md +++ b/content/spin/v3/http-outbound.md @@ -7,6 +7,7 @@ url = "https://github.com/fermyon/developer/blob/main/content/spin/v3/http-outbo --- - [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. diff --git a/content/spin/v3/javascript-components.md b/content/spin/v3/javascript-components.md index a48e95b6f..b624e330d 100644 --- a/content/spin/v3/javascript-components.md +++ b/content/spin/v3/javascript-components.md @@ -11,6 +11,7 @@ url = "https://github.com/fermyon/developer/blob/main/content/spin/v3/javascript - [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) - [Routing in a Component](#routing-in-a-component) - [Storing Data in the Spin Key-Value Store](#storing-data-in-the-spin-key-value-store) @@ -155,7 +156,7 @@ The important things to note in the implementation above: ## 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 @@ -233,6 +234,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