> ## Documentation Index
> Fetch the complete documentation index at: https://alchemy.getgalaxy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Write a Go function

> Deploy a Go handler as source that a host compiles on the go:1.27 runtime, or as a static binary on the static:13 image, and invoke it.

A Go function is a static binary that reads its input on stdin and writes its
output on stdout. Alchemy runs it two ways:

* **From source.** You send `main.go`. A host compiles it in a microVM on the
  `go:1.27-build` image and the version runs the binary on `go:1.27`.
* **As an image.** You compile the binary yourself and copy it into an image
  on `static:13`.

The commands assume a server on `localhost:8780` with no auth, as in the
[Quickstart](https://alchemy.getgalaxy.io/pages/get-started/quickstart.md). With auth enabled, add
`-H "Authorization: Bearer $TOKEN"` to every call.

## The Go runtime

| Image | What it is |
| - | - |
| `<imagePrefix>/go:1.27` | Distroless static Debian 13 that runs `/app/handler` |
| `<imagePrefix>/go:1.27-build` | `golang:1.27-alpine` with the module's dependencies downloaded and compiled |
| `<imagePrefix>/static:13` | The same distroless base, for binaries built elsewhere |

The default prefix is `ghcr.io/galaxy-io/alchemy/runtime`, set by the server's
`RUNTIME_IMAGE_PREFIX`. Ask the server for the exact image:

```sh theme={null}
curl -s localhost:8780/functions.v1.FunctionsService/ListRuntimes \
  -H 'Content-Type: application/json' -d '{}' \
  | jq -r '.runtimes[] | select(.id == "go") | .image'
```

Compiles run offline. Your files land in a module named `handler` whose only
requirement is `github.com/apache/arrow-go/v18` v18.8.0, so a source can
import the standard library and Arrow, nothing else. A function with other
dependencies ships as an [image](#deploy-as-an-image).

## The protocol

For each invocation the supervisor starts `/app/handler` as a new process,
writes the input to stdin and closes it, takes stdout as the output and
streams stderr to the invocation's log. A non-zero exit is a crash, reported
with the exit status and the last 4 KiB of stderr. A JSON Schema contract
passes one JSON value each way, an Arrow contract one IPC stream with exactly
one record batch. See [Contracts](https://alchemy.getgalaxy.io/pages/concepts/contracts.md).

## Write a handler

The runtime's JSON Schema starter:

```go main.go theme={null}
package main

import (
	"encoding/json"
	"fmt"
	"os"
)

func handler(event any) (any, error) {
	return event, nil
}

func main() {
	var event any
	if err := json.NewDecoder(os.Stdin).Decode(&event); err != nil {
		fail(err)
	}
	out, err := handler(event)
	if err != nil {
		fail(err)
	}
	if err := json.NewEncoder(os.Stdout).Encode(out); err != nil {
		fail(err)
	}
}

func fail(err error) {
	fmt.Fprintln(os.Stderr, err)
	os.Exit(1)
}
```

For an Arrow contract, read with `ipc.NewReader(os.Stdin)`, take one record
batch, and write one batch with the same number of rows through
`ipc.NewWriter(os.Stdout, ...)`.
[`examples/embed/go/main.go`](https://github.com/galaxy-io/alchemy/tree/main/examples/embed/go)
is a complete one. It reads `id` and `text` columns and returns the cleaned
text, its token count and a 64-dimension embedding per row. It uses the same
Arrow version as the runtime, so it compiles as a source unchanged.

The Arrow contract's schemas are serialized Arrow IPC. Build them as in the
[Python guide](https://alchemy.getgalaxy.io/pages/guides/python-function.md), which writes `arrow.json` for
the embed example, or define the fields in the web UI.

## Deploy from source

A source version names `go:1.27` as its image and carries `main.go`. When the
version builds, the server sees that the image has a build image and compiles
first:

1. The least busy host boots `go:1.27-build` in a microVM of its own, with
   2 vCPUs and 2 GiB, or the host's whole memory budget when that is smaller.
2. The build image copies your files into the module and runs
   `go build -ldflags='-s -w'`. The compiler's output is the build log.
3. The host stores the binary as a layer in the artifacts bucket, and the
   version is built from `go:1.27` with that layer at `/app/handler`.

A compile has 3 minutes. Its result is kept by the build image's digest and
the source's, so the same files on the same build image compile once. A
republished build image compiles afresh. The version's spec
keeps your source, which `GetFunctionVersion` returns.

**1. Create the function**

```text Web UI theme={null}
1. Click New function.
2. Choose Code and pick Go 1.27 as the language.
3. Define the contract.
4. Replace the starter with your main.go.
5. Set resources and limits, name the function and click
   Create function.
```

```sh API theme={null}
IMAGE=$(curl -s localhost:8780/functions.v1.FunctionsService/ListRuntimes \
  -H 'Content-Type: application/json' -d '{}' \
  | jq -r '.runtimes[] | select(.id == "go") | .image')

jq -n --arg image "$IMAGE" --rawfile src examples/embed/go/main.go --slurpfile arrow arrow.json '{
  name: "embed-go",
  spec: {
    image: $image,
    protocol: "INVOCATION_PROTOCOL_EXEC",
    contract: {arrow: $arrow[0]},
    source: {files: [{path: "main.go", content: ($src | @base64)}]}
  }
}' | curl -s localhost:8780/functions.v1.FunctionsService/CreateFunction \
  -H 'Content-Type: application/json' -d @- | jq '{id: .function.id, status: .version.status}'
```

Send `.go` files only. A `go.mod` or `go.sum` you send replaces the
module's, and any requirement the build image has not downloaded fails
the offline build.

**2. Wait for the build**

```sh theme={null}
curl -s localhost:8780/functions.v1.FunctionsService/GetFunctionVersion \
  -H 'Content-Type: application/json' \
  -d '{"functionId": "<function-id>", "version": 1}' \
  | jq -r '.version | .status, .statusMessage, .buildLog'
```

A compile error fails the version. `statusMessage` starts with
`compile failed:` and `buildLog` holds the compiler's output.

> [!WARNING]
>
> Only the exact image `ListRuntimes` returns is compiled. A source on any
> other reference to a Go runtime, such as the public `ghcr.io` image on a
> server whose prefix points elsewhere, is laid over the image uncompiled,
> and every invocation crashes because `/app/handler` does not exist.

## Deploy as an image

Build the binary yourself when it needs other modules or build flags. The
embed example compiles in one stage and copies the binary onto `static:13`:

```dockerfile Dockerfile theme={null}
FROM golang:1.26-alpine AS build
WORKDIR /src
COPY go.mod go.sum main.go ./
RUN CGO_ENABLED=0 go build -trimpath -o /out/handler .

FROM ghcr.io/galaxy-io/alchemy/runtime/static:13
COPY --from=build /out/handler /app/handler
```

`static:13` has no libc, so build with `CGO_ENABLED=0`. Build for the hosts'
architecture and push:

```sh theme={null}
docker build --platform linux/amd64 -t registry.example.com/embed-go:1 examples/embed/go
docker push registry.example.com/embed-go:1
```

Create the function with that image and no `source`:

```sh theme={null}
jq -n --slurpfile arrow arrow.json '{
  name: "embed-go",
  spec: {
    image: "registry.example.com/embed-go:1",
    protocol: "INVOCATION_PROTOCOL_EXEC",
    contract: {arrow: $arrow[0]}
  }
}' | curl -s localhost:8780/functions.v1.FunctionsService/CreateFunction \
  -H 'Content-Type: application/json' -d @- | jq '{id: .function.id, status: .version.status}'
```

See [Deploy any OCI image](https://alchemy.getgalaxy.io/pages/guides/image-function.md) for private
registries.

## Invoke it

POST the input with the contract's content type. For the Arrow example,
write `input.arrows` as in the [Python guide](https://alchemy.getgalaxy.io/pages/guides/python-function.md):

```sh theme={null}
curl -s localhost:8780/functions/<function-id>/invoke \
  -H 'Content-Type: application/vnd.apache.arrow.stream' \
  --data-binary @input.arrows -o output.arrows
```

For a JSON contract, send `-H 'Content-Type: application/json'` and the value
with `-d`. The response carries `Alchemy-Invocation-Id` and `Alchemy-Version`.
A handler that exits non-zero answers `500`, and one past its timeout `504`.
See [HTTP invoke](https://alchemy.getgalaxy.io/pages/usage/http.md).

## Next steps

> [card] [Troubleshooting](https://alchemy.getgalaxy.io/pages/guides/troubleshooting.md)
>
> Read compile failures, crashes and contract violations.

> [card] [Runtimes and builds](https://alchemy.getgalaxy.io/pages/concepts/runtimes-and-builds.md)
>
> How a spec becomes a root filesystem and a snapshot.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.