Skip to main content
A function is what callers invoke. It carries no behaviour of its own. Its versions do: each one is an immutable spec, built once, that never changes under a caller who pinned it.

Functions

CreateFunction creates a function and its version 1 in one call. A function’s name is required, at most 128 bytes and unique within its tenant. A second function with the same name is ALREADY_EXISTS. The function owns the settings every version runs with. UpdateFunction changes them, and a change applies to the next invocation of any version, including invocations already waiting in the queue. A change of resources makes every version a new artifact. Each host builds and snapshots it again at the new size the first time it runs it. DeleteFunction removes the function with its versions and its invocations.

Versions

CreateFunctionVersion adds a version to an existing function. Versions are numbered from 1 and count up. A version returns as soon as it is accepted, in BUILDING, and moves to one of two outcomes:
  • READY: it built and can run. The newest READY version is the function’s current_version.
  • FAILED: it did not build. status_message says why and build_log holds the tail of the build’s output. A failed version stays failed. Fix the spec and create a new version.
A READY version records image_digest, the content digest its image resolved to at build time. The version always runs that digest, even when the tag moves later. Its contract is part of the version too, so a caller that pins a version always gets the contract it was written against.

The spec

The server validates a spec before it accepts the version. The contract must compile, every name in secrets must exist in the tenant, and a source needs the server to have an artifacts bucket. GetFunctionVersion returns the spec with the source files’ content filled back in.

Pinning a version

An invocation runs the function’s current_version unless it pins one. Over plain HTTP, ?version= pins it:
On the API, version on InvokeRequest does the same, and 0 means the current version. The response names the version that ran, in the Alchemy-Version header or the version field.

Runtimes

ListRuntimes returns the runtimes a function can be built from source on, each with its image, the handler file the image runs and a starter handler per contract kind. It also returns the limits a source is held to. The images live under RUNTIME_IMAGE_PREFIX, ghcr.io/galaxy-io/alchemy/runtime by default. runtime/static:13 is not in the list: it runs a binary built elsewhere, so it is used as the base of an image function.