compression

Documentation

Overview

Package compression provides utilities for working with compressed archives. Supports ZIP and TAR archive creation and extraction with various compression methods.

ZIP Usage

Extracting:

err := compression.UnZip("/path/to/archive.zip", "/path/to/destination")
if err != nil {
    log.Fatalf("Failed to extract: %v", err)
}

Creating:

// With deflate compression (default)
err := compression.Zip("/path/to/source", "/path/to/archive.zip")

// Without compression (store only)
err := compression.Zip("/path/to/source", "/path/to/archive.zip",
    compression.WithZipStore())

TAR Usage

Extracting (auto-detects compression):

err := compression.UnTar("/path/to/archive.tar.gz", "/path/to/destination")
if err != nil {
    log.Fatalf("Failed to extract: %v", err)
}

Creating:

// Gzip compression (auto-detected from extension)
err := compression.Tar("/path/to/source", "/path/to/archive.tar.gz")

// Explicit compression option
err := compression.Tar("/path/to/source", "/path/to/archive.tar",
    compression.WithBzip2Compression())

Supported Formats

• ZIP: .zip (store or deflate compression)
• TAR: .tar, .tar.gz/.tgz, .tar.bz2/.tbz2

Security

All extraction functions include protection against path traversal attacks (zip slip/tar slip) by validating that extracted files remain within the destination directory.

Index

• Variables
• func Tar(sourcePath, destTarPath string, opts ...TarOption) error
• func UnTar(tarPath, destDir string) error
• func UnZip(zipPath, destDir string) error
• func Zip(sourcePath, destZipPath string, opts ...ZipOption) error
• type TarOption
  • func WithBzip2Compression() TarOption
  • func WithGzipCompression() TarOption
  • func WithNoCompression() TarOption
• type ZipOption
  • func WithZipDeflate() ZipOption
  • func WithZipStore() ZipOption

Variables

var (
	// ErrTarSlip is returned when a tar archive contains files that would be
	// extracted outside the destination directory (path traversal attack).
	ErrTarSlip = errors.New("tar slip: file path escapes destination directory")

	// ErrUnsupportedTarEntry is returned when encountering unsupported tar entry types
	// such as device files, FIFOs, or other special files.
	ErrUnsupportedTarEntry = errors.New("unsupported tar entry type")

	// ErrInvalidSymlink is returned when a symlink points outside the destination directory.
	ErrInvalidSymlink = errors.New("symlink points outside destination directory")

	// ErrUnknownCompression is returned when the compression format cannot be determined.
	ErrUnknownCompression = errors.New("unknown compression format")
)

TAR-related error variables

var ErrZipSlip = errors.New("zip slip: file path escapes destination directory")

ErrZipSlip is returned when a zip archive contains files that would be extracted outside the destination directory (path traversal attack).

Functions

func Tar

func Tar(sourcePath, destTarPath string, opts ...TarOption) error

Tar creates a TAR archive from the specified source path. The source can be a single file or a directory (which will be recursively archived).

Compression is automatically detected from the destination file extension:

• .tar.gz, .tgz -> gzip compression
• .tar.bz2, .tbz2 -> bzip2 compression
• .tar -> no compression

Compression can be explicitly overridden using TarOption functions:

• WithGzipCompression()
• WithBzip2Compression()
• WithNoCompression()

The archive preserves file permissions, modification times, and directory structure. Symbolic links are stored in the archive (not followed).

Parameters:

• sourcePath: Path to the file or directory to archive
• destTarPath: Destination path for the tar archive
• opts: Optional configuration functions

Returns an error if the source cannot be read, the destination cannot be created, or if file operations fail during archiving.

Example:

// Create gzip-compressed tar from directory
err := Tar("/path/to/source", "/path/to/archive.tar.gz")

// Create bzip2-compressed tar with explicit option
err := Tar("/path/to/source", "/path/to/archive.tar", WithBzip2Compression())

func UnTar

func UnTar(tarPath, destDir string) error

UnTar extracts a TAR archive to the specified destination directory. It automatically detects the compression format based on file extension (.tar, .tar.gz, .tgz, .tar.bz2, .tbz2) and handles decompression accordingly.

The function creates directories as needed and preserves the archive's directory structure, file permissions, and symbolic links.

Security: This function validates that all extracted files remain within the destination directory to prevent tar slip (path traversal) attacks. It also validates that symlinks do not point outside the destination directory.

Parameters:

• tarPath: Path to the TAR file to extract
• destDir: Destination directory for extracted files

Returns an error if the archive cannot be opened, read, if file operations fail, if a tar slip attack is detected, or if unsupported entry types are encountered.

func UnZip

func UnZip(zipPath, destDir string) error

UnZip extracts a ZIP archive to the specified destination directory. It creates directories as needed and preserves the archive's directory structure.

Security: This function validates that all extracted files remain within the destination directory to prevent zip slip (path traversal) attacks.

Parameters:

• zipPath: Path to the ZIP file to extract
• destDir: Destination directory for extracted files

Returns an error if the archive cannot be opened, read, if file operations fail, or if a zip slip attack is detected.

func Zip

func Zip(sourcePath, destZipPath string, opts ...ZipOption) error

Zip creates a ZIP archive from the specified source path. The source can be a single file or a directory (which will be recursively archived).

By default, deflate (gzip) compression is used. This can be changed using ZipOption functions:

• WithZipDeflate() - Use deflate compression (default)
• WithZipStore() - Store files without compression

The archive preserves file permissions, modification times, and directory structure.

Note: Bzip2 compression is not supported for ZIP archives due to limited Go standard library support.

Parameters:

• sourcePath: Path to the file or directory to archive
• destZipPath: Destination path for the zip archive
• opts: Optional configuration functions

Returns an error if the source cannot be read, the destination cannot be created, or if file operations fail during archiving.

Example:

// Create zip with deflate compression (default)
err := Zip("/path/to/source", "/path/to/archive.zip")

// Create zip without compression
err := Zip("/path/to/source", "/path/to/archive.zip", WithZipStore())

Types

type TarOption

type TarOption func(*tarConfig)

TarOption is a function that configures tar creation options.

func WithBzip2Compression

func WithBzip2Compression() TarOption

WithBzip2Compression configures tar creation to use bzip2 compression. The resulting archive will be in .tar.bz2 format.

func WithGzipCompression

func WithGzipCompression() TarOption

WithGzipCompression configures tar creation to use gzip compression. The resulting archive will be in .tar.gz format.

func WithNoCompression

func WithNoCompression() TarOption

WithNoCompression configures tar creation to create an uncompressed tar archive. The resulting archive will be in .tar format.

type ZipOption

type ZipOption func(*zipConfig)

ZipOption is a function that configures zip creation options.

func WithZipDeflate

func WithZipDeflate() ZipOption

WithZipDeflate configures zip creation to use deflate (gzip) compression. This is the standard compression method for ZIP archives.

func WithZipStore

func WithZipStore() ZipOption

WithZipStore configures zip creation to use no compression (store only). Files are stored as-is without any compression.