Migrating an Application from Spin 2.x to Spin 3.x
Most applications will not require changes. The following changes may affect application authors:
- The HTTP trigger application-level
base
option has been removed. To simulate the effect ofbase
, use a common prefix for your routes. - Spin now infers the
authority
property of an incoming HTTP request from either the request URL or the HTTP Host header. (If the request includes both, then they must agree.) This means that when a client makes the request through a DNS name, theauthority
will be that DNS name, rather than the Spin server’s listener address. If your components use theauthority
property then you should carefully re-test that they work correctly after this change. - Spin now adds an HTTP Host header on
self
requests (those made using a path only). The value of the header is the listener address of the Spin HTTP server. Consequently, the component receiving theself
request will always see the URLauthority
as that of the Spin HTTP server. If your application uses self-requests, and the receiving components use theauthority
property, then you should carefully re-test that they work correctly after this change. - The on-disk format for Serverless AI LLMs has changed. You will need to re-download local models and re-organise them in accordance with the new format. See the Serverless AI API guide for details. (No application code changes are required.)
- The environment provider for application variables is now overridden
by application variable providers configured in the runtime config file.
If you relied on environment variables taking precedence over other sources, you will need to stop setting
--runtime-config-file
or tweak your workflow. - Some modules produced by languages with older WASI support may no longer run. This specifically affects WAGI applications compiled with a WASI-SDK version 18 or earlier. See https://github.com/fermyon/spin/issues/2552 for details of the issue and for possible workarounds.
The following change will not affect most application authors, but may affect you if you work directly with the low-level WASI interfaces:
- If an outbound HTTP request is denied, the
HTTP-request-denied
error previously occurred immediately on the initialwasi:http/outgoing-handler#handle
call. It now occurs when callingget
on thefuture-incoming-response
returned from thehandle
call.
If you’re affected by these or other changes and you’re looking for help, please reach out on the Fermyon Discord for support.