archive

Documentation

Overview

Package archive provides common types and functions for archive processing.

Index

• Variables
• func ExtractTar(tr *tar.Reader, fs billy.Filesystem, opt ExtractOptions) error
• func NewStabilizedGzipWriter(gr *gzip.Reader, w io.Writer, opts StabilizeOpts) (*gzip.Writer, error)
• func Stabilize(dst io.Writer, src io.Reader, f Format) error
• func StabilizeTar(tr *tar.Reader, tw *tar.Writer, opts StabilizeOpts) error
• func StabilizeWithOpts(dst io.Writer, src io.Reader, f Format, opts StabilizeOpts) error
• func StabilizeZip(zr *zip.Reader, zw *zip.Writer, opts StabilizeOpts) error
• type ContentSummary
  • func NewContentSummary(src io.Reader, f Format) (*ContentSummary, error)
  • func NewContentSummaryFromTar(tr *tar.Reader) (*ContentSummary, error)
  • func NewContentSummaryFromZip(zr *zip.Reader) (*ContentSummary, error)
  • func (cs *ContentSummary) Diff(other *ContentSummary) (leftOnly, diffs, rightOnly []string)
• type ExtractOptions
• type Format
• type GzipStabilizer
• type MutableGzipHeader
• type MutableZipFile
  • func (mf *MutableZipFile) Open() (io.Reader, error)
  • func (mf *MutableZipFile) SetContent(content []byte)
• type MutableZipReader
  • func NewMutableReader(zr *zip.Reader) MutableZipReader
  • func (mr MutableZipReader) WriteTo(zw *zip.Writer) error
• type StabilizeOpts
• type TarArchive
• type TarArchiveStabilizer
• type TarEntry
  • func (e TarEntry) WriteTo(tw *tar.Writer) error
• type TarEntryStabilizer
• type ZipArchiveStabilizer
• type ZipEntry
  • func (e ZipEntry) WriteTo(zw *zip.Writer) error
• type ZipEntryStabilizer

Variables

var AllGzipStabilizers = []any{
	StableGzipCompression,
	StableGzipName,
	StableGzipTime,
	StableGzipMisc,
}

var AllStabilizers = slices.Concat(AllZipStabilizers, AllTarStabilizers, AllGzipStabilizers)

var AllTarStabilizers []any = []any{
	StableTarFileOrder,
	StableTarTime,
	StableTarFileMode,
	StableTarOwners,
	StableTarXattrs,
	StableTarDeviceNumber,
}

var AllZipStabilizers []any = []any{
	StableZipFileOrder,
	StableZipModifiedTime,
	StableZipCompression,
	StableZipDataDescriptor,
	StableZipFileEncoding,
	StableZipFileMode,
	StableZipMisc,
}

var StableGzipCompression = GzipStabilizer{
	Name: "gzip-compression",
	Func: func(h *MutableGzipHeader) {
		h.Compression = gzip.NoCompression
	},
}

var StableGzipMisc = GzipStabilizer{
	Name: "gzip-misc",
	Func: func(h *MutableGzipHeader) {
		h.Comment = ""
		h.Extra = nil
		h.OS = 255
	},
}

var StableGzipName = GzipStabilizer{
	Name: "gzip-name",
	Func: func(h *MutableGzipHeader) {
		h.Name = ""
	},
}

var StableGzipTime = GzipStabilizer{
	Name: "gzip-time",
	Func: func(h *MutableGzipHeader) {

		h.ModTime = time.Time{}
	},
}

var StableTarDeviceNumber = TarEntryStabilizer{
	Name: "tar-device-number",
	Func: func(e *TarEntry) {

		e.Devmajor = 0
		e.Devminor = 0
	},
}

var StableTarFileMode = TarEntryStabilizer{
	Name: "tar-file-mode",
	Func: func(e *TarEntry) {
		e.Mode = int64(fs.ModePerm)
	},
}

var StableTarFileOrder = TarArchiveStabilizer{
	Name: "tar-file-order",
	Func: func(f *TarArchive) {
		slices.SortFunc(f.Files, func(a, b *TarEntry) int {
			return strings.Compare(a.Name, b.Name)
		})
	},
}

