README
¶
onnxruntime
Resolve the ONNX Runtime shared library for the machine you are on: a configured path, a library bundled beside the executable, a cached copy, or the estate's signed artefact channel — in that order.
client, err := artifacts.New(verifier, artifacts.WithCache(cache))
resolver, err := onnxruntime.New(client)
lib, err := resolver.Resolve(ctx, cfg.LibraryPath) // "" to let it decide
lib is a path. Hand it to whichever binding loads the runtime.
Why it exists
Two tools were about to grow the same hundred lines: a platform table, a
download, an extraction, a cache. The download half belongs to
go/artifacts, which verifies a
signature over a manifest before a byte is fetched. What is left is the half
that is specific to this runtime — which archive a platform wants, and how to
get one file out of it.
Specification:
specs/0013
D1, in the phpbotscout wiki until the artefact project takes ownership.
The resolution order
| Rung | Source | Wins because |
|---|---|---|
| 1 | The path you passed | A caller who has said where their runtime is should not be second-guessed |
| 2 | libonnxruntime.so beside the executable |
How a packaged application ships one |
| 3 | The cache | Already verified and extracted |
| 4 | The artefact channel | Verified, then extracted and cached |
An explicit path is never checked for existence. If it is wrong you get a loader error naming your path, which is more use than this package quietly substituting a different runtime.
What it does not do
It does not download, verify, or decide what is approved — go/artifacts does
all three, and this module holds no digests as a result. A SHA-256 constant in
Go source cannot be rotated or revoked and says nothing about who published the
bytes.
It does not load the library or bind to the C API. It returns a path.
Extraction
Tar extraction is where path traversal lives, so the entry's own name is never used to build an output path. The destination is chosen before the archive is opened, and an entry is matched by the base name of its path. A hostile name can therefore cause a miss; it cannot cause a write.
Non-regular entries are skipped, which is the ordinary case rather than a hypothetical — the real archives carry symlinks beside the versioned object.
Documentation
docs/ — tutorial, how-to guides, reference and the design rationale,
published by CI as a Zensical site. The Go API is on
pkg.go.dev.
Licence
Apache-2.0. See LICENSE.
Documentation
¶
Overview ¶
Package onnxruntime resolves the ONNX Runtime shared library that native inference providers load at run time.
It answers one question — "where is libonnxruntime for this machine?" — and tries, in order: a path the caller configured, a library bundled beside the executable, a copy already extracted into the cache, and finally the estate's artefact channel.
What this package does NOT do ¶
It does not download, verify or decide what is approved. Those belong to gitlab.com/phpboyscout/go/artifacts, which fetches by name and version, checks a signature over a manifest that names the artefact it describes, consults a signed index of what is approved, and hands back a path.
What is left is the part that resolver deliberately refused: opening the archive. Extraction is where tar traversal lives, and go/artifacts declined the job rather than do it badly — so it is done here, once, for one file.
The consequence worth noticing is that this package contains no digests. An earlier design carried a table of platforms and SHA-256 constants; a digest in a Go constant cannot be rotated or revoked and says nothing about who published the bytes. This package now asks for a name and a version and is given a path to bytes whose provenance somebody else established.
Index ¶
Constants ¶
const Artefact = "onnxruntime"
Artefact is the name this runtime is published under in the channel.
const DefaultVersion = "1.28.0"
DefaultVersion is the runtime this module resolves unless told otherwise.
Pinned rather than floating. A resolver that asked for "latest" would load a different runtime depending on when it ran, and an ABI change would surface as an inference failure rather than as a version bump somebody reviewed.
It must expose C API 23 or above, which the purego binding targets.
renovate: datasource=gitlab-packages depName=phpboyscout/artifacts:onnxruntime versioning=semver
Variables ¶
var ( // ErrNoPlatformBuild means the channel publishes no archive for this // GOOS/GOARCH at the requested version. // // A real case rather than a defensive one: upstream dropped macOS Intel // between 1.23.0 and 1.26.0, so a machine that resolved 1.23.0 happily // gets nothing at 1.28.0. The remedy is a configured path, and the error // says so. ErrNoPlatformBuild = errors.New("onnxruntime: no build for this platform") // ErrNotInArchive means the archive did not contain the expected library. // The bytes verified, so this is a channel that published something // unexpected rather than something that arrived corrupted. ErrNotInArchive = errors.New("onnxruntime: library not found in the archive") // ErrOversizeLibrary means the decompressed library exceeded the bound. ErrOversizeLibrary = errors.New("onnxruntime: library exceeds the size limit") // ErrNoFetcher means New was called without one. // // Exported so the refusal can be matched rather than string-compared. It is // a programming error rather than a runtime condition, but a caller wiring // a resolver from configuration can still reach it. ErrNoFetcher = errors.New("onnxruntime: a fetcher is required") )
Errors callers may match on.
Functions ¶
This section is empty.
Types ¶
type Fetcher ¶
type Fetcher interface {
// Resolve returns a local path to a verified file of an artefact-version.
Resolve(ctx context.Context, ref artifacts.Ref, file string) (string, error)
}
Fetcher supplies a verified artefact.
Satisfied by *artifacts.Client. An interface because the caller owns the trust anchors: the client carries the key embedded in THEIR binary, and a library that constructed its own would be choosing what to trust on their behalf.
type Option ¶
type Option func(*Resolver)
Option configures a Resolver.
func WithCacheDir ¶
WithCacheDir stores extracted libraries under dir.
Defaults to <user cache>/phpboyscout/onnxruntime/<version>. Deliberately not named after any one tool: krites cached under a "krites" directory, so a different tool's install populated a directory named after krites — the kind of thing nobody notices until they go looking for disk usage.
func WithExecutableDir ¶
WithExecutableDir sets where a bundled library is looked for.
func WithPlatform ¶
WithPlatform overrides the GOOS/GOARCH used to select an archive, for tests and for cross-provisioning.
func WithVersion ¶
WithVersion resolves a runtime other than DefaultVersion.
type Resolver ¶
type Resolver struct {
// contains filtered or unexported fields
}
Resolver locates the ONNX Runtime shared library.
The zero value is not usable; construct with New.
func New ¶
New builds a Resolver that fetches through the given Fetcher.
The Fetcher is required. A resolver that could be built without one would have a mode in which it loads a shared library from somewhere nobody verified, and a shared library is about the worst thing to be casual about: it is executed.
func (*Resolver) Resolve ¶
Resolve returns a path to the shared library.
The order is the decision. An explicit path always wins, because a caller who has said where their runtime is should not be second-guessed — they may be on a platform with no published build, or running a distribution package, or testing against a build they made. Then a library bundled beside the executable, which is how a packaged application ships one. Then the cache. Only then the network.
Source Files