ocibundle

package
v0.11.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 21 Imported by: 1

Documentation

Overview

Package ocibundle pulls a bundle of configuration files from an OCI registry. It is shared by the clients that pull on the user's machine and by the server, which pulls on the caller's behalf; the server passes the limits and the restricted HTTP client from NewPublicHTTPClient.

Index

Constants

View Source
const Scheme = "oci://"

Scheme prefixes an OCI reference given where a file or directory could be.

Variables

This section is empty.

Functions

func IsPublicAddress

func IsPublicAddress(addr netip.Addr) bool

IsPublicAddress reports whether addr is a globally routable unicast address: not loopback, private, link-local (which holds the 169.254.169.254 metadata endpoint), unique-local, multicast, or unspecified.

func IsRef

func IsRef(input string) bool

IsRef reports whether an input is an OCI reference rather than a file, directory, or "-".

func NewPublicHTTPClient

func NewPublicHTTPClient() *http.Client

NewPublicHTTPClient returns a client for pulling on someone else's behalf: it speaks only HTTPS and connects only to public addresses. A registry reference is caller-supplied, so without these checks a pull could reach the puller's own network -- a cloud metadata endpoint, a database, an internal service. The address is checked when each connection is dialed, after DNS resolution, so a name that resolves to a private address is refused too, as is every redirect and token request, since they are all dialed the same way.

func NewestRelease added in v0.9.12

func NewestRelease(ctx context.Context, rawRepo string, opts Options) (string, error)

NewestRelease returns the newest tag of a repository that names a release: X.Y.Z, with or without a leading "v". Other tags, such as latest or a pre-release, are passed over. rawRepo names the repository, without a tag.

func ReadImageFile added in v0.9.12

func ReadImageFile(ctx context.Context, rawRef, filePath string, opts Options) ([]byte, string, error)

ReadImageFile reads one file from a container image without running it, such as configuration an image ships beside its binary. Layers are read from the newest down, and the first that holds the file wins, as in the image's filesystem, so an image that adds the file in its last layer costs one small fetch. An image index is read through its first platform's image, so the file has to be the same on every platform. It returns the file and the digest of the manifest the reference resolved to. opts.Include is ignored.

Types

type Bundle

type Bundle struct {
	// Digest is the digest of the manifest the reference resolved to. Pulling
	// Ref@Digest later reads exactly the same bundle.
	Digest string
	Files  []File
}

Bundle is what a pull extracted.

func Pull

func Pull(ctx context.Context, rawRef, digest string, opts Options) (*Bundle, error)

Pull fetches an OCI artifact and extracts the files it carries. The artifact may carry them as a tar or tar+gzip layer (as `cub release publish` and Flux produce) or as individual file layers (as `oras push <files>` produces), so any bundle a GitOps toolchain can consume works here. A non-empty digest pulls that manifest instead of the one the reference's tag names now.

type Credentials

type Credentials struct {
	Username string
	Password string
}

Credentials authenticate a pull. Registries that issue access tokens take the token as the password.

type File

type File struct {
	Path    string
	Content []byte
}

File is one extracted file, with its path within the bundle.

type Limits

type Limits struct {
	MaxManifestBytes int64
	MaxLayers        int
	// MaxLayerBytes bounds each layer as stored, before decompression.
	MaxLayerBytes int64
	// MaxFiles and MaxTotalBytes bound the files extracted, after decompression,
	// so a small compressed layer cannot expand without bound.
	MaxFiles      int
	MaxTotalBytes int64
}

Limits bound what a pull reads. A zero field is unlimited.

type Options

type Options struct {
	// Credentials are used for this pull only. Nil pulls anonymously.
	Credentials *Credentials
	UserAgent   string
	// HTTPClient carries every request, including token and redirect requests.
	// Nil uses a client that retries transient failures.
	HTTPClient *http.Client
	// PlainHTTPLoopback pulls from a loopback registry over plain HTTP, as local
	// development registries are served.
	PlainHTTPLoopback bool
	// Include selects the files to extract by path. Nil extracts every file.
	Include func(path string) bool
	Limits  Limits
}

Options configure a pull.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL