Documentation
¶
Overview ¶
Package rar reads a RAR archive as a filesystem.Filesystem, and writes one holding stored entries.
It decodes through github.com/nwaples/rardecode/v2, which is pure Go and maintained; this package is the go-filesystems shape around it -- the Filesystem/Opener contract, the volume resolver, and an extraction that can say whether an entry came out whole. NewWriter is the other direction, and owes that library nothing: it writes the container itself.
Reading: multi-volume ¶
A RAR set may be split across files, and the format finds the next one BY NAME -- part1 asks for part2. Any text a downloader or a tidy-up has added to those names breaks the chain, and what happens then is worse than an error: some readers pad the missing remainder with zeros and report success, so the file is the right LENGTH and the wrong content. Volumes resolves the chain by volume NUMBER within a directory instead, so a set survives names like "film.part2 [49736858].rar" without anything being renamed or linked.
OpenReader takes a single io.ReaderAt, which is the shape github.com/go-filesystems/detect opens every driver with; it can therefore only serve a single-volume archive, and says so. Open takes a path and resolves the whole set.
Reading: an archive is read-only ¶
An archive opened for reading is read-only: every mutating method of filesystem.Filesystem (WriteFile, MkDir, DeleteFile, DeleteDir, Rename) returns ErrReadOnly, as in the other read-only drivers of this org. Writing an archive means building a new one with NewWriter, which is what github.com/go-filesystems/overlay seals into.
Writing: the stored method, and why there is no other ¶
NewWriter writes RAR 5 archives whose entries are STORED -- held byte-for-byte, uncompressed. It writes no compressed entry, and this is not a feature that has not been got to yet. It is the boundary of what may lawfully be written at all.
RAR's compression is proprietary and its algorithms are unpublished. The only full description of them is UnRAR's source, whose licence permits reading RAR archives and forbids the one use that would be needed here. Clause 2, in full:
UnRAR source code may be used in any software to handle RAR archives without limitations free of charge, but cannot be used to develop RAR (WinRAR) compatible archiver and to re-create RAR compression algorithm, which is proprietary.
A compressing RAR writer is exactly the "RAR compatible archiver" that clause forecloses, and the algorithm is not available from anywhere else to write one independently. So there is nothing to implement later: an entry this package cannot store uncompressed is an entry it cannot write.
What IS published is the container. RARLAB's "RAR 5.0 archive format" technote (https://www.rarlab.com/technote.htm) documents the block headers, the variable-length integers, the CRCs, the flags and the volume linkage -- and the stored method needs the container and nothing else, which is why an independent writer of it is possible at all.
What this package was built from ¶
The writer was built from that published technote, and checked against two independent readers that accept what it produces: github.com/nwaples/rardecode/v2 and 7-Zip's 7zz.
No UnRAR-derived source was read, consulted, ported or translated. That includes 7-Zip's own RAR sources (CPP/7zip/Compress/Rar*), which 7-Zip distributes under "GNU LGPL with unRAR license restriction" and which are therefore the same code under another cover. 7zz is used here only as a program, run on a finished archive to see whether it agrees -- which is the use its licence and UnRAR's both allow, and the only one this package makes of it.
rardecode was read, for the container layout it already parses. It carries no UnRAR-derived code: it is BSD-licensed original work by Nicholas Waples, and a search of its source for any mention of UnRAR or Roshal finds nothing.
Index ¶
- Variables
- func OpenReader(r io.ReaderAt, size int64, opts ...Option) (filesystem.Filesystem, error)
- type FS
- func (f *FS) Close() error
- func (f *FS) DeleteDir(string) error
- func (f *FS) DeleteFile(string) error
- func (f *FS) ListDir(p string) ([]filesystem.DirEntry, error)
- func (f *FS) MkDir(string, os.FileMode) error
- func (f *FS) OpenFile(p string) (filesystem.File, error)
- func (f *FS) ReadFile(p string) ([]byte, error)
- func (f *FS) ReadLink(p string) (string, error)
- func (f *FS) Rename(string, string) error
- func (f *FS) Stat(p string) (filesystem.Stat, error)
- func (f *FS) VolumeSet() *Volumes
- func (f *FS) WriteFile(string, []byte, os.FileMode) error
- type Option
- type Volumes
- type Writer
Constants ¶
This section is empty.
Variables ¶
var ( // ErrReadOnly is returned by every mutating method (WriteFile, MkDir, // DeleteFile, DeleteDir, Rename). An archive is a read-only format. ErrReadOnly = errors.New("rar: archive is read-only") // ErrNotFound is returned when a path is not in the archive. ErrNotFound = fmt.Errorf("rar: path not found: %w", iofs.ErrNotExist) // ErrNotDirectory is returned when ListDir targets a non-directory. ErrNotDirectory = errors.New("rar: not a directory") // ErrNotRegular is returned when ReadFile targets a non-regular file. ErrNotRegular = errors.New("rar: not a regular file") // ErrNotSymlink is returned by ReadLink when the target is not a symlink. ErrNotSymlink = errors.New("rar: not a symbolic link") // ErrShort is returned when an entry yields fewer bytes than its header // declares. // // It exists because the alternative is what this package was written // against: a reader that meets the end of the volume chain, pads the // remainder with zeros and reports success. The file is then exactly the // declared length and its tail is nothing, which no size check can see -- // and for a container that keeps its index at the end, such as MP4, the // result opens nowhere. ErrShort = errors.New("rar: entry ended before its declared size") // ErrVolumeMissing is returned when the chain asks for a volume the // directory does not hold. ErrVolumeMissing = errors.New("rar: a volume of this set is missing") // ErrWriterClosed is returned by a Writer that has already been closed. ErrWriterClosed = errors.New("rar: writer is closed") // ErrBadName is returned for an entry name the archive cannot carry // unchanged: absolute, climbing out of the archive, or holding a character a // RAR reader would read as something else. See the Writer. ErrBadName = errors.New("rar: an entry name the archive cannot carry") // ErrSizeMismatch is returned when the reader handed to AddFile delivers a // different number of bytes than the size it was called with. // // The size is in the header before the bytes are read, so a mismatch cannot // be absorbed: it has to fail at the call that made the promise, while the // entry still has a name to report, rather than become an archive whose // header disagrees with its data. ErrSizeMismatch = errors.New("rar: the entry did not deliver the size it declared") )
Sentinel errors. Compare with errors.Is so wrapped errors continue to match.
Functions ¶
func OpenReader ¶
func OpenReader(r io.ReaderAt, size int64, opts ...Option) (filesystem.Filesystem, error)
OpenReader reads a SINGLE-VOLUME archive from r, and is the shape every driver in go-filesystems answers to so github.com/go-filesystems/detect can open them all through one function type.
A multi-volume set cannot be opened this way and nothing pretends otherwise: one io.ReaderAt is one file, and the rest of the set is in other files that only a name or a path can reach. Such an archive reports ErrVolumeMissing from the first entry that continues past this volume -- which is better than the alternative this package exists to prevent, where the remainder is padded with zeros and called a success. Use Open for a set.
Types ¶
type FS ¶
type FS struct {
// contains filtered or unexported fields
}
FS reads a RAR archive as a filesystem.
⛔ Random access costs what the format costs. A RAR entry is a STREAM: to reach byte n the decoder must produce the n bytes before it, and in a SOLID archive it must start from the beginning of the compression block, which may be an earlier file. A handle therefore keeps its decoder and its position: reading forwards is linear overall, reading BACKWARDS starts a fresh pass. Sequential use is what this is good at; a caller seeking about in a large entry is paying for the archive's own shape, not for this code.
func Open ¶
Open reads the archive at name, resolving the whole volume set it belongs to.
The set is found by volume NUMBER within name's directory (see Volumes), so files carrying anything extra in their names -- an id a downloader inserted, a "(1)" a copy left behind -- are still reached, and nothing is renamed.
func (*FS) DeleteFile ¶
func (*FS) ListDir ¶
func (f *FS) ListDir(p string) ([]filesystem.DirEntry, error)
ListDir names what is directly inside p.
func (*FS) OpenFile ¶
func (f *FS) OpenFile(p string) (filesystem.File, error)
OpenFile hands back a handle on one entry.
func (*FS) ReadFile ¶
ReadFile returns the whole entry.
It is the contract's method and it holds the entry in memory, which for a video inside an archive is the whole video. Use OpenFile for anything whose size you did not choose.
func (*FS) Stat ¶
func (f *FS) Stat(p string) (filesystem.Stat, error)
Stat reports what the archive recorded about p.
type Volumes ¶
type Volumes struct {
// contains filtered or unexported fields
}
Volumes is the set of files one multi-volume archive is split across, keyed by volume number.
It answers fs.FS so it can be handed straight to the decoder, which asks for volumes BY NAME -- and the names it asks for are the canonical ones the archive was made with, not the ones the files ended up carrying. Every request is answered by the NUMBER in the requested name, so the real files keep whatever they are called.
func FindVolumes ¶
FindVolumes collects the volume set that first belongs to, by looking in its directory for files with the same stem and a volume number.
Only the stem decides membership, so a directory holding three different multi-volume sets -- which is an ordinary thing for a downloaded album -- resolves each of them separately instead of mixing them.
func (*Volumes) First ¶
First is the name the decoder should be given as the archive to open. It is a canonical name, not a real one: the set answers by number.
func (*Volumes) Numbers ¶
Numbers are the volume numbers found, in order, so a caller can see a hole rather than discover it halfway through an extraction.
func (*Volumes) Open ¶
Open answers the decoder's request for a volume.
The name is read for its number and nothing else. A request this set cannot answer returns ErrVolumeMissing rather than a bare not-exist, because the two mean different things to somebody looking at a half-extracted file: one is a set with a hole in it, the other is a wrong path.
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer builds a RAR 5 archive holding stored entries.
It needs an io.WriteSeeker, and that is the format's doing rather than a convenience. A file header carries a CRC32 of the entry's UNPACKED data, and the header is written before that data is read; the alternatives are to hold every entry in memory to checksum it first, or to leave the checksum out. The second is not the small compromise it looks like: with no checksum in the header there is nothing in a stored entry for a reader to verify, and `7zz t` answers "Everything is Ok" for an archive whose bytes have been altered. So the header goes out with the field zeroed, the data streams past a running CRC, and the header is written again in place -- it is the same length either way, because only a fixed four-byte field changed.
Entries carry no timestamp. The Builder contract this shape answers to does not offer one, and a time this package invented would be a fact about when it ran rather than about the file; leaving the field out also makes the same input produce the same bytes.
Stored only ¶
See the package documentation: RAR's compression is proprietary and unpublished, so the stored method is not a first step towards the others. It is the whole of what can be written from a published specification.
func NewWriter ¶
func NewWriter(w io.WriteSeeker) *Writer
NewWriter returns a Writer that builds an archive in w.
Nothing is written until the first entry or Close: an archive with no entries is still a valid archive, and Close writes one.
func (*Writer) AddDir ¶
AddDir records a directory, which in this format is a file entry with the directory flag, no data, and no data size.
func (*Writer) AddFile ¶
AddFile records a file of exactly size bytes and copies them from r.
The size is the caller's: it goes in the header, before the bytes, and cannot be discovered without reading the whole entry first. A reader that delivers some other number of bytes is refused here, naming the entry and the size it was promised, because the alternative is an archive whose header disagrees with its data -- which every reader reports as corruption of the file, with nothing to say who wrote it.