api

Documentation

Overview

Package api defines the API outline for working with different container runtimes.

The user should first establish some kind of connection as client with their desired container runtime. The client configuraton could be either by specifying it manually, or by recognizing them on the host first.

After establishing a client connection with container runtime, the user could invoke the client API to enumerate containers and images by their IDs, and open one of these entities furtherly.

Index

• type File
• type FileSystem
• type Image
• type Runtime

Types

type File

type File interface {
	io.ReadWriteCloser
	io.ReaderAt
	io.WriterAt

	Stat() (os.FileInfo, error)
}

File abstracts an open file from container. Some behaviours might be masked due to potential incompatibility.

type FileSystem

type FileSystem interface {
	Open(path string) (File, error)
	Stat(path string) (os.FileInfo, error)
	Lstat(path string) (os.FileInfo, error)
	Readlink(path string) (string, error)
	EvalSymlink(path string) (string, error)
	Readdir(path string) ([]os.FileInfo, error)
	Walk(root string, walkFn filepath.WalkFunc) error
}

FileSystem abstracts the property of an object to visit its internal file system structure, which is usually prepared by the container runtime.

type Image

type Image interface {
	FileSystem

	Close() error
	ID() string

	Repos() ([]string, error)
	RepoRefs() ([]string, error)

	OCISpecV1() (*imageV1.Image, error)
}

Image is the open image object from a runtime.

type Runtime

type Runtime interface {
	Close() error

	// ListImageIDs attempt to enumerate the images by their
	// IDs managed by the container runtime, which could be
	// used to open the image.
	ListImageIDs() ([]string, error)

	// FindImageIDs attempt to match image ID by specifying
	// their human readable identifiers. It must follow the
	// following rules.
	//
	// 1. When pattern is image ID recognizable by this
	//    container runtime, it will be searched first.
	// 2. When pattern is pure hexadecimal, the digest value
	//    portion will be matched.
	// 3. When pattern is a single identifier, all images
	//    with the specified identifier will be matched.
	// 4. When pattern is a repository path, all images with
	//    the specified repository but different versions
	//    will be matched.
	// 5. When pattern is a named tagged or canonical
	//    reference, the whole portion will be matched.
	FindImageIDs(pattern string) ([]string, error)

	// OpenImageByID attempt to open a image by its ID.
	OpenImageByID(id string) (Image, error)
}

Runtime is the connection established with a specific container runtime, depending on the implementation and container runtime internal nature.