ocibundle

package
v0.4.20 Latest Latest
Warning

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

Go to latest
Published: Sep 14, 2026 License: MIT Imports: 20 Imported by: 0

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.

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