compute-sdk-go
module
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
- Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Open Source Insights
README¶
compute-sdk-go
Go SDK for buildingFastly Compute applications withGo (1.21+) andTinyGo (0.28.1+).
Quick Start
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.
Supported Toolchains
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.
Installation
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
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.
API Reference
The API reference documentation can be found onpkg.go.dev/github.com/fastly/compute-sdk-go.
Testing
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 testThis 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
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())Readthrough HTTP Cache Support
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 Recommended Packages
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:
JSON Parsing
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.
Changelog
The changelog can be foundhere.
Security
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.
License
Directories¶
| Path | Synopsis |
|---|---|
_examples | |
aclcommand | |
add-or-remove-cookiescommand | |
corecachecommand | |
device-detectioncommand | |
geodatacommand | |
hello-worldcommand | |
http-adaptercommand | |
kvstorecommand | |
limitscommand | |
logging-and-envcommand | |
middlewarescommand | |
multiple-goroutinescommand | |
parallel-requestscommand | |
print-requestcommand | |
proxy-requestcommand | |
proxy-request-framingcommand | |
reusable-sandboxcommand | |
secret-storecommand | |
set-cookiecommand | |
set-google-analyticscommand | |
shieldingcommand | |
simplecachecommand | |
stream-responsecommand | |
with-timeoutcommand | |
Package acl provides access to Fastly ACLs. | Package acl provides access to Fastly ACLs. |
cache | |
core Package core provides the Fastly Core Cache API. | Package core provides the Fastly Core Cache API. |
simple Package simple provides the Simple Cache API, a simplified interface to inserting and retrieving entries from Fastly's cache. | Package simple provides the Simple Cache API, a simplified interface to inserting and retrieving entries from Fastly's cache. |
Useful functions for interacting with the compute instance runtime. | Useful functions for interacting with the compute instance runtime. |
Package configstore provides a read-only interface to config stores. | Package configstore provides a read-only interface to config stores. |
Package device provides device dection based on the User-Agent header. | Package device provides device dection based on the User-Agent header. |
Package edgedict provides a read-only interface to edge dictionaries. | Package edgedict provides a read-only interface to edge dictionaries. |
end_to_end_tests | |
loopbackcommand | |
serve-manycommand | |
Package erl provides Edge Rate Limiting functionality. | Package erl provides Edge Rate Limiting functionality. |
Package fsthttp provides HTTP functionality for Fastly's Compute environment. | Package fsthttp provides HTTP functionality for Fastly's Compute environment. |
Package geo provides access to the geographic data for IP addresses. | Package geo provides access to the geographic data for IP addresses. |
integration_tests | |
httpcachecommand | |
internal | |
abi/fastly Package fastly provides access to the Fastly Compute hostcall ABI. | Package fastly provides access to the Fastly Compute hostcall ABI. |
abi/prim Package prim contains primitive types used in Wasm ABI functions. | Package prim contains primitive types used in Wasm ABI functions. |
abi/wasi Package wasi provides access to Wasi features independent of Fastly Compute. | Package wasi provides access to Wasi features independent of Fastly Compute. |
Package kvstore provides access to Fastly KV stores. | Package kvstore provides access to Fastly KV stores. |
Deprecated: Use the kvstore package instead. | Deprecated: Use the kvstore package instead. |
Package purge provides cache purging operations for Fastly Compute. | Package purge provides cache purging operations for Fastly Compute. |
Package rtlog provides an interface to real-time logging endpoints. | Package rtlog provides an interface to real-time logging endpoints. |
Package secretstore provides a read-only interface to Fastly Compute Secret Stores. | Package secretstore provides a read-only interface to Fastly Compute Secret Stores. |
Package x contains temporary and/or experimental sub-packages. | Package x contains temporary and/or experimental sub-packages. |
exp/handoff Deprecated: Use fsthttp.Request.Handoff* methods instead. | Deprecated: Use fsthttp.Request.Handoff* methods instead. |
fstctx Package fstctx provides alternatives to context.WithTimeout and context.WithDeadline. | Package fstctx provides alternatives to context.WithTimeout and context.WithDeadline. |