Pin a version¶

This package resolves what you ask for. It does not choose versions, and there is no "latest" to ask for — so the version has to come from somewhere in your own code or configuration.

Put it in a constant¶

For most tools the version belongs beside the code that depends on it:

// The runtime this build was tested against. Changing it is a code change,
// reviewed like any other.
const runtimeVersion = "1.28.0"

ref := artifacts.Ref{Name: "onnxruntime", Version: runtimeVersion}

A constant means the bump appears in a diff, runs through CI, and is attributable to a commit. That is the whole benefit — not ceremony for its own sake.

Build the asset name from the platform¶

Artefact filenames encode the platform, so derive the name rather than hard-coding one per build:

var assets = map[string]string{
    "linux/amd64":  "onnxruntime-linux-x64-%s.tgz",
    "linux/arm64":  "onnxruntime-linux-aarch64-%s.tgz",
    "darwin/arm64": "onnxruntime-osx-arm64-%s.tgz",
}

pattern, ok := assets[artifacts.Platform()]
if !ok {
    return fmt.Errorf("no runtime build for %s", artifacts.Platform())
}

file := fmt.Sprintf(pattern, runtimeVersion)

artifacts.Platform() returns GOOS/GOARCH, matching how the channel's inventory records platforms.

The map is deliberately not exhaustive. A platform absent from it should fail in your code with a message naming the platform, rather than reaching the channel and coming back as a missing file.

Check what a version contains first¶

To find out which platforms exist without downloading anything:

files, err := client.Manifest(ctx, ref)

This fetches the manifest and its signature, verifies one against the other, and returns the filenames with their digests. It is the cheap way to answer "was this platform published?" — and the answer is authoritative, because it comes from signed data rather than from a URL responding.

If the version does not exist¶

Resolve and Manifest both return ErrNotFound when the channel has no such artefact-version:

if errors.Is(err, artifacts.ErrNotFound) {
    // usually a typo, or a version nobody has approved yet
}

Approving a version is a merge request against artifacts.yaml in the artifacts channel, not something a consumer can trigger.

What not to do¶

Do not resolve a status. The channel's inventory labels versions supported, legacy and untested, and it is tempting to treat those as channels you could point at. They are advisory labels for humans, and this package will not resolve against them — see Why status is not a channel for why that refusal is deliberate.

Do not derive the version from user input. It reaches a URL. The bounds are in place — the path components are escaped, the download is size-capped — but a version that comes from a config file someone else controls means your tool loads whatever they nominate, and every one of those is correctly signed.