var StableTarOwners = TarEntryStabilizer{
	Name: "tar-owners",
	Func: func(e *TarEntry) {
		e.Uid = 0
		e.Gid = 0
		e.Uname = ""
		e.Gname = ""
	},
}

var StableTarTime = TarEntryStabilizer{
	Name: "tar-time",
	Func: func(e *TarEntry) {
		e.ModTime = time.UnixMilli(0)
		e.AccessTime = time.UnixMilli(0)
		e.ChangeTime = time.Time{}

		e.Format = tar.FormatPAX
	},
}

var StableTarXattrs = TarEntryStabilizer{
	Name: "tar-xattrs",
	Func: func(e *TarEntry) {
		clear(e.Xattrs)
		clear(e.PAXRecords)
	},
}

var StableZipCompression = ZipEntryStabilizer{
	Name: "zip-compression",
	Func: func(zf *MutableZipFile) {
		zf.Method = zip.Store
	},
}

var StableZipDataDescriptor = ZipEntryStabilizer{
	Name: "zip-data-descriptor",
	Func: func(zf *MutableZipFile) {
		zf.Flags = zf.Flags & ^dataDescriptorFlag
		zf.CRC32 = 0
		zf.CompressedSize = 0
		zf.CompressedSize64 = 0
		zf.UncompressedSize = 0
		zf.UncompressedSize64 = 0
	},
}

var StableZipFileEncoding = ZipEntryStabilizer{
	Name: "zip-file-encoding",
	Func: func(zf *MutableZipFile) {
		zf.NonUTF8 = false
	},
}

var StableZipFileMode = ZipEntryStabilizer{
	Name: "zip-file-mode",
	Func: func(zf *MutableZipFile) {
		zf.CreatorVersion = 0
		zf.ExternalAttrs = 0
	},
}

var StableZipFileOrder = ZipArchiveStabilizer{
	Name: "zip-file-order",
	Func: func(zr *MutableZipReader) {
		slices.SortFunc(zr.File, func(i, j *MutableZipFile) int {
			return strings.Compare(i.Name, j.Name)
		})
	},
}

var StableZipMisc = ZipEntryStabilizer{
	Name: "zip-misc",
	Func: func(zf *MutableZipFile) {
		zf.Comment = ""
		zf.ReaderVersion = 0
		zf.Extra = []byte{}

		zf.Flags = zf.Flags & dataDescriptorFlag
	},
}

var StableZipModifiedTime = ZipEntryStabilizer{
	Name: "zip-modified-time",
	Func: func(zf *MutableZipFile) {
		zf.Modified = time.UnixMilli(0)
		zf.ModifiedDate = 0
		zf.ModifiedTime = 0
	},
}

Functions

func ExtractTar

func ExtractTar(tr *tar.Reader, fs billy.Filesystem, opt ExtractOptions) error

ExtractTar writes the contents of a tar to a filesystem.

func NewStabilizedGzipWriter

func NewStabilizedGzipWriter(gr *gzip.Reader, w io.Writer, opts StabilizeOpts) (*gzip.Writer, error)

NewStabilizedGzipWriter applies the provided stabilizers to the gzip.Reader metadata. The caller is responsible for closing the returned writer.

NOTE: This abstraction differs from the other stabilizers because the compression level used in the gzip.Writer is not configurable after construction. As a result, a raw writer must be provided and a gzip.Writer returned to ensure a configurable compression level.

func Stabilize

func Stabilize(dst io.Writer, src io.Reader, f Format) error

Stabilize selects and applies the default stabilization routine for the given archive format.

func StabilizeTar

func StabilizeTar(tr *tar.Reader, tw *tar.Writer, opts StabilizeOpts) error

StabilizeTar strips volatile metadata and re-writes the provided archive in a standard form.

func StabilizeWithOpts

func StabilizeWithOpts(dst io.Writer, src io.Reader, f Format, opts StabilizeOpts) error

StabilizeWithOpts selects and applies the provided stabilization routine for the given archive format.

func StabilizeZip

func StabilizeZip(zr *zip.Reader, zw *zip.Writer, opts StabilizeOpts) error

StabilizeZip strips volatile metadata and rewrites the provided archive in a standard form.

Types

type ContentSummary

type ContentSummary struct {
	Files      []string
	FileHashes []string
	CRLFCount  int
}

ContentSummary is a summary of rebuild-relevant features of an archive.

func NewContentSummary

func NewContentSummary(src io.Reader, f Format) (*ContentSummary, error)

NewContentSummary constructs a ContentSummary for the given archive format.

func NewContentSummaryFromTar

func NewContentSummaryFromTar(tr *tar.Reader) (*ContentSummary, error)

NewContentSummaryFromTar returns a ContentSummary for a tar archive.

func NewContentSummaryFromZip

func NewContentSummaryFromZip(zr *zip.Reader) (*ContentSummary, error)

NewContentSummaryFromZip returns a ContentSummary for a zip archive.

func (*ContentSummary) Diff

func (cs *ContentSummary) Diff(other *ContentSummary) (leftOnly, diffs, rightOnly []string)

Diff returns the files that are only in this summary, the files that are in both summaries but have different hashes, and the files that are only in the other summary.

type ExtractOptions

type ExtractOptions struct {
	// SubDir is a directory within the TAR to extract relative to the provided filesystem.
	SubDir string
}

ExtractOptions provides options modifying ExtractTar behavior.

type Format

type Format int

Format represents the archive types of packages.

const (
	UnknownFormat Format = iota
	TarGzFormat
	TarFormat
	ZipFormat
	RawFormat
)

ArchiveType constants specify the type of archive of a file/target.

type GzipStabilizer

type GzipStabilizer struct {
	Name string
	Func func(*MutableGzipHeader)
}

type MutableGzipHeader

type MutableGzipHeader struct {
	*gzip.Header
	Compression int
}

type MutableZipFile

type MutableZipFile struct {
	zip.FileHeader
	File *zip.File
	// contains filtered or unexported fields
}

MutableZipFile wraps zip.File to allow in-place modification of the original.

func (*MutableZipFile) Open

func (mf *MutableZipFile) Open() (io.Reader, error)

func (*MutableZipFile) SetContent

func (mf *MutableZipFile) SetContent(content []byte)

type MutableZipReader

type MutableZipReader struct {
	*zip.Reader
	File    []*MutableZipFile
	Comment string
}

MutableZipReader wraps zip.Reader to allow in-place modification of the original.

func NewMutableReader

func NewMutableReader(zr *zip.Reader) MutableZipReader

func (MutableZipReader) WriteTo

func (mr MutableZipReader) WriteTo(zw *zip.Writer) error

type StabilizeOpts

type StabilizeOpts struct {
	Stabilizers []any
}

StabilizeOpts aggregates stabilizers to be used in stabilization.

type TarArchive

type TarArchive struct {
	Files []*TarEntry
}

type TarArchiveStabilizer

type TarArchiveStabilizer struct {
	Name string
	Func func(*TarArchive)
}

type TarEntry

type TarEntry struct {
	*tar.Header
	Body []byte
}

TarEntry represents an entry in a tar archive.

func (TarEntry) WriteTo

func (e TarEntry) WriteTo(tw *tar.Writer) error

WriteTo writes the TarEntry to a tar writer.

type TarEntryStabilizer

type TarEntryStabilizer struct {
	Name string
	Func func(*TarEntry)
}

type ZipArchiveStabilizer

type ZipArchiveStabilizer struct {
	Name string
	Func func(*MutableZipReader)
}

type ZipEntry

type ZipEntry struct {
	*zip.FileHeader
	Body []byte
}

ZipEntry represents an entry in a zip archive. TODO: Move to archivetest.

func (ZipEntry) WriteTo

func (e ZipEntry) WriteTo(zw *zip.Writer) error

WriteTo writes the ZipEntry to a zip writer.

type ZipEntryStabilizer

type ZipEntryStabilizer struct {
	Name string
	Func func(*MutableZipFile)
}