interop

Documentation

Overview

Package interop reads foreign archive formats (zip, tar and its compressed variants, 7z, rar, and raw compressed streams) and converts them to native .oar. It is read-only: OAR never writes foreign containers.

Each format is a self-contained backend registered in an init(); adding a new one is a single file plus one register() call. Foreign entries are surfaced as archive.Entry, so conversion reuses the native writer unchanged.

Index

• Variables
• func Convert(in, out string, opt archive.Options, password string) (*format.Index, string, error)
• func Detect(path string) (string, error)
• func ExtractTo(in, dest, password string) (int, string, error)
• func FS(a Archive) (fs.FS, error)
• func Formats() []string
• func Verify(in, password string) (int, int64, string, error)
• type Archive
  • func Open(path, password string) (Archive, error)
• type Opener

Variables

var ErrBomb = errors.New("interop: decompression limit exceeded (possible archive bomb)")

ErrBomb is returned when decompression exceeds the safety limit for the archive's on-disk size (a likely decompression bomb).

var ErrDMGUnavailable = errors.New("interop: this build has no DMG support — rebuild with `-tags dmg` (needs a C compiler for LZFSE)")

ErrDMGUnavailable is returned when a .dmg is opened in a build without DMG support. DMG reading needs cgo (LZFSE), so it lives behind the `dmg` build tag.

var ErrEncrypted = errors.New("interop: archive is encrypted, a password is required")

ErrEncrypted is returned by a backend when the archive needs a password (and none, or a wrong one, was supplied). Callers use errors.Is to prompt the user.

Functions

func Convert

func Convert(in, out string, opt archive.Options, password string) (*format.Index, string, error)

Convert reads a foreign archive and writes it as a native .oar (password "" if the source isn't encrypted).

func Detect

func Detect(path string) (string, error)

Detect identifies a file's format by magic bytes, falling back to extension.

func ExtractTo

func ExtractTo(in, dest, password string) (int, string, error)

ExtractTo reads a foreign archive and writes its files into dest. Paths that would escape dest are refused (Zip-Slip guard); total output is capped against decompression bombs. Returns count and detected kind.

Extraction goes through os.Root (Go 1.24+), so every write is confined to dest at the OS level: this defeats not just lexical "../" traversal but also symlink traversal and the TOCTOU races that a purely lexical IsLocal check cannot — e.g. a pre-existing or concurrently-created symlink under dest pointing outside it. IsLocal stays as a cheap first filter (and to skip absolute/empty names).

func FS

func FS(a Archive) (fs.FS, error)

FS returns a read-only fs.FS view over an opened foreign archive, so callers can traverse it with fs.WalkDir / fs.ReadFile and open entries lazily through the underlying backend. Directories implied by entry paths are synthesized.

func Formats

func Formats() []string

Formats returns the supported format names (for help/diagnostics).

func Verify

func Verify(in, password string) (int, int64, string, error)

Verify reads every entry to completion, surfacing decompression/CRC errors (like `unzip -t`). Returns file count, total bytes read, and detected kind.

Types

type Archive

type Archive interface {
	Entries() ([]archive.Entry, error)
	Close() error
}

Archive is a read-only foreign archive yielding native entries.

func Open

func Open(path, password string) (Archive, error)

Open detects and opens a foreign archive (password "" if none).

type Opener

type Opener func(path, password string) (Archive, error)

Opener opens a foreign archive of a known format. password is "" when none is supplied; backends that don't support encryption ignore it.