expand

package
v1.2.1 Latest Latest
Warning

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

Go to latest
Published: Aug 26, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package expand defines the Expander interface and a registry of expanders for compressed files.

Index

Constants

View Source
const (
	DefaultMaxEntrySize int64 = 500 * 1024 * 1024
	DefaultMaxTotalSize int64 = 1024 * 1024 * 1024
	DefaultFilesLimit   int   = 10000
)

Default resource limits applied to expanders to guard against decompression bombs. DefaultMaxEntrySize matches the Conforma CLI's maxTarEntrySize (500 MiB per extracted entry); DefaultMaxTotalSize caps the whole-archive extracted size; DefaultFilesLimit caps the entry count.

Variables

This section is empty.

Functions

func CopyBounded added in v1.2.1

func CopyBounded(dst io.Writer, src io.Reader, copied *int64, max int64, buf []byte) error

CopyBounded copies src into dst using buf as scratch space, adding the bytes actually written to *copied and failing if *copied exceeds max. Enforcing on bytes actually read defeats archives that under-declare their sizes. Callers reuse one buf across many copies to avoid a per-call allocation.

func IsCompressedFile

func IsCompressedFile(filePath string) (bool, error)

IsCompressedFile reports whether the file at filePath begins with a known compression magic number.

func IsTarFile

func IsTarFile(filePath string) (bool, error)

IsTarFile checks whether the file at filePath is a tar archive by reading the standard tar magic bytes at offset 257 ("ustar\0" or "ustar ").

func RegisterExpander

func RegisterExpander(e Expander)

RegisterExpander adds an Expander to the global registry.

func RemoveOnError added in v1.2.1

func RemoveOnError(path string, created bool, err *error)

RemoveOnError removes path when *err is non-nil and created is true. Use it as `defer expand.RemoveOnError(dst, createdDst, &err)` so a failed extraction does not leave partial (possibly attacker-controlled) output behind, without deleting a destination that already existed.

Types

type ExpandOptions

type ExpandOptions struct {
	// MaxEntrySize bounds the size of a single extracted entry.
	MaxEntrySize int64
	// MaxTotalSize bounds the cumulative extracted size across the archive.
	MaxTotalSize int64
	// FilesLimit bounds the number of entries extracted.
	FilesLimit int
}

ExpandOptions holds extraction limits. For every limit the zero value means "use the default" (so a zero-value expander is safe, not unlimited), and a negative value explicitly disables that check.

func DefaultExpandOptions added in v1.2.1

func DefaultExpandOptions() ExpandOptions

DefaultExpandOptions returns the safe default limits.

func ResolveOptions added in v1.2.1

func ResolveOptions(opts ...Option) ExpandOptions

ResolveOptions returns ExpandOptions starting from the safe defaults with the given overrides applied.

func (ExpandOptions) Effective added in v1.2.1

func (o ExpandOptions) Effective() (maxEntry, maxTotal int64, filesLimit int)

Effective resolves the options to the limits an expander enforces: zero values use the defaults and negative values disable the corresponding check. Expanders embed ExpandOptions and call this so the resolution lives in one place.

type Expander

type Expander interface {
	Expand(ctx context.Context, source string, destination string, umask os.FileMode) error
	Matcher(extension string) bool
}

Expander defines the interface for extracting compressed archives.

func GetExpander

func GetExpander(extension string) Expander

GetExpander returns the first registered Expander whose Matcher accepts the given extension.

type Option added in v1.2.1

type Option func(*ExpandOptions)

Option overrides a field of ExpandOptions.

func WithFilesLimit added in v1.2.1

func WithFilesLimit(n int) Option

WithFilesLimit sets the maximum number of entries extracted. Zero uses the default; a negative value disables the check.

func WithMaxEntrySize added in v1.2.1

func WithMaxEntrySize(n int64) Option

WithMaxEntrySize sets the maximum size of a single extracted entry. Zero uses the default; a negative value disables the check.

func WithMaxTotalSize added in v1.2.1

func WithMaxTotalSize(n int64) Option

WithMaxTotalSize sets the maximum cumulative extracted size. Zero uses the default; a negative value disables the check.

Directories

Path Synopsis
Package bzip2 implements an Expander for standalone bzip2 compressed files.
Package bzip2 implements an Expander for standalone bzip2 compressed files.
Package tar implements an Expander for tar archives, including gzip and bzip2 compressed variants.
Package tar implements an Expander for tar archives, including gzip and bzip2 compressed variants.
Package zip implements an Expander for ZIP archives.
Package zip implements an Expander for ZIP archives.

Jump to

Keyboard shortcuts

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