basemeta

Documentation

Overview

Package basemeta reads and writes streams of base image content metadata.

A stream describes tar entries without materializing a tar: it is a length-delimited sequence of baselayer.BaseEntry protobuf messages, zstd compressed as a whole. Rules that describe base image content (users, CA certificates, directory skeletons, ...) each emit one stream; the terminal layer rule reads all of them, merges the entries with Merge, and writes a single flat layer.

The format is internal to rules_img and carries no version: producer and consumer always ship in the same binary.

Index

• Constants
• func Dir(path string, mode int64) *baselayer.BaseEntry
• func File(path string, mode int64, content []byte) *baselayer.BaseEntry
• func FileFromPath(path string, mode int64, srcPath string) *baselayer.BaseEntry
• func Merge(streams [][]*baselayer.BaseEntry, opts MergeOptions) ([]*baselayer.BaseEntry, error)
• func NormalizePath(path string) string
• func Read(r io.Reader) ([]*baselayer.BaseEntry, error)
• func ReadFile(path string) ([]*baselayer.BaseEntry, error)
• func Symlink(path, target string) *baselayer.BaseEntry
• func ToTarHeader(entry *baselayer.BaseEntry) (*tar.Header, error)
• func WithOwner(entry *baselayer.BaseEntry, uid, gid int64, uname, gname string) *baselayer.BaseEntry
• func WithProducer(entries []*baselayer.BaseEntry, producer string) []*baselayer.BaseEntry
• type MergeOptions
  • func DefaultMergeOptions() MergeOptions
• type Writer
  • func Create(path string) (*Writer, io.Closer, error)
  • func NewWriter(w io.Writer) (*Writer, error)
  • func (w *Writer) Close() error
  • func (w *Writer) Write(entry *baselayer.BaseEntry) error
  • func (w *Writer) WriteAll(entries []*baselayer.BaseEntry) error

Constants

const SchilyXattrPrefix = "SCHILY.xattr."

SchilyXattrPrefix is the PAX record namespace tar uses for extended attributes.

Functions

func Dir

func Dir(path string, mode int64) *baselayer.BaseEntry

Dir builds a directory entry.

func File

func File(path string, mode int64, content []byte) *baselayer.BaseEntry

File builds a regular file entry with inline content.

func FileFromPath

func FileFromPath(path string, mode int64, srcPath string) *baselayer.BaseEntry

FileFromPath builds a regular file entry backed by a file on disk. srcPath is resolved relative to the execution root when the entry is turned into a layer.

func Merge

func Merge(streams [][]*baselayer.BaseEntry, opts MergeOptions) ([]*baselayer.BaseEntry, error)

Merge combines the entries of several streams into the ordered entry list of a single flat layer.

Streams are supplied in dependency order, and for a path described by more than one stream the last one wins -- a rule closer to the layer overrides what it depends on. Two entries for the same path with *different* types are rejected instead: that is a rule authoring mistake (say a directory shadowing a symlink) rather than a deliberate override, and silently picking one would produce a subtly broken image.

The result is sorted by path, which puts every parent directory ahead of its children.

func NormalizePath

func NormalizePath(path string) string

NormalizePath turns a user-supplied image path into the tar convention used throughout a stream: no leading "/", no trailing "/", no "./" prefix.

func Read

func Read(r io.Reader) ([]*baselayer.BaseEntry, error)

Read decodes every entry of a compressed stream, in order.

func ReadFile

func ReadFile(path string) ([]*baselayer.BaseEntry, error)

ReadFile decodes every entry of the compressed stream stored at path.

func Symlink

func Symlink(path, target string) *baselayer.BaseEntry

Symlink builds a symbolic link entry pointing at target.

func ToTarHeader

func ToTarHeader(entry *baselayer.BaseEntry) (*tar.Header, error)

ToTarHeader converts an entry into the tar header it describes. The Size field is left at zero for regular files: the caller knows whether the content comes from an inline blob or a file on disk and fills it in.

func WithOwner

func WithOwner(entry *baselayer.BaseEntry, uid, gid int64, uname, gname string) *baselayer.BaseEntry

WithOwner sets the numeric and symbolic owner on an entry and returns it, so it can be chained onto a constructor.

func WithProducer

func WithProducer(entries []*baselayer.BaseEntry, producer string) []*baselayer.BaseEntry

WithProducer records the label of the rule that created the entry, used to name both sides of a conflict during Merge.

Types

type MergeOptions

type MergeOptions struct {
	// CreateParentDirectories synthesizes a directory entry for every parent of
	// an entry that no stream describes.
	CreateParentDirectories bool
	// ParentDirectoryMode is the mode given to synthesized parents.
	ParentDirectoryMode int64
}

MergeOptions controls how streams are combined by Merge.

func DefaultMergeOptions

func DefaultMergeOptions() MergeOptions

DefaultMergeOptions returns the options used when a caller has no preference.

type Writer

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

Writer serializes BaseEntry messages into a compressed, length-delimited stream. Callers must call Close to flush the compressor.

func Create

func Create(path string) (*Writer, io.Closer, error)

Create opens path for writing and returns a Writer for it. The returned closer closes both the Writer and the file.

func NewWriter

func NewWriter(w io.Writer) (*Writer, error)

NewWriter returns a Writer emitting into w.

func (*Writer) Close

func (w *Writer) Close() error

Close flushes the compressor. It does not close the underlying writer.

func (*Writer) Write

func (w *Writer) Write(entry *baselayer.BaseEntry) error

Write appends one entry to the stream.

func (*Writer) WriteAll

func (w *Writer) WriteAll(entries []*baselayer.BaseEntry) error

WriteAll appends every entry to the stream, stopping at the first error.