Compute@Edge services
Compute@Edge is a computation platform capable of running custom binaries that you compile on your own systems and upload to Fastly. Security and portability is provided by compiling your code to WebAssembly.
IMPORTANT: Compute@Edge is generally available, but the status of individual languages and features may vary, and where it differs will be specified in the documentation for that feature. For more information, see our product and feature lifecycle descriptions.
Getting started
Create a Fastly account
To use Compute@Edge, you must create a Fastly account if you don't already have one.
Generate an API token
Compute@Edge services use packages built on your computer using the Fastly CLI. To authenticate the Fastly CLI, you must create an API token for your account. Follow the steps for creating an API token, make sure it has global
scope, and make a note of the token.
Download and install the Fastly CLI
The Fastly CLI is available for multiple operating systems.
- MacOS: Install from Homebrew:$ brew install fastly/tap/fastly
- Windows: Visit the GitHub repo to download the prebuilt binary for your architecture.
- Linux: Packages are available for many distributions, along with prebuilt binaries. Visit the GitHub repo to download the package for your distro.
Verify everything works by running fastly version. For example:
$ fastly versionFastly CLI version vX.Y.Z (abc0001)Built with go version go1.18 linux/amd64Viceroy version: viceroy X.Y.Z
The CLI will notify you if a new version is available. You can update it using the fastly update command.
Configure the Fastly CLI
The CLI interacts with Fastly via our API, authenticated using an API token. Configure the CLI to act on your behalf using the token you previously created, using one of the following options:
- (Recommended) Run fastly profile create and follow the interactive prompts. This will store your API token credential in a configuration file and remember it for subsequent commands.
- Include the token explicitly on each command you run using the
--token
or-t
flags. - Set a
FASTLY_API_TOKEN
environment variable.
For an overview of all available commands, run fastly with no arguments. Summarized help about any command or subcommand is available via the --help
flag (e.g., fastly service --help). For verbose help, use the help command (e.g., fastly help service).
Choose a language to use
Fastly supports client SDKs for several languages that can compile to Compute@Edge compatible Wasm packages. Choose a language below to view language-specific guidelines for our most popular SDKs.
HINT: This table lists features you can interact with from your Compute@Edge code. Many features supported by Fastly don't have interfaces exposed to your code, and therefore support cannot vary between SDKs. For a broader sense of what Fastly services can do, learn more about building on Fastly.
SDK version | 0.9.1 | 1.3.1 | 0.1.1 | |
---|---|---|---|---|
Core features | ||||
Geolocation | ✅ | ✅ | ✅ | |
Dynamic compression ℹ️ | ✅ | ✅ | ✅ | |
Auto decompression ℹ️ | ✅ | - | ✅ | |
Environment variables ℹ️ | ✅ | ✅ | ✅ | |
Cache override ℹ️ | ✅ | ✅ | ✅ | |
Real time logging ℹ️ | ✅ | ✅ | ✅ | |
Edge dictionaries ℹ️ | ✅ see note 1 | ✅ | ✅ | |
Fanout ℹ️ | ✅ | - | - | |
Websockets passthrough ℹ️ | ✅ | - | - | |
Pre-release features | ||||
Object stores | ✅ | ✅ | - | |
Config stores | ✅ | ✅ | - | |
Secret stores | ✅ | - | - | |
Dynamic backends | ✅ | ✅ | - | |
Purging see note 2 | ✅ | - | - | |
Backend health | ✅ | - | - | |
Use Rust » | Use JavaScript » | Use Go » |
- Edge dictionaries are exposed in the Rust SDK using the
ConfigStore
interface - Purging from edge code allows purge operations to be triggered when processing edge requests. Purging via our API is available regardless of which SDK is used.
We recommend the use of official Fastly SDKs (available for Rust, JavaScript, Go and AssemblyScript), but you can also create your own for a language of your choice, or use a community-created SDK. Learn more about custom SDKs.
Install local dependencies
To build your project, the Fastly CLI requires your local toolchain to be available and up to date. To install the toolchain for your chosen language, follow these instructions:
- Rust
- JavaScript
- Go
- AssemblyScript
Compiling Rust applications for Compute@Edge requires that you have rustup
installed, along with Rust's stable channel and the wasm32-wasi toolchain. Install Rust and its dependencies using rustup
so you can begin building Compute@Edge services:
If you don't have rustup
installed:
Download and install rustup
and the Rust stable
toolchain:
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
Install the wasm32-wasi
target for the stable
toolchain:
$ rustup target add wasm32-wasi --toolchain stable
If you do have rustup
installed:
Install Rust:
$ rustup toolchain add stable
Install the wasm32-wasi
target for the stable
toolchain:
$ rustup target add wasm32-wasi --toolchain stable
Create a new Compute@Edge project
Use fastly compute init to scaffold a new Fastly Compute@Edge project. The CLI will generate source code for your project in the current working directory.
To get you started, we have made a library of Compute@Edge starter kit applications that are ready to compile and run on your service, so you can start from a working example that is as close as possible to the solution you are trying to achieve.
Right now, we offer the following starter kits:
- Authenticate at edge with OAuth
- Default starter for AssemblyScript
- Default starter for Go
- Default starter for JavaScript
- Empty starter for JavaScript
- Default starter kit for Expressly
- OpenAPI Validation (JS)
- Queuing / Waiting room (JS)
- Beacon termination
- Connect to Google Bigquery for Rust
- Default starter for Rust
- Empty starter for Rust
- Fanout starter for Rust
- Fanout forwarding starter for Rust
- Static content
- WebSockets starter for Rust
- Fastly Compute@Edge Starter kit for Fauna
- Optimizely Full Stack
- Integrate Storj using Rust
When you initialize a Compute@Edge project with fastly compute init, you'll be prompted to choose one of these starter kits.
$ mkdir example && cd example$ fastly compute init
The system will display a series of prompts to guide you through the process of setting up your new project.
Creating a new Compute@Edge project.
Press ^C at any time to quit.
Name: [example]Description: hello world rust projectAuthor: Service AuthorLanguage:[1] Rust (limited availability)[2] JavaScript (limited availability)[3] Go (beta)[4] AssemblyScript (beta)[5] Other ('bring your own' Wasm binary)Choose option: [1]Starter kit:[1] Default starter for Rust A basic starter kit that demonstrates routing, simple synthetic responses and overriding caching rules. https://github.com/fastly/compute-starter-kit-rust-default[2] Beacon termination Capture beacon data from the browser, divert beacon request payloads to a log endpoint, and avoid putting load on your own infrastructure. https://github.com/fastly/compute-starter-kit-rust-beacon-termination[3] Static content Apply performance, security and usability upgrades to static bucket services such as Google Cloud Storage or AWS S3. https://github.com/fastly/compute-starter-kit-rust-static-contentChoose option or paste git URL: [1]
At the prompts, provide details about the service you're creating:
- Name: Enter a name for your service. By default, the CLI will use the name of the current directory.
- Description: Enter a short description for your service, or leave it blank.
- Author: Enter an email address as the author of the service package if desired.
- Language: Select the toolchain you wish to use to build your service.
- Starter kit: Choose from the available starter kits or press enter to accept the default. You may also enter the URL of a GitHub repo to use a template not in the list.
The CLI will set up a local development environment and a fastly.toml package manifest based on your selections, and provide some useful links and commands for working with your project:
✓ Initializing...✓ Fetching package template...✓ Updating package manifest...✓ Initializing package...
Initialized package example to: /home/me/example
To publish the package (build and deploy), run: fastly compute publish
To learn about deploying Compute@Edge projects using third-party orchestration tools, visit: https://developer.fastly.com/learning/integrations/orchestration/
SUCCESS: Initialized package example
NOTE: Prior to CLI version 0.28.0 the fastly compute init process prompted for the domain and backend, and created a live Fastly service in preparation for your first deployment. This has now been moved to the fastly compute deploy process.
By default fastly compute init will create your project in the current directory. To specify a different one, use the --directory flag, but remember to change to the target directory before executing any other commands that you want to run in the context of the new project.
Compile the project to a Wasm binary
HINT: You already have a complete, functional Compute@Edge project at this point. If you want to dive in to the code, check out the language-specific guides on Rust, JavaScript, Go or AssemblyScript, but you don't need to make any code changes before you deploy for the first time.
To run the Compute@Edge project on Fastly, it needs to be compiled into a WebAssembly module that can be packaged for Fastly use. The CLI internally runs the appropriate compiler for the language you're using, and generates the necessary WebAssembly binary.
$ fastly compute build
A successful build looks like this:
$ fastly compute build✓ Initializing...✓ Verifying package manifest...✓ Verifying local <selected language> toolchain...✓ Building package using <selected language> toolchain...✓ Creating package archive...
SUCCESS: Built <selected language> package <name> (pkg/<name>.tar.gz)
Deploy the project to a new Fastly service
To deploy the project to Fastly, run fastly compute deploy.
HINT: You'll start a Compute@Edge free trial when you deploy a Compute@Edge project to a Fastly service. While on a free trial, Compute@Edge services in your account are subject to lower limits and cannot be used for production traffic. When you're ready to use your Compute@Edge service for production traffic, contact our sales team or your Fastly account contact.
If you already have a Fastly service you want to deploy the package to, you can add the service ID into the service_id
property in fastly.toml before running the deploy command, but if not, we'll create a service for you automatically.
At the prompts, provide details about the service you're creating:
- Domain: Press enter to accept the automatically generated domain name (we'll take care of the TLS and DNS and give you a working domain immediately) or enter the name of the domain you'd like to associate with your service. You can also accept the default now and add more domains to the service later if you prefer.
- Backend: If you want to configure an origin server for your service, enter a valid hostname, or an IPv4 or IPv6 address. Alternatively leave the prompt blank to create a service with no origin server. Such services cannot forward requests to your servers, but they can respond to client requests with a response composed within your Compute@Edge package.
NOTE: Find out more about routing traffic to Fastly.
$ fastly compute deploy
There is no Fastly service associated with this package. To connect to an existing serviceadd the Service ID to the fastly.toml file, otherwise follow the prompts to create aservice now.
Press ^C at any time to quit.
Create new service: [y/N] y
✓ Initializing...✓ Creating service...
Domain: [random-funky-words.edgecompute.app]
Backend (hostname or IP address, or leave blank to stop adding backends):
✓ Initializing...✓ Creating domain 'random-funky-words.edgecompute.app'...✓ Uploading package...✓ Activating version...
Manage this service at: https://manage.fastly.com/configure/services/PS1Z4isxPaoZGVKVdv0eY
View this service at: https://random-funky-words.edgecompute.app
SUCCESS: Deployed package (service PS1Z4isxPaoZGVKVdv0eY, version 1)
The output includes a link to manage your service in the Fastly web interface. You can use this link to perform more complex configuration of the service, such as adding or removing domains, changing origin server settings, and setting up logging endpoints.
HINT: Many customers like using Terraform to manage Fastly service configurations. If you want to do this, consider using Terraform to provision the service, and then add the service_id
to the fastly.toml file.
After the command completes, it may take up to an additional 20 seconds before the package begins handling requests, and if you're replacing a previous version of the package, the earlier version may continue to handle requests for up to a minute.
Test and celebrate
Open a browser or use a command line HTTP client such as cURL to issue a request to the domain that you assigned to the service.
$ curl -si "https://random-funky-words.edgecompute.app/"HTTP/2 200content-type: text/html; charset=utf-8date: Tue, 09 Nov 2021 17:25:05 GMTcontent-length: 666
<!DOCTYPE html><html lang="en">...</html>
Or if you prefer, test it in a web browser:
Next steps
Now that you have a working project deployed, you have the basic building blocks in place to be successful with Compute@Edge.
If you would like to learn more about how Compute@Edge integrates with your preferred language, read our getting started guides for Rust, JavaScript, Go or AssemblyScript.
If you are already familiar with VCL and want to migrate an existing VCL configuration to Compute@Edge, try the VCL to Compute@Edge migration guide, which shows examples of the most common use cases in VCL and how to implement the same functionality using Compute@Edge's supported languages.
Or maybe you have an idea in mind and you want to experiment with examples? Try cloning a starter kit, copy and pasting code from some examples, or following a tutorial.
Limitations and constraints
Compute@Edge services allow connections to backends on ports 80 and 443, and accept client connections on port 443 only. This is different from VCL services, which support client connections on port 80.
HINT: If your Compute@Edge service receives a request on port 80, Fastly automatically returns a 308
("Permanent Redirect") response status with the Location
header indicating the HTTPS version of the same URL in a Location
header.
The following default limits apply to Compute@Edge services. If you need to exceed one of these limits, please speak to your Fastly contact or reach out to support@fastly.com:
Item | Limit | Scope |
---|---|---|
Maximum compiled package size | 50MB | per service |
Maximum CPU time available to a single request instance | 50ms | per execution |
Maximum runtime for a single request instance | 2 min (60s for free trials) | per execution |
Maximum memory consumption | 1M bytes stack, 128MB heap | per execution |
Maximum number of dictionary lookups | 16 | per execution |
Maximum number of backend requests | 32 (10 for free trials) | per execution |
An 'execution' refers to a single instance of Compute@Edge being executed, normally in response to a client HTTP request. Separate limits also apply to the use of log tailing with Compute@Edge services.