decompress

Documentation

Overview

Package decompress defines a pluggable decompression interface and a registry that dispatches on leading magic bytes.

Index

• Variables
• type Decompressor
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Match(head []byte) Decompressor
  • func (r *Registry) MaxMagicLen() int
  • func (r *Registry) Register(d Decompressor) error

Variables

var (
	// ErrNilDecompressor is returned when a nil Decompressor is registered.
	ErrNilDecompressor = errors.New("decompress: nil decompressor")
	// ErrNoMagic is returned when a Decompressor provides zero magic sequences.
	ErrNoMagic = errors.New("decompress: no magic sequences")
	// ErrEmptyMagic is returned when a Decompressor provides an empty byte
	// slice as one of its magic entries.
	ErrEmptyMagic = errors.New("decompress: empty magic entry")
	// ErrDuplicateMagic is returned when a magic sequence is already
	// registered by another Decompressor.
	ErrDuplicateMagic = errors.New("decompress: duplicate magic")
)

Sentinel errors returned by Register.

Types

type Decompressor

type Decompressor interface {
	// Name returns the codec name for logging and error messages.
	Name() string
	// Magic returns the byte sequences that identify this codec.
	// Each inner slice is a distinct magic prefix. At least one is required.
	// Multiple magics allow one decompressor to handle related formats
	// (e.g. different versions of the same container).
	Magic() [][]byte
	// Decompress decompresses src into dst. If dst has sufficient capacity,
	// it is reused; otherwise a new slice is allocated. The caller must not
	// mutate the returned slice.
	Decompress(dst, src []byte) ([]byte, error)
}

Decompressor decompresses bytes produced by a specific codec. Implementations must be safe for concurrent use.

To create a plugin, implement this interface and register it with a Registry:

reg := decompress.NewRegistry()
if err := reg.Register(myCodec{}); err != nil {
	// handle duplicate magic conflict
}

The Reader will automatically invoke Match on file contents and call Decompress when a magic prefix is detected.

type Registry

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

Registry dispatches Decompressors by leading-byte (magic) match. Entries are stored sorted by descending magic length so the first prefix match is also the longest. Registry is safe for concurrent use; Register acquires a write lock and Match acquires a read lock.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty registry.

func (*Registry) Match

func (r *Registry) Match(head []byte) Decompressor

Match returns the Decompressor whose magic prefix matches head, or nil. When multiple decompressors share a common prefix, the longest match wins.

func (*Registry) MaxMagicLen

func (r *Registry) MaxMagicLen() int

MaxMagicLen returns the length of the longest registered magic sequence. Callers can use this to size a head buffer: only the first MaxMagicLen bytes of a file need to be inspected for magic matching.

func (*Registry) Register

func (r *Registry) Register(d Decompressor) error

Register adds d to the registry. Returns an error if d is nil, provides zero magic sequences, includes an empty magic entry, or conflicts with an already-registered decompressor. Entries are re-sorted by descending magic length after insertion.