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
- func WriteManifest(w io.Writer, m *Manifest) error
- type ContentSummary
- type CustomStabilizerConfig
- type CustomStabilizerConfigOneOf
- type CustomStabilizerEntry
- type ExcludePath
- type ExtractOptions
- type Format
- type GzipStabilizer
- type Manifest
- type MutableGzipHeader
- type MutableZipFile
- type MutableZipReader
- type ReplacePattern
- type Section
- type StabilizeOpts
- type Stabilizer
- type TarArchive
- type TarArchiveStabilizer
- type TarEntry
- type TarEntryStabilizer
- type ZipArchiveStabilizer
- type ZipEntry
- type ZipEntryStabilizer
Constants ¶
This section is empty.
Variables ¶
var AllGzipStabilizers = []Stabilizer{ StableGzipCompression, StableGzipName, StableGzipTime, StableGzipMisc, }
var AllJarStabilizers = []Stabilizer{ StableJARBuildMetadata, StableJAROrderOfAttributeValues, StableGitProperties, }
var AllStabilizers = slices.Concat(AllZipStabilizers, AllTarStabilizers, AllGzipStabilizers, AllJarStabilizers)
var AllTarStabilizers = []Stabilizer{ StableTarFileOrder, StableTarTime, StableTarFileMode, StableTarOwners, StableTarXattrs, StableTarDeviceNumber, }
var AllZipStabilizers = []Stabilizer{ StableZipFileOrder, StableZipModifiedTime, StableZipCompression, StableZipDataDescriptor, StableZipFileEncoding, StableZipFileMode, StableZipMisc, }
var StableGitProperties = ZipEntryStabilizer{ Name: "jar-git-properties", Func: func(zf *MutableZipFile) { if path.Base(zf.Name) == "git.json" { zf.SetContent([]byte("{}")) } if path.Base(zf.Name) == "git.properties" { zf.SetContent([]byte{}) } }, }
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 StableJARBuildMetadata = ZipEntryStabilizer{ Name: "jar-build-metadata", Func: func(zf *MutableZipFile) { if !strings.HasSuffix(zf.Name, "META-INF/MANIFEST.MF") { return } r, err := zf.Open() if err != nil { return } manifest, err := ParseManifest(r) if err != nil { return } for _, attr := range []string{ "Archiver-Version", "Bnd-LastModified", "Build-Date", "Build-Date-UTC", "Build-Host", "Build-Id", "Build-Java-Version", "Build-Jdk", "Build-Jdk-Spec", "Build-Job", "Build-Number", "Build-OS", "Build-Status", "Build-Time", "Build-Timestamp", "Build-Tool", "Build-Url", "Built-By", "Built-Date", "Built-Host", "Built-JDK", "Built-On", "Built-OS", "Built-Status", "Created-By", "DSTAMP", "Eclipse-SourceReferences", "Git-Commit-Id-Describe", "Git-Remote-Origin-Url", "Git-SHA", "Git-Descriptor", "git-describe", "git-tags", "hash", "Hudson-Build-Number", "Implementation-Build-Date", "Implementation-Build-Java-Vendor", "Implementation-Build-Java-Version", "Implementation-Build", "Ion-Java-Build-Time", "Java-Vendor", "Java-Version", "JCabi-Date", "Jenkins-Build-Number", "Maven-Version", "Module-Origin", "Originally-Created-By", "Os-Arch", "Os-Name", "Os-Version", "SCM-Git-Branch", "SCM-Git-Commit-Dirty", "SCM-Git-Commit-ID", "SCM-Git-Commit-Abbrev", "SCM-Git-Commit-Description", "SCM-Git-Commit-Timestamp", "SCM-Revision", "SHA-256-Digest", "Source-Date-Epoch", "Sunset-BuiltOn", "TODAY", "Tool", "TSTAMP", "url", } { manifest.MainSection.Delete(attr) } buf := bytes.NewBuffer(nil) if err := WriteManifest(buf, manifest); err != nil { return } zf.SetContent(buf.Bytes()) }, }
var StableJAROrderOfAttributeValues = ZipEntryStabilizer{ Name: "jar-attribute-value-order", Func: func(zf *MutableZipFile) { if !strings.HasSuffix(zf.Name, "META-INF/MANIFEST.MF") { return } r, err := zf.Open() if err != nil { return } manifest, err := ParseManifest(r) if err != nil { return } for _, attr := range []string{ "Export-Package", "Include-Resource", "Provide-Capability", "Private-Package", } { value, _ := manifest.MainSection.Get(attr) if value == "" { continue } subvalues := splitPreservingQuotes(value, ',') sort.Strings(subvalues) for i, subvalue := range subvalues { subvalueArray := splitPreservingQuotes(subvalue, ';') sort.Strings(subvalueArray) subvalues[i] = strings.Join(subvalueArray, ";") } manifest.MainSection.Set(attr, strings.Join(subvalues, ",")) } buf := bytes.NewBuffer(nil) if err := WriteManifest(buf, manifest); err != nil { return } zf.SetContent(buf.Bytes()) }, }
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 ¶
Stabilize selects and applies the default stabilization routine for the given archive format.
func StabilizeTar ¶
StabilizeTar strips volatile metadata and re-writes the provided archive in a standard form.
func StabilizeWithOpts ¶
StabilizeWithOpts selects and applies the provided stabilization routine for the given archive format.
func StabilizeZip ¶
StabilizeZip strips volatile metadata and rewrites the provided archive in a standard form.
Types ¶
type ContentSummary ¶
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 CustomStabilizerConfig ¶
type CustomStabilizerConfig interface { Stabilizer(name string, format Format) (Stabilizer, error) Validate() error }
CustomStabilizerConfig defines a custom stabilizer that can be materialized for many formats
type CustomStabilizerConfigOneOf ¶
type CustomStabilizerConfigOneOf struct { ReplacePattern *ReplacePattern `yaml:"replace_pattern"` ExcludePath *ExcludePath `yaml:"exclude_path"` }
CustomStabilizerConfigOneOf aggregates known implementations of CustomStabilizerConfig
func (*CustomStabilizerConfigOneOf) CustomStabilizerConfig ¶
func (cfg *CustomStabilizerConfigOneOf) CustomStabilizerConfig() CustomStabilizerConfig
func (*CustomStabilizerConfigOneOf) Validate ¶
func (cfg *CustomStabilizerConfigOneOf) Validate() error
type CustomStabilizerEntry ¶
type CustomStabilizerEntry struct { Config CustomStabilizerConfigOneOf `yaml:",inline"` Reason string `yaml:"reason"` }
CustomStabilizerEntry defines a custom Stabilizer
func (CustomStabilizerEntry) Validate ¶
func (ent CustomStabilizerEntry) Validate() error
type ExcludePath ¶
type ExcludePath struct {
Paths []string `yaml:"paths"`
}
ExcludePath is stabilizer that removes specified path(s) from the output - Paths is a slice of path.Match-like patterns defining the archive paths to apply the exclusion.
func (*ExcludePath) Stabilizer ¶
func (ep *ExcludePath) Stabilizer(name string, format Format) (Stabilizer, error)
func (*ExcludePath) Validate ¶
func (ep *ExcludePath) Validate() error
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 GzipStabilizer ¶
type GzipStabilizer struct { Name string Func func(*MutableGzipHeader) }
func (GzipStabilizer) Stabilize ¶
func (g GzipStabilizer) Stabilize(arg any)
type Manifest ¶
type Manifest struct { MainSection *Section EntrySections []*Section OriginalContent []byte // Keep original content for modification }
Manifest represents a parsed MANIFEST.MF file
type MutableGzipHeader ¶
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) 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
type ReplacePattern ¶
type ReplacePattern struct { Paths []string `yaml:"paths"` Pattern string `yaml:"pattern"` Replace string `yaml:"replace"` }
ReplacePattern is a regex replace stabilizer applied to a specified path - Paths is a slice of path.Match-like patterns defining the archive paths to apply the exclusion. - Pattern is a regex that accepts the golang RE2 syntax. - Replace can define a substitution for the matched content.
func (*ReplacePattern) Stabilizer ¶
func (rp *ReplacePattern) Stabilizer(name string, format Format) (Stabilizer, error)
Stabilizer materializes a Stabilizer for the given config, name, and format.
func (*ReplacePattern) Validate ¶
func (rp *ReplacePattern) Validate() error
type Section ¶
type Section struct { // Names of Attributes, by default maintaining their original order of appearance Names []string // contains filtered or unexported fields }
Section represents a section in the manifest file
type StabilizeOpts ¶
type StabilizeOpts struct {
Stabilizers []Stabilizer
}
StabilizeOpts aggregates stabilizers to be used in stabilization.
type Stabilizer ¶
type Stabilizer interface {
Stabilize(any)
}
func CreateCustomStabilizers ¶
func CreateCustomStabilizers(entries []CustomStabilizerEntry, format Format) ([]Stabilizer, error)
CreateCustomStabilizers converts a set of CustomStabilizerEntry specs to Stabilizers. NOTE: This should only be called once. It generates stabilizer names using a 0-based integer counter so subsequent calls will generate identical names.
type TarArchive ¶
type TarArchive struct {
Files []*TarEntry
}
type TarArchiveStabilizer ¶
type TarArchiveStabilizer struct { Name string Func func(*TarArchive) }
func (TarArchiveStabilizer) Stabilize ¶
func (t TarArchiveStabilizer) Stabilize(arg any)
type TarEntryStabilizer ¶
func (TarEntryStabilizer) Stabilize ¶
func (t TarEntryStabilizer) Stabilize(arg any)
type ZipArchiveStabilizer ¶
type ZipArchiveStabilizer struct { Name string Func func(*MutableZipReader) }
func (ZipArchiveStabilizer) Stabilize ¶
func (z ZipArchiveStabilizer) Stabilize(arg any)
type ZipEntry ¶
type ZipEntry struct { *zip.FileHeader Body []byte }
ZipEntry represents an entry in a zip archive. TODO: Move to archivetest.
type ZipEntryStabilizer ¶
type ZipEntryStabilizer struct { Name string Func func(*MutableZipFile) }
func (ZipEntryStabilizer) Stabilize ¶
func (z ZipEntryStabilizer) Stabilize(arg any)