Overview

Scale Functions currently support using Golang as both a Guest and the Host language.

This means that you can write your Functions in Golang (Guest Support) and you can run Functions written in any supported language inside a Golang application (Host Support).

Guest Support

A Scale Function written in Golang often looks something like this:

//go:build tinygo || js || wasm
package scale
 
import (
   signature "github.com/loopholelabs/scale-signature-http"
)
 
func Scale(ctx *signature.Context) (*signature.Context, error) {
   ctx.Response().SetBody("Hello, World!")
   return ctx.Next()
}

The above example is a simple HTTP Function that responds with "Hello, World!" to any request.

By default, the generated function will be configured to use the HTTP Signature, which provides an interface for handling HTTP requests and responses. To learn more about the HTTP Signature and the interfaces it provides, you can check out the HTTP Signature Reference. Learn more about Signatures in the Signatures Overview.

Compiling these Functions requires the appropriate toolchain to be installed on your machine.

Installing the Golang Toolchain

To use Golang as the Guest Language, you'll need to install the following:

• The Go toolchain
• The TinyGo compiler

The best way to install Go is to follow the official instructions for your operating system and platform at https://go.dev/doc/install.

You can verify that Go was installed correctly by running the following command:

go version

The best way to install TinyGo is to follow the official instructions for your operating system and platform at https://tinygo.org/getting-started/install/.

You can verify that TinyGo was installed correctly by running the following command:

tinygo version

Host Support

To use a compiled Scale Function (written in any supported language) inside a Golang application, there are 3 steps:

1. Import the Scale Function(s) into the Golang application by embedding them
2. Create a new Scale Runtime and pass in the Scale Function(s)
3. Call the Run method on the Scale Runtime with your request

Importing Scale Functions

Scale Functions can be imported into a Golang application by embedding them Directly.

Embedding Scale Functions

Scale Functions can be embedded into a Golang application by using the //go:embed directive, after it has been exported using the scale fn export command (see Exporting Scale Functions).

import (
	"embed"
	"github.com/loopholelabs/scale/scalefunc"
)
 
//go:embed <path to exported function>
var embeddedFunction []byte
 
func main() {
    // ...
    sf := new(ScaleFunc)
	_ = sf.Decode(embeddedFunction)
    // ...
}

Creating a Scale Runtime

Once you've imported your Scale Function(s) into your Golang application, you can create a new instance of the Scale Runtime and pass in the Scale Function(s).

import (
	"context"
	scale "github.com/loopholelabs/scale"
)
 
func main() {
    // ...
	ctx := context.Background()
    r := scale.New(ctx, sf) // Or scale.New(ctx, sf1, sf2, sf3, ...)
    // ...
}

Running a Scale Function

Once you've created the Scale Runtime, you can call the Instance method on it to get a new runtime instance. The Context method of the Instance can then be used to set the request body, and the Run method can be used to run the Scale Function (or Functions).

import (
    "context"
)
 
func main() {
    // ...
    i, _ := r.Instance()
    i.Context().Request.Body = []byte("Hello, World!")
 
    ctx := context.Background()
    _ = i.Run(ctx)
    // ...
}

It's important to note that an Instance can be reused multiple times, but it's not thread-safe. If you need to run multiple instances of a Scale Function concurrently, you'll need to create a new Instance for each one.

Instances are heavily optimized and will recycle themselves automatically when they're no longer in use. This means that creating instances are very cheap and you can create as many as you need as often as you need.

import (
    "context"
    scale "github.com/loopholelabs/scale"
)
 
func main() {
    // ...
    r := scale.New(ctx, sf)
    // ...
    ctx := context.Background()
    _ = i.Run(ctx)
    // ...
    r.Clear
}

Putting it all Together

Here's a complete example of a Golang application that imports a Scale Function, creates a new Scale Runtime, and runs it.

package main
 
import (
    "context"
    "embed"
    "fmt"
    scale "github.com/loopholelabs/scale"
)
 
//go:embed hello-latest.scale
var embeddedFunction []byte
 
func main() {
    sf := new(scale.ScaleFunc)
    _ = sf.Decode(embeddedFunction)
 
    ctx := context.Background()
    r := scale.New(ctx, sf)
 
    i, _ := r.Instance()
    i.Context().Request.Body = []byte("Hello, World!")
 
    _ = i.Run(ctx)
 
    fmt.Println(string(i.Context().Response.Body))
}

What's Next?

Now that you've learned how to use Scale Functions inside your Golang application, you should check out our pre-made adapters for popular Golang frameworks and libraries, such as net/http and FastHTTP.