1. Home
  2. Developer guides
  3. Compute services

Go on the Compute platform

The guidance on this page was tested with an older version (1.0.0) of the Go SDK. It may still work with the latest version (1.3.0), but the change log may help if you encounter any issues.

The Go tooling for the Compute platform builds Go application code into Wasm using either the standard Go compiler or TinyGo. Go is a reliable and efficient language for building performant applications. It is a great SDK to get started with on the Compute platform if you're familiar with traditional server-side languages.

Quick access

SDK reference

Documentation for the compute-sdk-go Go module.

Code examples

Filter all our code examples for those with implementations in Go.

Starter kit

Start a Go project from a simple but complete example application.

Project layout

If you don't yet have a working toolchain and Compute service set up, start by getting set up.

At the end of the initialization process, the current working directory will contain a file tree resembling the following:

.
├── .gitignore
├── README.md
├── fastly.toml
├── go.mod
├── go.sum
└── main.go

The most important file to work on is main.go, which contains the logic you'll run on incoming requests. If you initialized your project from the default starter template, the contents of this file will match the one in the template's repo. The other files include:

  • Module metadata: go.mod and go.sum describe the dependencies of your module, managed using go get.
  • Fastly metadata: The fastly.toml file contains metadata required by Fastly to deploy your package to a Fastly service. It is generated by the fastly compute init command. Learn more about fastly.toml.

Choosing a compiler

The scripts.build property in fastly.toml tells the Fastly CLI how to build your project. Our starter kits ship with this property set assuming you want to use the standard Go compiler, however, you can also choose to use TinyGo if you prefer. TinyGo produces smaller, faster binaries, but its support for Reflection and other Go features is incomplete, so it doesn't support all standard Go libraries yet.

Fastly supported TinyGo before standard Go, so if your fastly.toml file does not specify a scripts.build, the Fastly CLI will use TinyGo by default and emit a warning.

If using the standard Go compiler, you will likely also want to set environment variables GOARCH=wasm and GOOS=wasip1, which can be done in fastly.toml using the env_vars property of scripts:

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

The following are the typical build commands for each compiler:

  • Standard Go: go build -o bin/main.wasm .
  • TinyGo: tinygo build -target=wasi -o bin/main.wasm ./

Main interface

The most common way to start a Compute program is to define a main() function that calls the fsthttp.ServeFunc function using the following type signature:

9func main() {
10    fsthttp.ServeFunc(func(ctx context.Context, w fsthttp.ResponseWriter, r *fsthttp.Request) {
11      // ...
12    })
13}

The fastly/compute-sdk-go module provides the core fsthttp.Request and fsthttp.ResponseWriter types referenced here. The program will be invoked for each request that Fastly receives for a domain attached to your service, and it must return a response that can be served to the client.

Communicating with backend servers and the Fastly cache

A fsthttp.Request can be forwarded to any backend defined on your service. If you specify a backend hostname as part of completing the fastly compute deploy wizard, it will be named the same as the hostname or IP address, but with . replaced with _ (e.g., 151_101_129_57). It's a good idea to define backend names as constants:

const BackendName = "my_backend_name"

And then reference them when you want to forward a request to a backend:

11const BackendName = "my_backend_name"
15        resp, err := r.Send(ctx, BackendName)
16        if err != nil {
17            w.WriteHeader(fsthttp.StatusBadGateway)
18            fmt.Fprintln(w, err.Error())
19            return
20        }
21

22        w.Header().Reset(resp.Header)
23        w.WriteHeader(resp.StatusCode)
24        io.Copy(w, resp.Body)

Requests forwarded to a backend will typically transit the Fastly cache, and the response may come from cache. For more precise or explicit control over the Fastly edge cache see Caching content with Fastly.

The Go SDK supports dynamic backends created at runtime using RegisterDynamicBackend.

Composing requests and responses

In addition to the request passed into fsthttp.ServeFunc and responses returned from fsthttp.Request.Send, requests and responses can also be constructed. This is useful if you want to make an arbitrary API call that is not derived from the client request, or if you want to make a response to the client without making any backend fetch at all.

The fsthttp.NewRequest constructor can be used to customize the request:

17        // A different URL to the incoming request.
18        url := "https://httpbin.org/headers"
19

20        req, err := fsthttp.NewRequest("GET", url, nil)
21        if err != nil {
22            log.Printf("%s: create request: %v", url, err)
23            return
24        }
25

26        req.Header.Add("foo", "bar")
27

28        resp, err := req.Send(ctx, BackendName)

The fsthttp.Response struct can be used to customize the response:

13        h := fsthttp.NewHeader()
14        h.Add("foo", "bar")
15

16        resp := fsthttp.Response{
17            Header:     h,
18            StatusCode: fsthttp.StatusOK,
19            Body:       io.NopCloser(strings.NewReader("Hello, world!")),
20        }

Parsing and transforming responses

Requests and responses in the Compute platform are streams, which allows large payloads to move through your service without buffering or running out of memory. Conversely, running methods such as io.ReadAll on a fsthttp.Response.Body will force the stream to be consumed entirely into memory. This can be appropriate where a response is known to be small or needs to be complete to be parsable.

