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:The CLI attempts to install itself to
/usr/local/bin
by default, but you can also specify a different directory by setting the INSTALL
environment variable like so: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.Installing the Golang Toolchain
To use Golang as the Guest Language, you'll need to install the following: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:The minimum supported version of Go for use with Scale Functions is
1.18
.The minimum supported version of TinyGo for use with Scale Functions is
0.27.0
.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:
--directory
or -d
flag:
By default, the CLI will create a new function using Golang as the Guest Language. If you want to use Rust instead,
you can pass the
--language
or -l
flag:scalefile
is the main configuration file for the function. It contains all of the metadata and configuration required
to build and run the function. The scale.go
file contains the actual implementation of the function, and
the go.mod
file is primarily used to provide Intellisense
and Auto-Completion support in your IDE.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.
When adding new dependencies to your function, you’ll need to add references to them in the
scalefile
to make sure
your function can be built properly.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.
The concept of a
Signature
is central to how Scale Functions provide cross-language type safety and it’s documented
in more detail in the Signatures section of the documentation.Build the Function
Once you’ve created a new function, you can build it by running the following command: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:
The
Cache Directory
is where the Scale CLI stores all of the built functions. This is where the CLI will look for
functions when you run commands like scale fn run
or scale fn push
.Cache Directory
, you can run the following command:
Run the Function
Once you’ve built the function, you can run it by running the following command: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:
The
scale fn run
command is designed for use with the HTTP Signature. It can be used for both
local development and production deployments and makes it easy to test your function without having to deploy it.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.Using the Scale Registry is completely free during our beta period. To learn more about our future plans for the Scale Registry,
please join the
#scale
channel on our Discord.If you are a new user you can still follow along with this guide. Your account will be created automatically when
you first sign in.
It’s also possible to authenticate with the Scale API using an API Key. To learn more about API Keys, you can check
out the API Keys section of the documentation.
The Scale Registry is currently in beta and may be subject to changes in the future. To learn more about the
Scale Registry, you can check out the Registry section of the documentation or join the
#scale
channel in our Discord.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:When you pushed the function to the Scale Registry, it was pushed to a specific organization.
You can find the name of the organization by running the
scale auth status
command.If you pushed the function using the --public
flag, you can pull it without being authenticated with the Scale API.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:
The
scale pull
command only pulls the contents of the scale function from the registry if it’s not already present.
If the function is already present, it will not be overwritten unless the --force
flag is passed.