sar

README

go-sar

Go simple archive handling

This library currently supports creating gzipped tar archives from the filesystem. It uses the excellent pgzip library for parallel compression.

Examples:

h, _ := os.OpenFile("test.tar.gz", os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0644)
a := sar.NewTarGz(h)
defer a.Close()
if err := a.ArchivePath("/some/file/or/folder"); err != nil {
  log.Fatal(err)
}

Limit the archive size to 10 MiB and the size of the data read to 200 MiB:

h, _ := os.OpenFile("test.tar.gz", os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0644)
a := sar.NewTarGz(h).LimitArchive(10*1024*1024).LimitData(200*1024*1024)
defer a.Close()
if err := a.ArchivePath("/some/file/or/folder"); err != nil {
  log.Fatal(err)
}

Documentation

Index

• type Archive
  • func NewTar() *Archive
  • func NewTarGz() *Archive
  • func (a *Archive) AddEntry(path, name string, info os.FileInfo) error
  • func (a *Archive) ArchivePath(paths ...string) error
  • func (a *Archive) Close() error
  • func (a *Archive) Extract(base string, opts *ExtractOptions) error
  • func (a *Archive) LimitArchive(limit int64) *Archive
  • func (a *Archive) LimitData(limit int64) *Archive
  • func (a *Archive) SetupReader() error
  • func (a *Archive) SetupWriter() error
  • func (a *Archive) WithReader(r io.Reader) *Archive
  • func (a *Archive) WithWriter(w io.Writer) *Archive
• type Compressor
• type ExtractOptions
  • func NewExtractOptions() *ExtractOptions
  • func (o *ExtractOptions) Apply(path string, h *tar.Header) error
• type ExtractionAbortedError
  • func (e ExtractionAbortedError) Error() string
• type LimitWriter
  • func NewLimitWriter(w io.Writer, limit int64) *LimitWriter
  • func (w *LimitWriter) Write(p []byte) (int, error)
• type ReadLimitExceeded
  • func (ReadLimitExceeded) Error() string
• type Type
• type WriteLimitExceeded
  • func (WriteLimitExceeded) Error() string

Types

type Archive

type Archive struct {
	Type       Type       // Type specifies the archive type.
	Compressor Compressor // Compressor specifies the compressor to use.
	Writer     io.Writer  // Writer provides sequential writing of an archive.
	Reader     io.Reader  // Reader provides sequential reading of an archive.
	ReadLimit  int64      // ReadLimit allows to limit the data read.
	WriteLimit int64      // WriteLimit allows to limit the data written, i.e., the archive size.
	// contains filtered or unexported fields
}

Archive provides access to an archive.

func NewTar

func NewTar() *Archive

NewTar returns a pointer to a new Tar archive structure.

func NewTarGz

func NewTarGz() *Archive

NewTarGz returns a pointer to a new Tar+Gzip archive structure.

func (*Archive) AddEntry

func (a *Archive) AddEntry(path, name string, info os.FileInfo) error

AddEntry adds a new file system entry to the archive.

func (*Archive) ArchivePath

func (a *Archive) ArchivePath(paths ...string) error

ArchivePath archives the given path.

func (*Archive) Close

func (a *Archive) Close() error

Close closes all ressources used by the archive.

func (*Archive) Extract

func (a *Archive) Extract(base string, opts *ExtractOptions) error

Extract extracts an archive to a given path according to the given rules.

func (*Archive) LimitArchive

func (a *Archive) LimitArchive(limit int64) *Archive

LimitArchive sets the maximum size an archive may grow to.

func (*Archive) LimitData

func (a *Archive) LimitData(limit int64) *Archive

LimitData limits the maximum size of the data to be archived.

func (*Archive) SetupReader

func (a *Archive) SetupReader() error

SetupReader initializes resources used needed for reading an archive.

func (*Archive) SetupWriter

func (a *Archive) SetupWriter() error

SetupWriter initializes resources needed for creating an archive.

func (*Archive) WithReader

func (a *Archive) WithReader(r io.Reader) *Archive

WithWriter sets the backing reader.

func (*Archive) WithWriter

func (a *Archive) WithWriter(w io.Writer) *Archive

WithWriter sets the backing writer.

type Compressor

type Compressor int

Compressor represents the compression type.

const (
	CompressorNone Compressor = iota // CompressNone disables compression.
	CompressorGzip                   // CompressGzip represents the Gzip compressor.
)

Constants to identify compression type.

type ExtractOptions

type ExtractOptions struct {
	Verbose           bool
	Overwrite         bool
	Interactive       bool
	RestoreOwner      bool
	RestoreTimestamps bool
	FailOnError       bool
	ShowErrors        bool
	Stdout            io.Writer
	Stderr            io.Writer
	Errors            []error
}

ExtractOptions specifies how an archive is to be extracted.

func NewExtractOptions

func NewExtractOptions() *ExtractOptions

NewExtractOptions returns an pointer to an ExtractOptions structure initialized with defaults values.

func (*ExtractOptions) Apply

func (o *ExtractOptions) Apply(path string, h *tar.Header) error

Apply set metadata on a path according to configured rules.

type ExtractionAbortedError

type ExtractionAbortedError struct{}

func (ExtractionAbortedError) Error

func (e ExtractionAbortedError) Error() string

type LimitWriter

type LimitWriter struct {
	Writer io.Writer
	Limit  int64
	// contains filtered or unexported fields
}

LimitWriter wraps a Writer and returns an error if the written data exceeds a given limit.

func NewLimitWriter

func NewLimitWriter(w io.Writer, limit int64) *LimitWriter

NewLimitWriter returns a pointer to a new LimitWriter wrapping a Writer and limiting written data to the given size.

func (*LimitWriter) Write

func (w *LimitWriter) Write(p []byte) (int, error)

Write writes the data to the underlying writer or returns an error if the size would exceed a set limit.

type ReadLimitExceeded

type ReadLimitExceeded struct{}

ReadLimitExceeded is an error object returned when a read would exceed a set limit.

func (ReadLimitExceeded) Error

func (ReadLimitExceeded) Error() string

type Type

type Type int

Type represents the archive type.

const (
	// TypeTar represents the Tar archive type.
	TypeTar Type = 1 + iota
)

Constants to identify various archive types.

type WriteLimitExceeded

type WriteLimitExceeded struct{}

WriteLimitExceeded is an error object returned when a write would exceed a set limit.

func (WriteLimitExceeded) Error

func (WriteLimitExceeded) Error() string