Documentation
¶
Overview ¶
Package artifact provides artifact-agnostic OCI primitives shared by the ToolHive ecosystem: reproducible tar archive creation and extraction, reproducible gzip compression, OCI platform helpers, and pull-hardening (size/count/digest validation) for registry operations.
These primitives are independent of any particular artifact type (skills, plugins, etc.). Artifact-specific media types, labels, and annotations live in the packages that define those artifacts (for example oci/skills).
Reproducible Archives ¶
CreateTar and Compress produce byte-stable output for identical input, which is what makes artifact digests deterministic:
data, err := artifact.CompressTar(files, artifact.DefaultTarOptions(), artifact.DefaultGzipOptions())
Platform Helpers ¶
PlatformString and ParsePlatform convert between OCI platform values and their "os/arch" or "os/arch/variant" string form.
Pull Hardening ¶
ValidatingTarget wraps an oras.Target and enforces size and structure limits on pushed content, defending against OOM and resource exhaustion from malicious registries during pull operations.
Stability ¶
This package is Alpha. Breaking changes are possible between minor versions.
Index ¶
- Constants
- Variables
- func Compress(data []byte, opts GzipOptions) ([]byte, error)
- func CompressTar(files []FileEntry, tarOpts TarOptions, gzipOpts GzipOptions) ([]byte, error)
- func CreateTar(files []FileEntry, opts TarOptions) ([]byte, error)
- func Decompress(data []byte) ([]byte, error)
- func DecompressWithLimit(data []byte, maxSize int64) ([]byte, error)
- func ParsePlatform(s string) (ocispec.Platform, error)
- func PlatformString(p ocispec.Platform) string
- type FileEntry
- type GzipOptions
- type TarOptions
- type ValidatingTarget
- func (v *ValidatingTarget) Exists(ctx context.Context, target ocispec.Descriptor) (bool, error)
- func (v *ValidatingTarget) Fetch(ctx context.Context, target ocispec.Descriptor) (io.ReadCloser, error)
- func (v *ValidatingTarget) Push(ctx context.Context, desc ocispec.Descriptor, content io.Reader) error
- func (v *ValidatingTarget) Resolve(ctx context.Context, reference string) (ocispec.Descriptor, error)
- func (v *ValidatingTarget) Tag(ctx context.Context, desc ocispec.Descriptor, reference string) error
Constants ¶
const ( // OSLinux is the Linux OS identifier used in OCI platform specs. OSLinux = "linux" // ArchAMD64 is the x86-64 architecture identifier used in OCI platform specs. ArchAMD64 = "amd64" // ArchARM64 is the 64-bit ARM architecture identifier used in OCI platform specs. ArchARM64 = "arm64" )
OS and architecture constants for OCI platform specifications.
const MaxBlobSize int64 = 100 * 1024 * 1024
MaxBlobSize is the maximum size of a blob (100MB).
const MaxDecompressedSize = 100 * 1024 * 1024
MaxDecompressedSize is the maximum size of decompressed data (100MB). This prevents decompression bombs.
const MaxManifestSize int64 = 1 * 1024 * 1024
MaxManifestSize is the maximum size of a manifest (1MB).
const MaxTarFileSize = 100 * 1024 * 1024
MaxTarFileSize is the maximum size of a single file in a tar archive (100MB). This prevents decompression bombs.
Variables ¶
var DefaultPlatforms = []ocispec.Platform{ {OS: OSLinux, Architecture: ArchAMD64}, {OS: OSLinux, Architecture: ArchARM64}, }
DefaultPlatforms are the default platforms for artifacts. These cover most Kubernetes clusters.
Functions ¶
func Compress ¶
func Compress(data []byte, opts GzipOptions) ([]byte, error)
Compress creates a reproducible gzip compressed byte slice. Headers are explicitly controlled for reproducibility: - ModTime: uses opts.Epoch (defaults to Unix epoch) - Name: empty (no filename) - Comment: empty - OS: 255 (unknown) for cross-platform consistency
func CompressTar ¶
func CompressTar(files []FileEntry, tarOpts TarOptions, gzipOpts GzipOptions) ([]byte, error)
CompressTar creates a reproducible .tar.gz from the given files.
func CreateTar ¶
func CreateTar(files []FileEntry, opts TarOptions) ([]byte, error)
CreateTar creates a reproducible tar archive from the given files. Files are sorted alphabetically and normalized headers are used to ensure deterministic output.
func DecompressWithLimit ¶
DecompressWithLimit decompresses gzip data with a size limit.
func ParsePlatform ¶
ParsePlatform parses a platform string in "os/arch" or "os/arch/variant" format.
func PlatformString ¶
PlatformString returns the platform in "os/arch" or "os/arch/variant" format.
Types ¶
type FileEntry ¶
type FileEntry struct {
Path string // Path within the archive
Content []byte // File content
Mode int64 // File mode (defaults to 0644)
}
FileEntry represents a file to include in a tar archive.
func DecompressTar ¶
DecompressTar extracts files from a .tar.gz archive.
func ExtractTar ¶
ExtractTar extracts files from a tar archive.
type GzipOptions ¶
type GzipOptions struct {
// Level is the compression level (defaults to gzip.BestCompression).
Level int
// Epoch is the modification time to use in the gzip header.
// If zero, uses Unix epoch (1970-01-01) for reproducibility.
Epoch time.Time
}
GzipOptions configures reproducible gzip compression.
func DefaultGzipOptions ¶
func DefaultGzipOptions() GzipOptions
DefaultGzipOptions returns default options for reproducible gzip compression.
type TarOptions ¶
type TarOptions struct {
// Epoch is the timestamp to use for all files (defaults to Unix epoch).
Epoch time.Time
}
TarOptions configures reproducible tar archive creation.
func DefaultTarOptions ¶
func DefaultTarOptions() TarOptions
DefaultTarOptions returns default options for reproducible tar archives.
type ValidatingTarget ¶
type ValidatingTarget struct {
// contains filtered or unexported fields
}
ValidatingTarget wraps an oras.Target to enforce size and count limits on pushed content. This prevents OOM and resource exhaustion from malicious registries during pull operations.
func NewValidatingTarget ¶
func NewValidatingTarget(inner oras.Target) *ValidatingTarget
NewValidatingTarget wraps an oras.Target with size and structure validation applied on every Push.
func (*ValidatingTarget) Exists ¶
func (v *ValidatingTarget) Exists(ctx context.Context, target ocispec.Descriptor) (bool, error)
Exists delegates to the inner target.
func (*ValidatingTarget) Fetch ¶
func (v *ValidatingTarget) Fetch(ctx context.Context, target ocispec.Descriptor) (io.ReadCloser, error)
Fetch delegates to the inner target.
func (*ValidatingTarget) Push ¶
func (v *ValidatingTarget) Push(ctx context.Context, desc ocispec.Descriptor, content io.Reader) error
Push validates size and structure limits before delegating to the inner target.
func (*ValidatingTarget) Resolve ¶
func (v *ValidatingTarget) Resolve(ctx context.Context, reference string) (ocispec.Descriptor, error)
Resolve delegates to the inner target.
func (*ValidatingTarget) Tag ¶
func (v *ValidatingTarget) Tag(ctx context.Context, desc ocispec.Descriptor, reference string) error
Tag delegates to the inner target.
Source Files