Documentation
¶
Overview ¶
Package yazip provides a high-level, ergonomic API for extracting zip archives. It wraps Go's archive/zip standard library with a functional options pattern that enables common operations, such as filtering files, controlling destination directories, and enforcing security limits, without requiring boilerplate code.
Basic Usage ¶
err := yazip.Extract(ctx, "archive.zip")
With Options ¶
err := yazip.Extract(ctx, "archive.zip",
yazip.WithDestination("/tmp/output"),
yazip.WithCreateDir(),
yazip.WithIgnorePrefix("__MACOSX", "."),
yazip.WithMaxTotalSize(500*1024*1024),
)
Security ¶
Zip-slip protection is always enabled and cannot be disabled. Archive entries that would resolve outside the destination directory cause an immediate error.
Size and count limits can be set via WithMaxTotalSize and WithMaxFiles to protect against zip bombs.
Index ¶
- func Extract(ctx context.Context, zipPath string, opts ...Option) error
- func ExtractReader(ctx context.Context, r io.ReaderAt, size int64, opts ...Option) error
- type Option
- func WithCreateDir() Option
- func WithDestination(dir string) Option
- func WithFilter(fn func(string, fs.FileInfo) bool) Option
- func WithFlatten() Option
- func WithIgnore(paths ...string) Option
- func WithIgnorePrefix(prefixes ...string) Option
- func WithIgnoreRegex(patterns ...string) Option
- func WithLogger(logger *slog.Logger) Option
- func WithMaxFiles(n int) Option
- func WithMaxTotalSize(n int64) Option
- func WithMode(mode fs.FileMode) Option
- func WithOnly(paths ...string) Option
- func WithOnlyRegex(patterns ...string) Option
- func WithOverwrite(mode OverwriteMode) Option
- func WithPreservePermissions() Option
- type OverwriteMode
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Option ¶
type Option func(*options)
Option configures extraction behavior. Use the With* functions to create options.
func WithCreateDir ¶
func WithCreateDir() Option
WithCreateDir creates a directory named after the zip file inside the destination.
func WithDestination ¶
WithDestination sets the extraction target directory.
func WithFilter ¶
WithFilter sets a custom per-entry filter function.
func WithFlatten ¶
func WithFlatten() Option
WithFlatten discards directory structure and extracts all files into destination root.
func WithIgnore ¶
WithIgnore adds exact relative paths to the ignore set.
func WithIgnorePrefix ¶
WithIgnorePrefix skips entries whose name starts with any provided prefix. Prefixes are matched against the last element of the relative entry path
func WithIgnoreRegex ¶
WithIgnoreRegex skips entries matching any provided regex pattern.
func WithLogger ¶
WithLogger sets a custom structured logger for extraction.
func WithMaxFiles ¶
WithMaxFiles limits the number of files processed from the archive.
func WithMaxTotalSize ¶
WithMaxTotalSize limits cumulative extracted bytes across all files.
func WithOnlyRegex ¶
WithOnlyRegex extracts only entries matching at least one provided regex pattern.
func WithOverwrite ¶
func WithOverwrite(mode OverwriteMode) Option
WithOverwrite sets the overwrite policy.
func WithPreservePermissions ¶
func WithPreservePermissions() Option
WithPreservePermissions uses permissions stored in the archive when available.
type OverwriteMode ¶
type OverwriteMode int
OverwriteMode controls behavior when a destination file already exists.
const ( // OverwriteAlways overwrites destination files when they already exist. OverwriteAlways OverwriteMode = iota // OverwriteNever keeps destination files unchanged when they already exist. OverwriteNever // OverwriteIfNewer overwrites destination files only when the archive entry // has a newer modification time than the destination file. OverwriteIfNewer )
Source Files