Documentation
¶
Overview ¶
Package unarchive opens an archive without being told what it is, and extracts it while checking that what came out is what the archive promised.
Why the bytes and not the name ¶
A format is recognised by what is IN the file. An extension is a claim by whoever last renamed it: a .rar that is really a zip, a video saved as .mp4 that is an MPEG transport stream, a volume renamed by a download manager -- all ordinary, and all wrong if the name decides.
Why the check ¶
An extractor that reports success is not the same as an extractor that got everything. libarchive, which is bsdtar and therefore macOS, does not follow a multi-volume RAR chain: it writes the first volume, pads the remainder with ZEROS to the declared length and exits 0. The result is exactly the right SIZE, which is what every check afterwards looks at. This package compares what was written against what the header declared, per entry, and says so when they differ.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrCannotWrite = errors.New("unarchive: this format is read but not written")
ErrCannotWrite is returned for a format this package reads and does not write.
A third sentence alongside the other two: "I know what this is, I can read it, and I cannot produce one". Only RAR is left in it, and for a reason that is not going to change here: no free writer exists.
bzip2 used to be in it too, because the standard library decompresses bzip2 and nothing compressed it. That was a missing LIBRARY rather than a property of the format, so the library was written -- go-compressions/bzip2 -- and the sentence stopped being true. Worth saying, because the two reasons look identical from the outside and only one of them is permanent.
var ErrEscapes = errors.New("unarchive: entry would be written outside the destination")
ErrEscapes is returned for an entry whose path would land outside the destination.
An archive is somebody else's list of names, and "../../.ssh/authorized_keys" is a name. Every extractor that trusted it has had the same bug, so this one does not trust it: the resolved path is checked against the destination, and an entry that leaves it is refused rather than sanitised, because silently rewriting a path puts the file somewhere the person did not ask for either.
var ErrExists = errors.New("unarchive: file exists")
ErrExists is returned when a file is already there and Overwrite is not set.
var ErrIncomplete = errors.New("unarchive: entry is shorter than its header declares")
ErrIncomplete is returned when an entry yielded fewer bytes than its header declared.
It is the point of this package. An extractor that writes what it got and reports success leaves a file of exactly the right SIZE when the source was zero-padded, and every check afterwards agrees with it.
var ErrNotImplemented = errors.New("unarchive: recognised, but this format is not read yet")
ErrNotImplemented is returned for a format that is recognised and not yet read. Telling the two apart matters to somebody holding a file: "I do not know what this is" and "I know exactly what this is and cannot open it yet" send them to different places.
var ErrReadOnly = errors.New("unarchive: archive is read-only")
ErrReadOnly is returned by every mutating method of a filesystem this package builds. An archive is read-only.
var ErrTooDeeplyNested = errors.New("unarchive: more stream wrappers than this will peel")
ErrTooDeeplyNested is returned when a file is wrapped more times than maxNesting.
var ErrUnknownFormat = errors.New("unarchive: the bytes match no format this knows")
ErrUnknownFormat is returned when nothing recognises the bytes.
Functions ¶
func FromFS ¶
func FromFS(fsys iofs.FS) filesystem.Filesystem
FromFS presents any io/fs.FS as a filesystem.Filesystem.
It exists because the standard library already answers fs.FS for some of these formats -- a *zip.Reader is one -- so the driver for them is an adaptation and not a decoder. Writing a second zip reader to satisfy a different interface would be a duplicate of something already correct.
⛔ Random access costs what the underlying fs.FS charges. An fs.File is a stream: unless it also answers io.ReaderAt, reaching an offset means reading what comes before it, and reading BACKWARDS means opening the entry again. A zip entry is stored on its own, so a fresh open is cheap; an entry inside a solidly-compressed archive is not, and that is the format's shape rather than this adapter's.
func FromFSWithModes ¶
func FromFSWithModes(fsys iofs.FS, modes map[string]os.FileMode) filesystem.Filesystem
FromFSWithModes is FromFS for an archive whose own metadata records modes the io/fs view does not report.
⛔ It exists because both io/fs adapters here LOSE a directory's permissions. archive/zip answers every directory with `fs.ModeDir | 0555` from its synthesised fileListEntry, and bodgit/sevenzip does the same, whatever the archive stored -- so a 0755 directory converted to tar came out dr-xr-xr-x, and the extracted tree could not be deleted without a chmod. Measured, not guessed: tar to tar kept 0755, zip to tar and 7z to tar both lost the owner's write bit, which is what pointed at the adapters rather than at the writers.
The map is keyed by path with no trailing slash. An entry whose recorded permissions are ZERO is skipped rather than believed: some archives carry no Unix mode at all, and a mode of 0 is the absence of a statement rather than a statement that nobody may read the file.
func InnerName ¶
InnerName is what the stream inside a compressed wrapper is called: the base name with the wrapper's suffix taken off, so notes.txt.gz gives notes.txt and archive.tgz gives archive.tar.
It is exported because the command needs the same answer for a different question -- what to call the directory it extracts into -- and computing it from filepath.Ext there gives "fixture.tar" for fixture.tar.gz, which is a directory named after half a suffix.
func SealTo ¶
SealTo writes everything the overlay holds into target, once.
The format comes from target's name -- see TargetFor -- and the write is atomic: the archive is built beside target and RENAMED over it, so an interrupted seal leaves whatever was there before untouched rather than half-replaced.
Types ¶
type Entry ¶
Entry is one thing an archive holds, as List reports it.
func List ¶
func List(fsys filesystem.Filesystem) ([]Entry, error)
List names everything in fsys without writing anything.
It walks the same way Extract does -- and refuses the same names, so a person who lists before extracting is told about an entry that would leave the destination BEFORE several gigabytes land somewhere.
type Format ¶
type Format string
Format is an archive format this package can recognise.
const ( FormatUnknown Format = "" FormatRAR Format = "rar" // RAR 1.5-4.x and RAR5, single or multi-volume FormatZIP Format = "zip" // PKZIP, including the jar/epub/odf family Format7z Format = "7z" // 7-Zip FormatTar Format = "tar" // POSIX tar: v7, USTAR, PAX and GNU alike FormatGzip Format = "gzip" // a stream wrapper, usually around a tar FormatBzip2 Format = "bzip2" // likewise FormatXZ Format = "xz" // likewise FormatZstd Format = "zstd" // likewise FormatLZ4 Format = "lz4" // likewise )
func Open ¶
func Open(path string) (filesystem.Filesystem, Format, error)
Open reads the archive at path, deciding what it is from its bytes, and returns it as a filesystem together with the format it turned out to be.
A multi-volume set is followed from here: the rar driver resolves the rest of the set by volume NUMBER within path's directory, so files carrying an id a download inserted are still reached and nothing is renamed.
func Writable ¶
Writable opens an archive and returns it as a filesystem that can be CHANGED, without rewriting the archive.
Changes go into a temporary cache; the archive underneath is untouched until SealTo. So renaming one entry in a 4 GiB archive costs a rename, not 4 GiB of rewriting, and an interrupted session leaves the original exactly as it was.
The caller closes the returned Overlay, which discards the cache. Closing it does NOT write anything back: that is SealTo's job, and keeping them apart is what makes "I changed my mind" free.
func (Format) Compressed ¶
Compressed says whether a format is a stream wrapper rather than an archive of its own: gzip holds one stream, which is usually a tar and might be anything.
type Options ¶
type Options struct {
// Overwrite lets an existing file be replaced. Off by default: an
// extraction that overwrites by default destroys data on a mistyped
// destination, and the mistake is not recoverable.
Overwrite bool
// Perm is the mode for created files and directories, before umask.
// Zero means 0o644 for files and 0o755 for directories.
Perm os.FileMode
// Progress, when set, is told each entry as it completes.
Progress func(name string, bytes int64)
}
Options tune an extraction.
type Result ¶
Result is what an extraction did.
func Extract ¶
func Extract(fsys filesystem.Filesystem, dest string, opt Options) (*Result, error)
Extract writes everything in fsys under dest.
Each file is compared against the size its header declared, and a shortfall is an error rather than a smaller number -- see ErrIncomplete.
type WriteTarget ¶
type WriteTarget struct {
Archive Format // FormatTar, FormatZIP or Format7z
Wrapper Format // FormatUnknown, or one of the stream formats
}
WriteTarget is what a target name resolves to: an archive format, and an optional stream wrapper around it.
func TargetFor ¶
func TargetFor(name string) (WriteTarget, error)
TargetFor says what to write into a file with this name.
⛔ This is the one place in the package where the NAME decides, and it has to: an output file has no bytes yet to read. Everywhere else a format comes from the content, because an extension is a claim by whoever last renamed the file; here the extension is the only statement of intent there is.
func (WriteTarget) String ¶
func (t WriteTarget) String() string
String names the pair the way a file name spells it.