accessor

Documentation

Overview

Package accessor provides random access to pxar archives.

Package accessor provides random access to pxar archives.

Accessor enables O(log n) filename lookups via goodbye table binary search trees. It supports both unified (v1) and split (v2) formats, lazy metadata decoding (Minimal mode), and batch lookups for efficient prefix sharing.

# Usage

acc := accessor.NewAccessor(reader)
root, _ := acc.ReadRoot()
entry, _ := acc.Lookup("/etc/hostname")
err := acc.ListDirectory(int64(root.ContentOffset), accessor.ListOption{}, func(entry *pxar.Entry) error {
	// process entry
	return nil
})

For split archives (v2), provide a payload io.ReadSeeker as the second argument to NewAccessor. File content is then read from the payload stream when PayloadOffset > 0.

Index

• type Accessor
  • func NewAccessor(reader io.ReadSeeker, payloadReader ...io.ReadSeeker) *Accessor
  • func (a *Accessor) ListDirectory(dirOffset int64, opts ListOption, fn func(*pxar.Entry) error) error
  • func (a *Accessor) Lookup(path string) (*pxar.Entry, error)
  • func (a *Accessor) ReadEntryAt(offset int64) (*pxar.Entry, error)
  • func (a *Accessor) ReadEntryAtMinimal(offset int64) (*pxar.Entry, error)
  • func (a *Accessor) ReadFileContent(entry *pxar.Entry) ([]byte, error)
  • func (a *Accessor) ReadFileContentReader(entry *pxar.Entry) (io.ReadCloser, error)
  • func (a *Accessor) ReadRoot() (*pxar.Entry, error)
• type ListOption

Types

type Accessor

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

Accessor provides random access to entries in a pxar archive.

func NewAccessor

func NewAccessor(reader io.ReadSeeker, payloadReader ...io.ReadSeeker) *Accessor

NewAccessor creates an accessor for random access to a pxar archive. For split archives (v2 format), provide the payload reader as the second argument.

func (*Accessor) ListDirectory

func (a *Accessor) ListDirectory(dirOffset int64, opts ListOption, fn func(*pxar.Entry) error) error

ListDirectory streams directory entries without materializing a slice. For each entry, fn is called with a pointer that is only valid during the callback. Callers must copy the Entry if they need to retain it beyond fn's return. If fn returns a non-nil error, iteration stops and the error is returned.

func (*Accessor) Lookup

func (a *Accessor) Lookup(path string) (*pxar.Entry, error)

Lookup finds an entry by path in the archive.

func (*Accessor) ReadEntryAt

func (a *Accessor) ReadEntryAt(offset int64) (*pxar.Entry, error)

ReadEntryAt reads a pxar entry at the given archive offset.

func (*Accessor) ReadEntryAtMinimal

func (a *Accessor) ReadEntryAtMinimal(offset int64) (*pxar.Entry, error)

ReadEntryAtMinimal reads a pxar entry with minimal decoding. It skips extended metadata (xattrs, fcaps, ACLs, quota project ID) and only populates stat basics. Use for indexing/browsing where full metadata is unnecessary.

func (*Accessor) ReadFileContent

func (a *Accessor) ReadFileContent(entry *pxar.Entry) ([]byte, error)

ReadFileContent reads the content of a file entry from the archive.

func (*Accessor) ReadFileContentReader

func (a *Accessor) ReadFileContentReader(entry *pxar.Entry) (io.ReadCloser, error)

ReadFileContentReader returns a streaming reader for file content. The caller must close the returned reader when done. This avoids materializing the entire file in memory.

func (*Accessor) ReadRoot

func (a *Accessor) ReadRoot() (*pxar.Entry, error)

ReadRoot reads the root entry of the archive.

type ListOption

type ListOption struct {
	// Minimal skips decoding xattrs, fcaps, ACLs, and other extended
	// metadata. Only stat basics (mode, uid, gid, times) are populated.
	// Significantly reduces per-entry decode cost.
	Minimal bool
}

ListOption controls which metadata is decoded during ListDirectory.