sevenzip

package module
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 4, 2026 License: BSD-3-Clause Imports: 8 Imported by: 0

README

go-filesystems/sevenzip

sevenzip

Go Reference CI

Writes 7z archives — pure Go, CGO_ENABLED=0, builds for every target Go builds for.

z, err := sevenzip.NewWriter(f)              // f is an io.WriteSeeker
z.AddDir("docs", 0o755)
z.AddFile("docs/notes.txt", 0o644, size, r)
z.Close()                                     // the header is written here

Writing, not reading

This package writes. For reading, github.com/bodgit/sevenzip already does it well and go-filesystems/unarchive uses it. What did not exist was a pure-Go writer, and overlay.Builder needed one:

var _ overlay.Builder = (*sevenzip.Writer)(nil)

AddDir and AddFile are that interface, so an overlay over any read-only filesystem can be sealed into a .7z.

It needs an io.WriteSeeker, and that is the format

The archive begins with a header carrying the position, size and CRC of the header at the end — none of which is known until the end. The alternative is holding every byte in memory to count them first, which for the files people put in archives is not an alternative. So the first thirty-two bytes are reserved and written last.

Two methods

Store keeps the bytes as they are. Every reader takes it, it costs nothing to write, and an entry can be read without decoding anything
LZMA2 what 7-Zip writes by default, and what the name of the format means to most people

WithMethod and WithDictionary choose; Store is the default.

⛔ An empty entry must not write a stream

An entry with no bytes used to get an LZMA2 stream anyway — and an LZMA2 stream with nothing in it is still one byte: its end marker. That orphan byte sat in the packed data that no entry claimed, so every stream after it was read one byte out, and the archive was corrupt from the first empty file onward.

Store hid it completely: storing nothing writes nothing, so the whole test suite passed on the default method. The witness that was missing was the same tests run over both methods, and it is what the suite does now.

The fix is that the coder is created by the first Write, not when the entry is opened — so an entry nobody writes to has no stream at all.

Directories and empty files are two bit vectors, not one

7z records them with kEmptyStream over every entry and kEmptyFile over only the ones that vector marked — MSB-first, padded to a byte. A reader that treats the second as parallel to the first sees directories where files are.

The POSIX mode travels in kWinAttributes, in the high sixteen bits behind flag 0x8000. os.ModeDir is 1 << 31, so narrowing an fs.FileMode into sixteen bits drops every type bit: the constants written are S_IFDIR 0o040000, S_IFREG 0o100000 and S_IFLNK 0o120000.

Judged by 7-Zip

Every archive the tests write is handed to 7zz t and 7zz l -slt, and the entries are extracted and compared on disk. Exit status is never the assertion on its own.

Licence

BSD-3-Clause.

Documentation

Overview

Package sevenzip reads and WRITES the 7z archive format.

Reading goes through github.com/bodgit/sevenzip, which is pure Go and maintained: a second decoder would duplicate LZMA, LZMA2, bzip2, deflate, brotli, lz4, PPMd and the BCJ filters, all of which already work there.

Writing is here because nothing pure-Go writes 7z. The compression half was already available -- github.com/ulikunitz/xz/lzma encodes LZMA2 -- so what this package adds is the container: the signature header, the packed streams, and the structured header that describes them.

Index

Constants

This section is empty.

Variables

View Source
var ErrClosed = errors.New("sevenzip: writer is closed")

ErrClosed is returned by a Writer that has already been closed.

View Source
var ErrEntryOpen = errors.New("sevenzip: the previous entry is still open")

ErrEntryOpen is returned when a second entry is started before the first is finished. Entries are written one after another because their bytes are written one after another: there is nowhere to put a second stream while the first is still arriving.

View Source
var ErrUnknownMethod = errors.New("sevenzip: unknown method")

ErrUnknownMethod is returned for a Method this writer does not have.

Functions

This section is empty.

Types

type Method

type Method int

Method is how an entry's bytes are stored.

const (
	// Store keeps the bytes as they are. Every reader takes it, it costs
	// nothing to write, and an entry can be read without decoding anything.
	Store Method = iota
	// LZMA2 compresses. It is what 7-Zip writes by default and what the name
	// of the format means to most people.
	LZMA2
)

type Option

type Option func(*config)

Option settles how a Writer stores what it is given.

func WithDictionary

func WithDictionary(bytes int) Option

WithDictionary asks for an LZMA2 dictionary of at least this many bytes.

At least, because the format names sizes from a fixed sequence rather than carrying a number: the smallest one big enough is used, and it is that size the stream is encoded with. Asking for something the sequence cannot name and being given the next one up is the format's arithmetic, not a rounding this package chose.

func WithMethod

func WithMethod(m Method) Option

WithMethod chooses how entries are stored. The default is Store.

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer builds a 7z archive.

It needs an io.WriteSeeker, and that is the format's doing rather than a convenience: the archive begins with a header that carries the POSITION, size and CRC of the header at the end, none of which is known until the end. The alternative is holding every byte in memory to count them first, which for the files people put in archives is not an alternative. So the first thirty-two bytes are reserved, the data is streamed straight through, and the beginning is filled in last.

What this writes

Stored entries, one folder each, and an uncompressed header. That is a complete and valid archive -- every reader takes it -- and it is deliberately the smallest thing that can be verified against the reference implementation before compression is added on top. A folder per entry also means an entry can be read without decoding any other, which is what a solid archive gives up.

func NewWriter

func NewWriter(w io.WriteSeeker, opts ...Option) (*Writer, error)

NewWriter reserves the signature header and returns a Writer ready for its first entry.

func (*Writer) AddDir

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

AddDir records a directory. No stream is written for it, and its mode is kept in the attribute word.

func (*Writer) AddFile

func (z *Writer) AddFile(name string, perm fs.FileMode, _ int64, src io.Reader) error

AddFile records a file of size bytes and copies them in.

AddDir and AddFile together are the shape a deferred write layer seals through, so that the thing rewriting an archive at the end does not have to know which format it is rewriting.

The size is accepted and NOT used, and that is the format's doing rather than an oversight: 7z records an entry's unpacked length in a header written at the END, so this writer counts the bytes as they go by and already knows. tar cannot do that -- its length goes in a header BEFORE its data -- so the contract carries the size for tar's sake, and a format that does not need it ignores it.

It is deliberately not checked against what arrives, either. The counted length is the truth this archive will be read by, so trusting the count over the claim is what keeps the archive consistent with itself; a caller whose claim was wrong gets an archive that is right.

func (*Writer) Close

func (z *Writer) Close() error

Close writes the header and the signature header, in that order, and the archive is complete when it returns.

func (*Writer) Create

func (z *Writer) Create(name string) (io.Writer, error)

Create starts an entry and returns the writer its contents go to.

The name is the path inside the archive, with '/' separators. Writing to the returned writer is what puts bytes in the archive; the entry ends when the next Create or Close is called.

Jump to

Keyboard shortcuts

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