This example will read a backend response into memory, replace every occurrence of "cat" with "dog" in the body, and then create a new body with the transformed bytes:

        // Consume all response body data into memory.
        bs, err := io.ReadAll(resp.Body)
        if err != nil {
            w.WriteHeader(fsthttp.StatusBadGateway)
            fmt.Fprintln(w, err.Error())
            return
        }


        // Replace all references to "cat" with "dog".
        bs = bytes.ReplaceAll(bs, []byte("cat"), []byte("dog"))


        // Reassign the updated body content
        resp.Body = io.NopCloser(bytes.NewReader(bs))

Compression

Fastly can compress and decompress content automatically, and it is often easier to use these features than to try to perform compression or decompression within your Go code. Learn more about compression with Fastly.

Using edge data

Fastly allows you to configure various forms of data stores to your services, both for dynamic configuration and for storing data at the edge. The Go SDK exposes the configstore, kvstore and secretstore packages to allow access to these APIs.

All edge data resources are account-level, service-linked resources, allowing a single store to be accessed from multiple Fastly services.

Logging

The rtlog package provides a standardized interface for sending logs to Fastly real-time logging, which can be attached to many third party logging providers. Before adding logging code to your Compute program, set up your log endpoint using the CLI, API, or web interface. Log endpoints are referenced in your code by name:

    "github.com/fastly/compute-sdk-go/rtlog"
        fmt.Fprintln(os.Stdout, "os.Stdout can be streamed via `fastly logs tail`")
        fmt.Fprintln(os.Stderr, "os.Stderr can be streamed via `fastly logs tail`")


        endpoint := rtlog.Open("my-logging-endpoint")
        fmt.Fprintln(endpoint, "Real-time logging is available via `package rtlog`")


        mw := io.MultiWriter(os.Stdout, endpoint, w)
        fmt.Fprintln(mw, "Mix-and-match destinations with helpers like io.MultiWriter")


        fmt.Fprintln(mw, "Several environment variables are defined by default...")
        for _, key := range []string{
            "FASTLY_CACHE_GENERATION",
            "FASTLY_CUSTOMER_ID",
            "FASTLY_HOSTNAME",
            "FASTLY_POP",
            "FASTLY_REGION",
            "FASTLY_SERVICE_ID",
            "FASTLY_SERVICE_VERSION",
            "FASTLY_TRACE_ID",
        } {
            fmt.Fprintf(mw, "%s=%s\n", key, os.Getenv(key))
        }


        prefix := fmt.Sprintf("%s | %s | ", os.Getenv("FASTLY_SERVICE_VERSION"), r.RemoteAddr)
        logger := log.New(os.Stdout, prefix, log.LstdFlags|log.LUTC)
        logger.Printf("It can be useful to create a logger with request-specific metadata built in")

Using dependencies

Any Go packages that can be compiled to WebAssembly by your chosen compiler (Standard Go or TinyGo) can be imported in a Compute Go project.

Our Fiddle tool allows the use of a subset of packages that we have tested and confirmed will work with the Compute platform. These include the packages most commonly used in Fastly projects and some that can fill the gaps where language features are missing:

This is a tiny fraction of the modules which will work on the Compute platform, but these are the most commonly useful modules when building applications.

Testing and debugging

Logging is the main mechanism to debug Compute programs. Log output from live services can be monitored via live log tailing. The local test server and Fastly Fiddle display all log output automatically. See Testing & debugging for more information about choosing an environment in which to test your program.

Most common logging requirements involve HTTP requests and responses. It's important to do this in a way that doesn't affect the main program logic, since consuming a response body can only be done once. The section Parsing and transforming responses demonstrates how you can read the response body, transform the content, then reassign the updated content so it may be read again using io.NopCloser before being written to the client.

Unit testing

You may choose to write unit tests for small, independent pieces of your Go code intended for the Compute platform. However, Compute programs heavily depend on and interact with Fastly features and your own systems.

You can use go test -tags nofastlyhostcalls or tinygo test -tags nofastlyhostcalls to run unit tests for code that imports the fastly/compute-sdk-go package, as long as they don't do any I/O using those modules. Integration tests that do I/O can be run inside a local test server using the Fastly CLI running fastly compute serve.

Functions should ideally have a signature that makes it easy to test. Avoid accepting concrete Fastly types in favour of more primitive types or use an interface. This allows the test environment to easily define a mock implementation.

Optimizations

If using TinyGo, the compiler provides various build options that can help optimize your compiled Wasm binary. These options are set on the tinygo build command using flags, for example:

OptionResultTrade-off
-no-debugReduced size of Wasm binaryNo line numbers will be present in panic tracebacks
-opt=2Improved runtime performanceSlightly larger Wasm binary, and less informative tracebacks
-gc=leakingImproved runtime performanceNo automated garbage collection

The standard Go compiler has no optimization flags that are relevant to most Fastly projects.

Fastly
© Fastly 2024