package statefile

import "gvisor.dev/gvisor/pkg/state/statefile"

Package statefile defines the state file data stream.

This package currently does not include any details regarding the state encoding itself, only details regarding state metadata and data layout.

The file format is defined as follows.

/------------------------------------------------------\ | header (8-bytes) | +------------------------------------------------------+ | metadata length (8-bytes) | +------------------------------------------------------+ | metadata | +------------------------------------------------------+ | data | \------------------------------------------------------/

First, it includes a 8-byte magic header which is the following sequence of bytes [0x67, 0x56, 0x69, 0x73, 0x6f, 0x72, 0x53, 0x46]

This header is followed by an 8-byte length N (big endian), and an ASCII-encoded JSON map that is exactly N bytes long.

This map includes only strings for keys and strings for values. Keys in the map that begin with "_" are for internal use only. They may be read, but may not be provided by the user. In the future, this metadata may contain some information relating to the state encoding itself.

After the map, the remainder of the file is the state data.

Index ¶

• Constants
• Variables
• func MetadataUnsafe(r io.Reader) (map[string]string, error)
• func NewReader(r io.ReadCloser, key []byte) (io.ReadCloser, map[string]string, error)
• func NewWriter(w io.Writer, key []byte, metadata map[string]string) (io.WriteCloser, error)
• type CompressionLevel
• func CompressionLevelFromMetadata(metadata map[string]string) (CompressionLevel, error)
• func CompressionLevelFromString(val string) (CompressionLevel, error)
• func (c CompressionLevel) String() string
• type Options
• func (o Options) WriteToMetadata(metadata map[string]string) map[string]string

Constants ¶

const (
	// CompressionLevelFlateBestSpeed represents flate algorithm in best-speed mode.
	CompressionLevelFlateBestSpeed = CompressionLevel("flate-best-speed")
	// CompressionLevelNone represents the absence of any compression on an image.
	CompressionLevelNone = CompressionLevel("none")
	// CompressionLevelDefault represents the default compression level.
	CompressionLevelDefault = CompressionLevelFlateBestSpeed
)

const (
	// CompressionKey is the key for the compression level in the metadata.
	CompressionKey = "compression"
)

Variables ¶

var ErrBadMagic = fmt.Errorf("bad magic header")

ErrBadMagic is returned if the header does not match.

var ErrInvalidFlags = fmt.Errorf("flags set is invalid")

ErrInvalidFlags is returned if passed flags set is invalid.

var ErrInvalidMetadataLength = fmt.Errorf("metadata length invalid, maximum size is %d", maxMetadataSize)

ErrInvalidMetadataLength is returned if the metadata length is too large.

var ErrMetadataInvalid = fmt.Errorf("metadata invalid, can't start with _")

ErrMetadataInvalid is returned if passed metadata is invalid.

var ErrMetadataMissing = fmt.Errorf("missing metadata")

ErrMetadataMissing is returned if the state file is missing mandatory metadata.

Functions ¶

func MetadataUnsafe ¶

func MetadataUnsafe(r io.Reader) (map[string]string, error)

MetadataUnsafe reads out the metadata from a state file without verifying any HMAC. This function shouldn't be called for untrusted input files.

func NewReader ¶

func NewReader(r io.ReadCloser, key []byte) (io.ReadCloser, map[string]string, error)

NewReader returns a reader for a statefile.

func NewWriter ¶

func NewWriter(w io.Writer, key []byte, metadata map[string]string) (io.WriteCloser, error)

NewWriter returns a state data writer for a statefile.

Note that the returned WriteCloser must be closed.

Types ¶

type CompressionLevel ¶

type CompressionLevel string

CompressionLevel is the image compression level.

func CompressionLevelFromMetadata ¶

func CompressionLevelFromMetadata(metadata map[string]string) (CompressionLevel, error)

CompressionLevelFromMetadata returns image compression type stored in the metadata. If the metadata doesn't contain compression information the default behavior is the "flate-best-speed" state because the default behavior used to be to always compress. If the parameter is missing it will be set to default.

func CompressionLevelFromString ¶

func CompressionLevelFromString(val string) (CompressionLevel, error)

CompressionLevelFromString parses a string into the CompressionLevel.

func (CompressionLevel) String ¶

func (c CompressionLevel) String() string

type Options ¶

type Options struct {
	// Compression is an image compression type/level.
	Compression CompressionLevel

	// Resume indicates if the sandbox process should continue running
	// after checkpointing.
	Resume bool

	// SaveRestoreExecArgv is the argv of the save/restore binary split by spaces.
	// The first element is the path to the binary.
	SaveRestoreExecArgv string

	// SaveRestoreExecTimeout is the timeout for waiting for the save/restore
	// binary.
	SaveRestoreExecTimeout time.Duration

	// SaveRestoreExecContainerID is the ID of the container that the
	// save/restore binary executes in.
	SaveRestoreExecContainerID string
}

Options is statefile options.

func (Options) WriteToMetadata ¶

func (o Options) WriteToMetadata(metadata map[string]string) map[string]string

WriteToMetadata save options to the metadata storage. Method returns the reference to the original metadata map to allow to be used in the chain calls.

Source Files ¶

statefile.go