Docs

Terrarium is a multi-language, browser-based editor and deployment platform where you can experiment with the technology that will power Fastly at the edge. This project pushes edge computing beyond the limitations of serverless implementations, and removes the need for specific languages, APIs, or add-ons that can impede your innovation or cause vendor lock-in.

About

With Terrarium, you can write your own code to create functions and applications, or try one of our examples and deploy it quickly. Terrarium uses our lightweight isolating sandbox, built with WebAssembly. It isolates each individual request, ensuring users’ privacy and mitigating the impact of crashes — so you can test it, break stuff, and test it again, ad infinitum.

Before you begin

This document explains the lifecycle of a Terrarium program, and how to use the Terrarium environment and the APIs for each language.

Program Lifecycle

Once compiled to WebAssembly, Terrarium programs are executed using Fastly's native WebAssembly engine.

Each Terrarium program is given a unique subdomain of fastly-terrarium.com, and remains active for 15 minutes after it's deployed. To run your program for another 15 minutes, just click "Build & Deploy" again. Each deployment will be given a fresh subdomain.

For each HTTP request to <terrarium-id>.fastly-terrarium.com, the Terrarium program's WebAssembly module is instantiated, and the user-defined entrypoint is called. From within the WebAssembly instance, the Terrarium host API may be used to get the contents of the HTTP request, and set the contents of the response. When the entrypoint function returns successfully, the web service sends the constructed response.

If the WebAssembly program encounters a fault, the HTTP request will return with an error status code, and some information about the cause of the fault.

Static Assets

The web service at <terrarium-id>.fastly-terrarium.com handles each incoming HTTP request by first checking the path against the contents of the /assets directory in the Terrarium project. For example, a request to /style.css will be served the static asset at /assets/style.css if it exists. Additionally, a health check endpoint at /__health will respond with "OK" while the program is active.

HTTP Client Requests

Terrarium programs can make HTTP requests to any other host on the internet. Responses can be retrieved synchronously or asynchronously. There is some rate limiting in place to stop you from turning Terrarium into a DDOS botnet.

DNS Requests

Terrarium programs can make DNS requests. The DNS-over-HTTPS example application demonstrates how this can be used to implement a web service.

Key-Value Store

Terrarium programs can access a Key-Value store. The contents of the store persist across all requests to the same Terrarium deployment.

Other features

Terrarium programs can request the current wall time with a resolution of 1 millisecond, and can ask for a random 64-bit integer with good cryptographic properties.

Supported Languages

Many programming languages have, or are developing, compiler backends to emit WebAssembly. Terrarium currently supports four languages: C, Rust, and TypeScript, and the textual representation of WebAssembly itself.

C

C language programs are compiled to WebAssembly using the Clang compiler. All files in a project with a .c extension will be compiled, and then linked into the same WebAssembly binary.

The host API for Terrarium is specified in http_hostcalls.h. We have published documentation of this interface, which includes the WebAssembly import functions for the Terrarium environment.

Each application must expose a function void run(void) as the user entrypoint. In order for Clang to expose this as a WebAssembly export function, the function definition must be preceded by __attribute__((visibility("default"))).

Rust

Rust language programs are compiled to WebAssembly using the wasm32-unknown-unknown target as a library crate that exports a run function.

The host API for Terrarium is specified in the crate http_guest, which is documented here. A number of third-party dependencies available to user programs are published as part of the documentation - see the "Crates" listing on the left-hand side of the documentation.

The http_guest crate wraps the low-level WebAssembly import functions into an idiomatic Rust API, and makes it easy to set up a user application by using the guest_app! or guest_app_kvs! macros.

TypeScript

TypeScript language programs are compiled to WebAssembly using the AssemblyScript compiler. AssemblyScript supports a strictly typed subset of TypeScript, and is still experimental - not every valid TypeScript program will compile correctly.

The host API for Terrarium is specified in the module http_guest, which is documented here. Adding additional TypeScript libraries as dependencies is not currently supported.

TypeScript programs must define an export function run(): void. To use the idiomatic TypeScript APIs, use the functions run_user or run_user_kvs to specify your application's entrypoint.

WebAssembly Text (.wat)

Terrarium supports programs written directly in WebAssembly's text format. The example WebAssembly application specifies all of the import functions available to a module. The module must export a run function that is used as the application entrypoint.