Repository files navigation

Go SDK for buildingFastly Compute applications withGo (1.23+) andTinyGo (0.33.0+).

The Fastly Developer Hub has a greatQuick Start guide for Go.

Alternatively, you can take a look at theGo Starter Kit.

If you're using TinyGo, you'll also want to take a look at ourTinyGo Recommended Packages section, as this can help with the sharp edges of the SDK, like JSON support.

Compute builds on top of WebAssembly and theWebAssembly System Interface.

TinyGo supports WASI as a target, and Go does as of its 1.21 release.

Each toolchain has its own tradeoffs. Generally speaking, TinyGo produces smaller compiled artifacts and takes less RAM at runtime. Build times are generally longer, sometimes considerably. TinyGo does not support all of the Go standard library, and in particular support for thereflect package is incomplete. This means that some third-party packages may not work with TinyGo.

Runtime performance is mixed, with TinyGo faster on some applications and Go faster on others. If you have a performance-critical application, we recommend benchmarking both toolchains to see which works best for you.

To switch between TinyGo and Go, set thebuild command in the[scripts] section of yourfastly.toml as follows:

[scripts]build = "tinygo build -target=wasi -o bin/main.wasm ."

or

[scripts]build = "GOARCH=wasm GOOS=wasip1 go build -o bin/main.wasm ."

You might need to adjust the actual build command depending on your project.

If you're using Go, downloadthe latest Go release. For TinyGo, follow theTinyGo Quick install guide.

Then, you can installcompute-sdk-go in your project by running:

go get github.com/fastly/compute-sdk-go

Examples can be found in theexamples directory.

The Fastly Developer Hub has a collection ofcommon use cases in VCL ported to Go which also acts as a great set of introductory examples of using Go on Compute.

The API reference documentation can be found onpkg.go.dev/github.com/fastly/compute-sdk-go.

Tests that rely on a Compute runtime useViceroy, our local development tool.

TheMakefile installs viceroy in ./tools/ and uses this version to run tests.

Write your tests as ordinary Go tests. Viceroy provides the Compute APIs locally, although be aware that not all platform functionality is available. You can look at theintegration_tests directory for examples.

To run your tests:

make test

This target runs tests in both Go and TinyGo, andintegration_tests in both Go and TinyGo in Viceroy. See additional targets inMakefile for running subsets of these tests.

Thetargets/fastly-compute-wasi{,p1}.json files provide TinyGo targets to run Viceroy.

Logging can be done using a Fastly Compute Log Endpoint (example), or by using normal stdout like:

fmt.Printf("request received: %s\n", r.URL.String())

Customizing cache behaviour with the readthrough cache is an opt-in feature; enable it by adding-tags=fsthttp_guest_cache to the build line of yourfastly.toml.

[scripts]build = "tinygo build -target=wasip1 -tags=fsthttp_guest_cache -o bin/main.wasm ."

TinyGo is still a new project, which has yet to get a version1.0.0. Therefore, the project is incomplete, but in its current state can still handle a lot of tasks on Compute. However,some languages features of Go are still missing.

To help with your adoption ofcompute-sdk-go, here are some recommended packages to help with some of the current missing language features:

TinyGo'sreflect support (which is needed byencoding/json among other things) is still new. While most use cases should work, for performance or other compatibility reasons you might need to consider a third-party JSON package if the standard library doesn't meet your needs.

• valyala/fastjson
• mailru/easyjson
• buger/jsonparser

The changelog can be foundhere.

If you find any security issues, see theFastly Security Reporting Page or send an email to:security@fastly.com

Note that communications related to security issues in Fastly-maintained OSS as described here are distinct fromFastly security advisories.

Apache-2.0 WITH LLVM-exception