image

Documentation

Overview

Package image is the orchestration layer: it detects an input by content, scans its metadata, exposes its merged filesystem view, and lists or extracts files. It covers virtual disk containers (qcow2/vmdk/vhd/vhdx/vdi/ vma/ova/sif/wim/ffu/appimage/...), raw filesystem images (ext4/xfs/squashfs/ iso9660/fat/...), and, via the archive subpackage, archive formats (tar/zip/7z/rar/cpio/asar/rpm/deb/oci). Detection is content-based, never extension-based.

Index

• func ApplyImage(imageTarPath string, meta *types.ImageMetadata, outputDir string, ...) error
• func BuildFileSystem(imageTarPath string, meta *types.ImageMetadata) (*fsview.Node, error)
• func ClassifyInput(path string) string
• func DetectInput(path string) string
• func ExtractDiskPath(path, vp, destPath string, bufferSize int) (int, error)
• func ExtractDiskVolumes(path, outputDir string, bufferSize int) ([]string, error)
• func ExtractPath(imageTarPath string, meta *types.ImageMetadata, sourcePath, destPath string, ...) (int, error)
• func ExtractPlainArchive(archivePath, destDir string, bufferSize int) (int, error)
• func ExtractPlainPath(archivePath, source, dest string, bufferSize int) (int, error)
• func FormatListing(root *fsview.Node, target string) (string, error)
• func IsDiskImage(path string) bool
• func PrepareOutputDir(outputDir string, force bool) error
• func ReadArchiveFile(path string, meta *types.ImageMetadata, sourcePath string) (io.ReadCloser, int64, error)
• func ReadDiskFile(path, vp string) (io.ReadCloser, int64, error)
• func ReadPlainArchiveFile(archivePath, sourcePath string) (io.ReadCloser, int64, error)
• func ScanImageMetadata(imageTarPath string, sel Selection) (*types.ImageMetadata, error)
• func WriteConfigYAML(outputDir string, meta *types.ImageMetadata) error
• type DiskInfo
• type DiskMetadata
  • func ScanDiskMetadata(path string) (*DiskMetadata, error)
• type DiskVolume
  • func (v DiskVolume) String() string
• type FileEntry
  • func ListArchive(imageTarPath string, sel Selection, treePath string) ([]FileEntry, error)
  • func ListDisk(path, vp string) ([]FileEntry, error)
  • func ListEntries(root *fsview.Node, target string) ([]FileEntry, error)
  • func ListPlainArchive(archivePath, treePath string) ([]FileEntry, error)
• type PlainInfo
  • func PlainArchiveInfo(path string) (*PlainInfo, error)
• type ProgressReporter
• type Selection

Functions

func ApplyImage

func ApplyImage(imageTarPath string, meta *types.ImageMetadata, outputDir string, bufferSize int, progress ProgressReporter) error

func BuildFileSystem

func BuildFileSystem(imageTarPath string, meta *types.ImageMetadata) (*fsview.Node, error)

BuildFileSystem merges all layers of the image into an in-memory tree without writing anything to disk.

func ClassifyInput

func ClassifyInput(path string) string

ClassifyInput returns the input class of path by content:

"disk"    — a virtual disk container or raw filesystem image
"image"   — a docker-save archive or OCI image layout (has manifest.json)
"archive" — a plain archive (tar/tar.gz/zip/7z/rar/cpio/asar/rpm)
""        — unsupported

Unlike the docker-save path, a plain archive is a flat list of files with no layered rootfs, so it is listed and extracted through a single flat tree.

func DetectInput

func DetectInput(path string) string

DetectInput returns the input class of path by content: "disk" for a virtual disk container or raw filesystem image, "archive" for a plain archive, and "" for unsupported files.

func ExtractDiskPath

func ExtractDiskPath(path, vp, destPath string, bufferSize int) (int, error)

ExtractDiskPath copies the file or directory at virtual path vp out to dest.

func ExtractDiskVolumes

func ExtractDiskVolumes(path, outputDir string, bufferSize int) ([]string, error)

ExtractDiskVolumes extracts every filesystem volume in the image. With several volumes each lands in its own subdirectory under outputDir; a single volume goes straight into outputDir. It returns the extracted volume names.

func ExtractPath

func ExtractPath(imageTarPath string, meta *types.ImageMetadata, sourcePath, destPath string, bufferSize int) (int, error)

ExtractPath copies a single file or directory from the merged image filesystem to destPath, streaming only the entries that belong to the selection instead of extracting the whole image.

Semantics mirror cp: a directory source copied into an existing directory lands at destPath/<basename>, while a non-existent destination receives the copy directly. Extracting the image root ("/" or ".") puts its contents into destPath itself. Returns the number of entries written.

func ExtractPlainArchive

func ExtractPlainArchive(archivePath, destDir string, bufferSize int) (int, error)

ExtractPlainArchive extracts the entire plain archive into destDir, writing files, directories and symlinks and returning the number of entries written.

func ExtractPlainPath

func ExtractPlainPath(archivePath, source, dest string, bufferSize int) (int, error)

ExtractPlainPath copies a single file or directory from a plain archive to a local destination, mirroring cp semantics: a directory copied into an existing directory lands at dest/<basename>. Returns the count of entries written.

func FormatListing

func FormatListing(root *fsview.Node, target string) (string, error)

FormatListing renders the merged image filesystem at target the way `ls -al` would: one long-format line per entry, plus a total block line for directories. target "" or "/" lists the image root.

func IsDiskImage

func IsDiskImage(path string) bool

IsDiskImage reports whether path is a virtual disk image (qcow2/vmdk/vhd/ vhdx/vdi/parallels/qed/qcow1/vma/sif/ova/ovf/ffu/wim/esd/swm) or a raw filesystem image (ext4/xfs/squashfs/ISO9660/UDF/exFAT/EROFS/FAT). Detection is content based (file magic), not by filename extension. Disk images are a different input class from the tar/zip archives handled elsewhere.

func PrepareOutputDir

func PrepareOutputDir(outputDir string, force bool) error

func ReadArchiveFile

func ReadArchiveFile(path string, meta *types.ImageMetadata, sourcePath string) (io.ReadCloser, int64, error)

ReadArchiveFile opens the content of a single regular file inside an archive image (tar/tar.gz/tgz/zip/7z/cpio/rar), following hardlink and symlink nodes to the regular file they point at. The returned reader must be closed to release the opened layer; size is the file length in bytes.

func ReadDiskFile

func ReadDiskFile(path, vp string) (io.ReadCloser, int64, error)

ReadDiskFile opens the content of a single regular file inside a disk image (qcow2/vmdk/vhd/vhdx/ova/...) at virtual path vp. The returned reader must be closed to release the image, its volumes and the opened file; size is the file length in bytes. Symlinks are not followed; use a filesystem path.

func ReadPlainArchiveFile

func ReadPlainArchiveFile(archivePath, sourcePath string) (io.ReadCloser, int64, error)

ReadPlainArchiveFile opens one regular file inside a plain archive, following symlink and hardlink nodes to the file that holds the content.

func ScanImageMetadata

func ScanImageMetadata(imageTarPath string, sel Selection) (*types.ImageMetadata, error)

func WriteConfigYAML

func WriteConfigYAML(outputDir string, meta *types.ImageMetadata) error

Types

type DiskInfo

type DiskInfo struct {
	Name        string       `json:"name"`
	Format      string       `json:"format"`
	VirtualSize int64        `json:"virtual_size"`
	Filesystem  string       `json:"filesystem,omitempty"`
	Volume      string       `json:"volume,omitempty"`
	Volumes     []DiskVolume `json:"volumes,omitempty"`
}

DiskInfo describes one disk inside an opened image: a qcow2/vmdk file, or a single .vmdk extracted from an OVA.

type DiskMetadata

type DiskMetadata struct {
	Disks []DiskInfo `json:"disks"`
}

DiskMetadata summarizes a disk image: one or more disks, each with its partitions and LVM logical volumes.

func ScanDiskMetadata

func ScanDiskMetadata(path string) (*DiskMetadata, error)

ScanDiskMetadata inspects a disk image without extracting anything.

type DiskVolume

type DiskVolume struct {
	Name   string `json:"name"`
	Kind   string `json:"kind"` // "partition" | "lvm" | "disk"
	Start  int64  `json:"start"`
	Size   int64  `json:"size"`
	FSType string `json:"fs_type,omitempty"` // "ext4" | "xfs"
}

DiskVolume is one extractable region on a disk image: an MBR/GPT partition or an LVM logical volume.

func (DiskVolume) String

func (v DiskVolume) String() string

String renders a compact "name(fs)" form so CLI listings stay legible.

type FileEntry

type FileEntry struct {
	Name    string    `json:"name"`
	Type    string    `json:"type"`
	Mode    string    `json:"mode"`
	Size    int64     `json:"size"`
	ModTime time.Time `json:"mod_time"`
	Target  string    `json:"target,omitempty"`
	FSType  string    `json:"fs_type,omitempty"` // filesystem of a disk/volume row
}

FileEntry is a structured description of one entry in the merged image filesystem — the machine-friendly counterpart of a FormatListing line.

func ListArchive

func ListArchive(imageTarPath string, sel Selection, treePath string) ([]FileEntry, error)

ListArchive lists the directory (or single file) at treePath inside an archive image, caching the result so repeated listings skip re-scanning the archive and re-building the merged filesystem tree.

func ListDisk

func ListDisk(path, vp string) ([]FileEntry, error)

ListDisk lists entries at virtual path vp: the disks when vp is empty on a multi-disk image, the volumes for a single disk, or a directory/file inside a volume.

func ListEntries

func ListEntries(root *fsview.Node, target string) ([]FileEntry, error)

ListEntries resolves target inside the merged tree and returns every entry to display: the sorted children when target is a directory (or the image root), the entry itself otherwise.

func ListPlainArchive

func ListPlainArchive(archivePath, treePath string) ([]FileEntry, error)

ListPlainArchive lists the directory (or single entry) at treePath inside a plain archive, without extracting.

type PlainInfo

type PlainInfo struct {
	Format    string `json:"format"`
	Files     int    `json:"files"`
	TotalSize int64  `json:"total_size"`
}

PlainInfo summarizes a plain archive for the info command.

func PlainArchiveInfo

func PlainArchiveInfo(path string) (*PlainInfo, error)

PlainArchiveInfo builds a summary of a plain archive without extraction.

type ProgressReporter

type ProgressReporter interface {
	SetLayer(string)
	AddLayer()
	MarkDone()
}

type Selection

type Selection struct {
	ImageIndex int
	RepoTag    string
}