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 (SipHash24 hashed, BST-ordered). It supports both unified (v1) and split (v2) formats, lazy metadata decoding (Minimal mode), hardlink following, and streaming file content reads.

Usage

acc := accessor.NewAccessor(reader)
root, _ := acc.ReadRoot()
entry, _ := acc.Lookup("/etc/hostname")
rc, _ := acc.ReadFileContentReader(entry)
defer rc.Close()
content, _ := io.ReadAll(rc)

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.

Hardlink Following

FollowHardlink resolves a hardlink entry to its target file entry by computing filenameHeaderOffset - linkOffset from the wire format, then re-reading the full entry at that position. This mirrors Rust's Accessor::follow_hardlink:

link, _ := acc.Lookup("/bin/bunzip2")
target, _ := acc.FollowHardlink(link)
rc, _ := acc.ReadFileContentReader(target)

Minimal Mode

ListOption{Minimal: true} skips decoding xattrs, ACLs, fcaps, and other extended metadata. Only stat basics (mode, uid, gid, times) are populated. This significantly reduces per-entry decode cost for index and browse workloads.

Index

• type Accessor
  • func NewAccessor(reader io.ReadSeeker, payloadReader ...io.ReadSeeker) *Accessor
  • func (a *Accessor) FollowHardlink(entry *pxar.Entry) (*pxar.Entry, error)
  • 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) 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.

Thread safety: Accessor methods that read from the metadata stream (ReadRoot, Lookup, ListDirectory, ReadEntryAt, ReadEntryAtMinimal, ReadFileContent, and the v1 path of ReadFileContentReader) are safe for concurrent use. The payload path of ReadFileContentReader (split archives) returns an independent io.SectionReader that can be read concurrently without additional synchronization.

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

func (a *Accessor) FollowHardlink(entry *pxar.Entry) (*pxar.Entry, error)

FollowHardlink resolves a hardlink entry to its target file entry. Mirrors Rust's Accessor::follow_hardlink: uses the relative offset stored in the hardlink wire format to seek back to the target's FILENAME header and re-reads the full entry from that position.

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 only populates stat basics and structural fields. Use for indexing/browsing where full metadata is unnecessary.

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.

When the underlying reader implements io.ReaderAt, the returned reader is backed by an io.SectionReader and is safe for concurrent use across multiple goroutines (each call returns an independent reader).

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.