Quick Start

In this section we’ll be going over how you can quickly get started with Scale to create, run and even publish your own function.

We’ll be building a simple Hello World function using the HTTP Signature that will return a simple greeting.

Install the Scale CLI

The Scale CLI is the primary tool for interacting with Scale Functions and the Scale Registry. It can be easily installed using the following command:

curl -fsSL https://dl.scale.sh | sh

curl -fsSL https://dl.scale.sh | INSTALL=./ sh

To verify that the CLI was installed correctly, check the scale cli version by running the following command:

scale version

For alternative installation methods or to build the CLI from source, please see the CLI Installation Guide.

Install the Toolchain for your Guest Language

Scale Functions currently support using Golang, TypeScript/JavaScript, and Rust as the Guest Languages, but compiling them requires the appropriate toolchain to be installed on your machine.

If you already have the toolchain for your Guest Language installed, you can skip this step. Otherwise, you can follow the guides for your Guest Language below to install the toolchain.

go version

tinygo version

Create a New Function

Once you have the Scale CLI and the toolchain for your Guest Language installed, you can create a new function by running the following command, passing a <name>:<tag> pair to the new command:

scale fn new hello:1.0

This will create a new scale function in the current directory. You can also specify a different directory by passing the --directory or -d flag:

scale fn new hello:1.0 -d /path/to/directory

scale fn new hello:1.0 -l rust

The following files will be created in the directory depending on the language you chose:

  version  = "v1alpha"
  name     = "hello"
  tag      = "1.0"
  language = "go"
 
  signature {
    organization = "local"
    name         = "hello-signature"
    tag          = "1.0"
  }
 
  stateless   = false
  function    = "scale"
  initialize  = ""
  description = ""

//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()
}

module scale

go 1.18

require github.com/loopholelabs/scale-signature v0.2.9
require github.com/loopholelabs/scale-signature-http v0.3.4

You'll notice that at the end of the Scale Function we call the Next() function. This is because Scale Functions can be chained together to form a pipeline. The Next() function is used to pass the context to the next function in the chain and can be conditionally called based on the logic in your function.

This allows for powerful composability that's completely language agnostic. For example, you can use a rust function to validate the request, a golang function to process the request, and a third rust function to generate the response!

If you call the Next() field and there is no next function in the chain, the function is a no-op and the context is returned.

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.

Build the Function

Once you've created a new function, you can build it by running the following command:

scale function build

This will build the function and save it to the Cache Directory (which defaults to ~/.config/scale/functions on Linux and macOS). You can also specify a different directory by passing the --cache-directory flag:

scale function build --cache-directory /path/to/directory

To list all of the functions that are currently in the Cache Directory, you can run the following command:

scale function list

  NAME (1)            TAG      ORG           LANGUAGE   SIGNATURE     HASH                                                               VERSION
 ------------------- -------- ------------- ---------- ------------- ------------------------------------------------------------------ ---------
  hello              1.0     local         rust       [email protected]   8dad03b701cd124b55ff5caf7a36a9af5d19759fc73a9e8299bea4816f929777   v1alpha

Run the Function

Once you've built the function, you can run it by running the following command:

scale fn run local/hello:1.0

This will start a local HTTP server on port 8080 and will run the function whenever you make a request to it. You can also specify a different port by passing the --listen or -l flag:

scale fn run local/hello:1.0 -l :3000

Push the Function

Now that you've built and tested your function, you can push it to the Scale Registry. Once pushed, the function can be pulled and used in your existing Typescript or Golang services, or even by other users for their own applications.

To use the Scale Registry, you'll first have to authenticate with the Scale API. This process is the same for both new and existing users.

To authenticate with the Scale API, you can run the following command:

scale auth login

This will open a browser window and prompt you to log in to your Scale account. Once you've logged in, you can close the browser window and return to the terminal. You should now be able to push your function to the Scale Registry.

To check that you're authenticated, you can run the following command:

scale auth status

  MEMBER ORGS   OWNED ORGS      EMAIL                         ORG
 ------------- --------------- ----------------------------- -------------
  []            [shivanshvij]   [email protected]   shivanshvij

Once you've authenticated with the Scale API, you can push your function to the Scale Registry by running the following command:

scale function push hello:1.0

This will push the function to the Scale Registry and make it available for use in your existing services.

Pulling a Function

Once you've pushed a function to the Scale Registry, you can pull it and use it in your existing services. To pull a function, you can run the following command:

scale function pull <your organization>/hello:1.0

This will pull the function from the Scale Registry and save it to the Cache Directory (which defaults to ~/.config/scale/functions on Linux and macOS). You can also specify a different directory by passing the --cache-directory flag:

scale function pull <your organization>/hello:1.0 --cache-directory /path/to/directory

Next Steps

Now that you've created and pushed your first function, you can check out the Importing Scale Functions guide for Golang and Typescript/Javascript to learn how to use your function inside your existing services (and to chain them alongside native functions).

You can also check out our Adapter Guides to learn how to integrate your functions with popular frameworks such as Next.js.