rar

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 26, 2026 License: BSD-3-Clause Imports: 16 Imported by: 2

README

go-filesystems/rar

rar

Go Reference CI

Pure-Go access to RAR archives — no CGO, no external tools. Reading exposes an archive through the shared github.com/go-filesystems/interface Filesystem API, including multi-volume sets whose files carry extra text in their names. Writing produces RAR 5 archives holding stored entries.

Decoding goes through github.com/nwaples/rardecode/v2. The writer is this package's own, built from RARLAB's published container specification.

Support summary

Feature Status Notes
Open / Close ✅ Open resolves a whole volume set; OpenReader takes one io.ReaderAt
ReadFile ✅ Holds the entry in memory; use OpenFile for anything whose size you did not choose
Read at an offset ✅ (*FS).OpenFile(path) → io.ReaderAt + Size(); forwards is linear, backwards restarts the pass (the format's cost, not this code's)
ListDir / Stat ✅ Directories the archive never named are synthesised from the paths inside them
ReadLink ✅ For entries the archive recorded a link target for
Short entry detected ✅ ErrShort rather than a shorter count, so a zero-padded remainder cannot pass for a whole file
Multi-volume ✅ Resolved by volume number within a directory, so film.part2 [49736858].rar still chains
Encrypted archives ✅ Password(...), passed through to the decoder
Mutate an opened archive ❌ Read-only: every filesystem.Filesystem mutator returns ErrReadOnly
Write: stored entries ✅ NewWriter / AddDir / AddFile / Close; RAR 5 container, method 0
Write: compressed entries ⛔ Not possible to implement lawfully — see below. Not a missing feature
Write: RAR 4 ❌ RAR 5 only
Write: multi-volume, encryption, solid ❌ Single volume, no encryption, no solid blocks

Why there is no compressed writer

RAR's compression is proprietary and unpublished. The only full description of the algorithms is UnRAR's source, and its licence permits reading RAR archives while forbidding precisely the use a compressing writer would need — 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 the "RAR compatible archiver" that clause forecloses, and the algorithm is available from nowhere else. So there is nothing here to finish later: an entry this package cannot store uncompressed is an entry it cannot write at all.

What is published is the container. RARLAB's "RAR 5.0 archive format" technote 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 the whole reason an independent writer is possible.

No UnRAR-derived source was read, consulted, ported or translated in writing this package. 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 over finished archives in the tests to see whether it agrees.

Module

github.com/go-filesystems/rar

Usage

Reading
fs, err := rar.Open("film.part1.rar")
if err != nil { /* ... */ }
defer fs.Close()

entries, err := fs.ListDir(".")
data, err := fs.ReadFile("film.mkv")
Writing
f, err := os.Create("out.rar")
if err != nil { /* ... */ }
defer f.Close()

z := rar.NewWriter(f)
if err := z.AddDir("docs", 0o755); err != nil { /* ... */ }
if err := z.AddFile("docs/notes.txt", 0o644, int64(len(body)), bytes.NewReader(body)); err != nil { /* ... */ }
if err := z.Close(); err != nil { /* ... */ }

AddDir/AddFile are github.com/go-filesystems/overlay's Builder, so an overlay seals straight into one.

Why the writer needs an io.WriteSeeker

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 — and the second is not the small compromise it looks like. With no checksum in a stored entry's header there is nothing for a reader to verify: 7zz t answers "Everything is Ok" for an archive whose bytes have been altered under it. (That is measured, not assumed — TestAblationTheDataChecksum.)

So the header goes out with the field zeroed, the data streams past a running CRC, and the header is rewritten in place. It is the same length either way, because only a fixed four-byte field changed.

Entries carry no timestamp: the Builder contract offers none, 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.

How the writer is tested

Two independent readers judge every archive, and both are shown to be capable of refusing one:

  • github.com/nwaples/rardecode/v2 reads every entry back and its bytes are compared per entry.
  • 7zz extracts every entry and the extracted bytes are compared on disk. Its exit status is not the assertion — the contents are.

Every container decision is then ablated: the vint encoding, which fields the header CRC spans, the method bits, the data-size flag, the directory flag, the end-of-archive block, the name encoding, the data checksum. An ablation that still passes is reported as such in the test rather than removed.

References

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

Constants

This section is empty.

Variables

View Source
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

func Open(name string, opts ...Option) (*FS, error)

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) Close

func (f *FS) Close() error

Close releases nothing: each read opens and closes its own pass.

func (*FS) DeleteDir

func (f *FS) DeleteDir(string) error

func (*FS) DeleteFile

func (f *FS) DeleteFile(string) error

func (*FS) ListDir

func (f *FS) ListDir(p string) ([]filesystem.DirEntry, error)

ListDir names what is directly inside p.

func (*FS) MkDir

func (f *FS) MkDir(string, os.FileMode) error

func (*FS) OpenFile

func (f *FS) OpenFile(p string) (filesystem.File, error)

OpenFile hands back a handle on one entry.

func (*FS) ReadFile

func (f *FS) ReadFile(p string) ([]byte, error)

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 (f *FS) ReadLink(p string) (string, error)

ReadLink answers for an entry the archive recorded a link target for.

func (*FS) Rename

func (f *FS) Rename(string, string) error

func (*FS) Stat

func (f *FS) Stat(p string) (filesystem.Stat, error)

Stat reports what the archive recorded about p.

func (*FS) VolumeSet

func (f *FS) VolumeSet() *Volumes

Volumes is the volume set this archive was opened from, or nil when it was opened from a single reader. A caller can ask it what it found -- Count, Numbers -- to see a hole before an extraction runs into it.

func (*FS) WriteFile

func (f *FS) WriteFile(string, []byte, os.FileMode) error

The mutating half of filesystem.Filesystem. An archive is read-only, as in the other read-only drivers of this org.

type Option

type Option = rardecode.Option

Option is a decoder option, passed through to the underlying reader.

func Password

func Password(pass string) Option

Password supplies the passphrase for an encrypted archive.

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

func FindVolumes(first string) (*Volumes, error)

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) Asked

func (v *Volumes) Asked() []string

Asked reports the names the decoder requested, for tests and diagnosis.

func (*Volumes) Count

func (v *Volumes) Count() int

Count is how many volumes were found.

func (*Volumes) First

func (v *Volumes) First() string

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

func (v *Volumes) Numbers() []int

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

func (v *Volumes) Open(name string) (fs.File, error)

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

func (z *Writer) AddDir(name string, perm os.FileMode) error

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

func (z *Writer) AddFile(name string, perm os.FileMode, size int64, r io.Reader) error

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.

func (*Writer) Close

func (z *Writer) Close() error

Close writes the end-of-archive block.

An archive without it is one a reader meets the end of the file in, and readers differ on whether that is an error or an archive that stops. Writing it is what says the set ends here rather than continuing in another volume.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL