types

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 22, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrContainerNotFound = errors.New("container not found")
	ErrImageNotFound     = errors.New("image not found")
	ErrNotFound          = errors.New("not found")
	ErrConflict          = errors.New("container state conflict")
	ErrPermissionsDenied = errors.New("permission denied")
	ErrConnectionFailed  = errors.New("connection failed")
	ErrInternal          = errors.New("internal error")
	ErrInvalidInput      = errors.New("invalid input")
	ErrUnauthorized      = errors.New("unauthorized")
)

Functions

This section is empty.

Types

type AuthConfig 

type AuthConfig struct {
	Username string
	Password string
	// ServerAddress is the image registry address.
	// If no address is provided, docker.io is used.
	ServerAddress string

	// IdentityToken is a specialized session token.
	// If provided, it is used instead of a password to negotiate an
	// access token with the container registry authentication server.
	IdentityToken string

	// RegistryToken is a raw bearer-token (usually a JWT) used mainly in
	// CI/CD environments to bypass username/password negotiation and provide
	// immediate, temporary access.
	RegistryToken string
}

AuthConfig contains authentication information for a container registry.

type ContainerCreateConfig 

type ContainerCreateConfig struct {
	// Name is an optional name of the container.
	Name string
	// Image specifies an image to be used and a version (e.g. "alpine:latest").
	// This is the only mandatory field.
	Image string

	// Env is a map of desired environment variables and their values.
	Env map[string]string
	// Labels specifies metadata for the container.
	Labels map[string]string

	// Ports is a list of port bindings for the container.
	Ports []PortBinding
	// Mounts is a list of bind mounts to volumes or directories for the container.
	Mounts []Mount

	// CPUs specifies the maximum number of CPUs available to the container.
	CPUs float64
	// MemoryMb specifies the maximum memory in megabytes available to the container.
	// If set to 0, the container will have unlimited memory.
	MemoryMb int64

	// RestartPolicy specifies the restart policy used for the container.
	Restart RestartPolicy
}

ContainerCreateConfig represents the configuration needed for the creation of a new container.

type ContainerCreateResult 

type ContainerCreateResult string

ContainerCreateResult holds the ID of the created container.

type ContainerExecOptions 

type ContainerExecOptions struct {
	// User specifies the user which will run the command.
	User string
	// Cmd holds the command and all its arguments. Must not be empty.
	Cmd []string

	// AttachStdout specifies whether the content of STDOUT will be returned.
	AttachStdout bool
	// AttachStderr specifies whether the content of STDERR will be returned.
	AttachStderr bool

	// WorkingDir specifies the working directory to run the command.
	WorkingDir string
	// Env holds the environment variables.
	Env []string
}

ContainerExecOptions holds the command to be executed inside the container.

func (*ContainerExecOptions) Validate 

func (opts *ContainerExecOptions) Validate() error

type ContainerExecResult 

type ContainerExecResult struct {
	// ExitCode holds the exit code of the executed command.
	ExitCode int64

	// Stdout holds the contents of STDOUT if AttachStdout was set to true.
	Stdout string
	// Stderr holds the contents of STDERR if AttachStderr was set to true.
	Stderr string
}

ContainerExecResult holds the output from executing a command inside a container.

type ContainerListOptions 

type ContainerListOptions struct {
	// All specifies whether to also return non-running containers in the list.
	All bool

	// Filters contain predicates for filtering the request.
	Filters Filters
}

ContainerListOptions holds optional arguments used for listing containers present on the host system.

type ContainerListResult 

type ContainerListResult struct {
	Containers []ContainerSummary
}

ContainerListResult holds a list of containers on the host system and basic information about them.

type ContainerLogsOptions 

type ContainerLogsOptions struct {
	// ShowStdout specifies whether the STDOUT stream will be captured.
	//
	// One of ShowStdout or ShowStderr must be set to true.
	ShowStdout bool
	// ShowStderr specifies whether the STDERR stream will be captured.
	//
	// One of ShowStdout or ShowStderr must be set to true.
	ShowStderr bool

	// Since represents a time from which onward logs should be returned.
	Since time.Time
	// Until represents a time up to which logs should be returned.
	Until time.Time

	// Timestamps specifies whether each line of logs will have its timestamp at the beginning.
	Timestamps bool

	// Follow keeps the connection open and continously stream new logs as they are produced.
	Follow bool

	// Tail specifies how many lines from the end should be returned.
	// It should be a stringified number or "all".
	Tail string

	// Details specifies whether to include detailed information and metadata which were passed
	// to the containers logging driver.
	Details bool
}

ContainerLogsOptions holds optional parameters which affect the type and structure of returned logs. One of ShowStdout or ShowStderr fields must be set to true.

type ContainerLogsResult 

type ContainerLogsResult io.ReadCloser

ContainerLogsResult holds a stream of logs from the container.

type ContainerOps 

type ContainerOps interface {
	// ContainerCreate initializes a new container based on the provided ContainerCreateConfig.
	// It returns the ID of the created container.
	//
	// ContainerCreateConfig is a mandatory argument.
	ContainerCreate(ctx context.Context, cfg *ContainerCreateConfig) (ContainerCreateResult, error)

	// ContainerStart initializes and starts an existing container with the provided ID.
	// If the container is already running, no error is returned.
	ContainerStart(ctx context.Context, id string, opts *ContainerStartOptions) error

	// ContainerStop gracefully halts a running container with the provided ID.
	// If the container is already stopped, no error is returned.
	ContainerStop(ctx context.Context, id string, opts *ContainerStopOptions) error

	// ContainerRemove forcefully kills and removes a container with the provided ID.
	// If the container is not running, it is only removed.
	ContainerRemove(ctx context.Context, id string, opts *ContainerRemoveOptions) error

	// ContainerStatus returns a ContainerStatusResult of a container with the provided ID.
	ContainerStatus(ctx context.Context, id string, opts *ContainerStatusOptions) (ContainerStatusResult, error)

	// ContainerList returns a ContainerListResult documenting basic information about all containers
	// on the host system.
	ContainerList(ctx context.Context, opts *ContainerListOptions) (ContainerListResult, error)

	// ContainerWait waits for a container with the provided ID to finish its task and returns
	// the exit code from the task.
	//
	// ContainerWaitOptions is a mandatory argument.
	ContainerWait(ctx context.Context, id string, opts *ContainerWaitOptions) (ContainerWaitResult, error)

	// ContainerExec executes a given command inside the container with the provided ID and returns
	// the exit code and optionally contents of Stdout and Stderr.
	//
	// ContainerExecOptions is a mandatory argument.
	ContainerExec(ctx context.Context, id string, opts *ContainerExecOptions) (ContainerExecResult, error)

	// ContainerLogs returns a ContainerLogsResult containing a stream of logs generated by the container.
	//
	// ContainerLogsOptions is a mandatory argument.
	ContainerLogs(ctx context.Context, id string, opts *ContainerLogsOptions) (ContainerLogsResult, error)
}

ContainerOps represents a set of methods for managing containers on the host.

type ContainerRemoveOptions 

type ContainerRemoveOptions struct {
	// RemoveVolumes specifies whether volumes mounted to the container should also be removed
	// (default is false).
	RemoveVolumes bool
	// Force specifies whether the container should be forcibly terminated (if running) before
	// removing it (default is false).
	Force bool
}

ContainerRemoveOptions holds optional arguments used for removing containers.

type ContainerStartOptions 

type ContainerStartOptions struct {
}

ContainerStartOptions may hold future optional arguments used for starting containers.

type ContainerStatusOptions 

type ContainerStatusOptions struct {
	// Size specifies whether to calculate the size of the container's filesystem (costly operation).
	// It should not be used unless needed (default is false).
	Size bool
}

ContainerStatusOptions holds optional arguments used for inspecting containers.

type ContainerStatusResult 

type ContainerStatusResult struct {
	// ID represents the container ID.
	ID string

	// Status specifies the current state of the container (e.g. "running").
	Status string
	// IPAddress specifies the IP address of the container.
	IPAddress string

	// ExitCode contains the exit code of the container, if it is stopped.
	ExitCode int
}

ContainerStatusResult represents the current status of a container.

type ContainerStopOptions 

type ContainerStopOptions struct {
	// Signal specifies a signal to be (gracefully) sent to the container (default is "SIGTERM").
	Signal string
	// Timeout specifies a time (in seconds) to wait for the container to stop gracefully
	// before forcibly terminating it with "SIGKILL".
	Timeout *int
}

ContainerStopOptions holds optional arguments used for stopping containers.

type ContainerSummary 

type ContainerSummary struct {
	// ID represents the container ID.
	ID string

	// Names is a list of names associated with the container.
	Names []string
	// Image represents the image running on the container.
	Image string

	// State represents a human-readable state of the container (e.g. "Up 1 minute").
	State string
	// Status represent the current state of the container (e.g. "running").
	Status string

	// Created is a timestamp of container creation.
	Created time.Time

	// Labels contains metadata for the container.
	Labels map[string]string
}

ContainerSummary represents basic information about a container.

type ContainerWaitOptions 

type ContainerWaitOptions struct {
	Condition WaitCondition
}

ContainerWaitOptions holds optional arguments used for waiting on containers.

type ContainerWaitResult 

type ContainerWaitResult int64

ContainerWaitResult holds the exit code of the exited container process.

type Event 

type Event struct {
	// Type represens the type of the event.
	Type EventType

	// Action represents the event action.
	Action EventAction

	// Actor represents the actor of the event.
	Actor EventActor

	// Time specifies the time of the event happening.
	Time time.Time
}

Event contains data about the event.

type EventAction 

type EventAction string

EventAction represents the action that is connected to the event. 

const (
	// EventActionCreate indicates that a container or resource was initialized but not yet started.
	EventActionCreate EventAction = "create"

	// EventActionStart indicates that a container's main process has started running.
	EventActionStart EventAction = "start"

	// EventActionRestart indicates that a container was restarted.
	EventActionRestart EventAction = "restart"

	// EventActionStop indicates that a container was gracefully stopped.
	EventActionStop EventAction = "stop"

	// EventActionPause indicates that a running container's processes were frozen.
	EventActionPause EventAction = "pause"

	// EventActionUnPause indicates that a paused container's processes were resumed.
	EventActionUnPause EventAction = "unpause"

	// EventActionKill indicates that a container was forcefully terminated using a system signal (e.g., SIGKILL).
	EventActionKill EventAction = "kill"

	// EventActionDie indicates that a container's main process has exited, regardless of the reason.
	EventActionDie EventAction = "die"

	// EventActionOOM indicates that a container was terminated by the host kernel for exceeding its memory limit.
	EventActionOOM EventAction = "oom"

	// EventActionDestroy indicates that a container's filesystem and resources were completely destroyed.
	EventActionDestroy EventAction = "destroy"

	// EventActionRemove indicates that a resource (like a container or volume) was removed from the daemon.
	EventActionRemove EventAction = "remove"

	// EventActionDelete indicates that a resource (typically an image) was deleted from the host.
	EventActionDelete EventAction = "delete"
)

type EventActor 

type EventActor struct {
	ID string
}

EventActor contains information about the resource that generated the event.

type EventOps 

type EventOps interface {
	// EventsStream returns an EventsStreamResult containing channels for events and errors on the
	// host system.
	EventsStream(ctx context.Context, opts *EventsStreamOptions) EventsStreamResult
}

EventOps represents a set of methods for monitoring events from containers on the host

type EventType 

type EventType string

EventType represents the type of event (the type of resource that generated it). 

const (
	// EventTypeContainer is a type that a container generates.
	EventTypeContainer EventType = "container"

	// EventTypeImage is a type that an image generates.
	EventTypeImage EventType = "image"

	// EventTypeVolume is a type that a volume generates.
	EventTypeVolume EventType = "volume"

	// EventTypeNetwork is a type that a network generates.
	EventTypeNetwork EventType = "network"
)

type EventsStreamOptions 

type EventsStreamOptions struct {
	// Since represents a time from which onward events should be returned.
	Since time.Time
	// Until represents a time up to which events should be returned.
	Until time.Time

	// Filters contain predicates for filtering the request.
	Filters Filters
}

EventsStreamOptions holds optional arguments for filtering which events get sent from the daemon.

type EventsStreamResult 

type EventsStreamResult struct {
	Events <-chan Event
	Errors <-chan error
}

EventsStreamResult holds streams of errors and events from the daemon.

type Filters 

type Filters map[string][]string

Filters represents a set of criteria for filtering results (e.g. containers or images). It acts as an AND filter between different keys, and an OR filter for values of the same key.

Always initialize it using make(Filters) or by explicit definition/

Example: 

f := make(Filters).Add("status", "running").Add("name", "foo", "bar")

func (Filters) Add 

func (f Filters) Add(key string, values ...string) Filters

Add appends values to the specific filter key. It returns the Filters for chaining.

type ImageInspectOptions 

type ImageInspectOptions struct{}

ImageInspectOptions may hold future optional arguments used for inspecting images.

type ImageInspectResult 

type ImageInspectResult struct {
	// ID represents the image ID.
	ID string

	// Created is a timestamp of the image creation.
	Created time.Time
	// Size is the size of all the layers of the image on disk.
	Size int64

	// Tags contain list of tags associated with the image.
	Tags []string

	// Architecture specifies the architecture the image is built to run on.
	Architecture string
	// OperatingSystem specifies the operating system the image is built to run on.
	OperatingSystem string
}

ImageInspectResult contains information about an image.

type ImageListOptions 

type ImageListOptions struct {
	// All specifies whether to also list intermediate image layers.
	All bool

	// Filters contain predicates for filtering the request.
	Filters Filters
}

ImageListOptions holds optional arguments used for listing images on the host.

type ImageListResult 

type ImageListResult struct {
	Images []ImageSummary
}

ImageListResult holds a list of images on the host system and basic information about them.

type ImageOps 

type ImageOps interface {
	// ImagePull pulls an image from a container registry.
	// If the image name does not contain a registry address, docker.io registry is used.
	ImagePull(ctx context.Context, name string, opts *ImagePullOptions) error

	// ImageInspect returns an ImageInspectResult containing information about an image with the provided ID.
	ImageInspect(ctx context.Context, id string, opts *ImageInspectOptions) (ImageInspectResult, error)

	// ImageList returns a list of ImageSummary documenting basic information about all images on the host system.
	ImageList(ctx context.Context, opts *ImageListOptions) (ImageListResult, error)

	// ImageRemove removes an image with the provided ID from the host system and returns
	// information about all removed tags corresponding with the provided image ID.
	ImageRemove(ctx context.Context, id string, opts *ImageRemoveOptions) (ImageRemoveResult, error)

	// ImagePrune requests the host container runtime to remove unused data and returns
	// information about pruned images and reclaimed space.
	ImagePrune(ctx context.Context, opts *ImagePruneOptions) (ImagePruneResult, error)
}

ImageOps represents a set of methods for managing images on the host

type ImagePruneOptions 

type ImagePruneOptions struct {
	// Filters contains predicates for filtering the request.
	Filters Filters
}

ImagePruneOptions holds optional arguments used for pruning dangling images.

type ImagePruneResult 

type ImagePruneResult struct {
	// ImagesRemoved contains information about all pruned images.
	ImagesRemoved []ImageRemoveSummary
	// SpaceReclaimed is the amount of space freed by the Prune operation.
	SpaceReclaimed uint64
}

ImagePruneResult contains a summary of the Prune operation.

type ImagePullOptions 

type ImagePullOptions struct {
	// All specifies whether to pull every single tag of the image.
	All bool
}

ImagePullOptions may hold future optional arguments used for pulling images from registry.

type ImageRemoveOptions 

type ImageRemoveOptions struct {
	// Force tells the daemon to remove the image even if there are stopped containers using it.
	Force bool

	// PruneChildren tells the daemon to clean up any not needed untagged parent layers.
	PruneChildren bool
}

ImageRemoveOptions holds optional arguments used for removing images.

type ImageRemoveResult 

type ImageRemoveResult struct {
	ImagesRemoved []ImageRemoveSummary
}

ImageRemoveResult holds a list of removed images (and tags).

type ImageRemoveSummary 

type ImageRemoveSummary struct {
	// Untagged is the ID of the untagged image.
	Untagged string
	// Deleted is the ID of the deleted image.
	Deleted string
}

ImageRemoveSummary contains information about the removed images.

type ImageSummary 

type ImageSummary struct {
	// ID represents the image ID.
	ID string

	// Created is a timestamp of the image creation.
	Created time.Time
	// Size is the size of all the layers of the image on disk.
	Size int64

	// Tags contain list of tags associated with the image.
	Tags []string

	// Labels contains metadata for the image.
	Labels map[string]string
}

ImageSummary contains basic information about an image.

type InfoResult 

type InfoResult struct {
	// ID specifies the system ID.
	ID string

	// Containers specifies the number of containers on the system.
	Containers int
	// ContainersRunning specifies the number of running containers on the system.
	ContainersRunning int
	// ContainersPaused specifies the number of paused containers on the system.
	ContainersPaused int
	// ContainersStopped specifies the number of stopped containers on the system.
	ContainersStopped int

	// Images specifies the number of images on the system.
	Images int

	// Driver specifies the storage driver used by the system.
	Driver string

	// MemoryLimit indicates whether the host kernel supports setting memory limits on containers.
	MemoryLimit bool
	// SwapLimit indicates whether the host kernel supports swap memory limiting.
	SwapLimit bool

	// SystemTime specifies the system time.
	SystemTime time.Time

	// KernelVersion specifies the kernel version.
	KernelVersion string
	// OperatingSystem specifies the host operating system.
	OperatingSystem string
	// OSVersion specifies the host operating system version.
	OSVersion string
	// OSType indicates the operating system type.
	OSType string
	// Architecture specifies the host architecture.
	Architecture string

	// NCPU specifies the number of CPUs on the host.
	NCPU int

	// MemTotal specifies the total amount of memory on the host.
	MemTotal int64

	// Name specifies the host system name.
	Name string
	// ServerVersion specifies the host server version.
	ServerVersion string

	// Warnings contains warnings which occurred during the collection of information about the system.
	Warnings []string
}

InfoResult represents information about the host server.

type Mount 

type Mount struct {
	// Source specifies the path on the host or a volume name.
	Source string
	// Destination specifies the path inside the container.
	Destination string

	// Type specifies the mount type (e.g. "bind", "volume").
	Type string

	// ReadOnly specifies if the mount is read-only.
	ReadOnly bool
}

Mount represents a bind between a path on the host FS and a path inside the container FS. It is used when there is need to access files or directories inside the container from the host.

type PortBinding 

type PortBinding struct {
	// HostIP specifies the IP address on the host to bind to (e.g. "192.168.0.1").
	HostIP string

	// HostPort specifies the port number on the host (e.g. 8080).
	HostPort int
	// ContainerPort specifies the port number inside the container (e.g. 80).
	ContainerPort int

	// Protocol specifies the communication protocol to use (e.g. "tcp", "udp").
	Protocol string
}

PortBinding represents a bind between a port on the host and a port inside the container. It is used when there is need to access network resources running inside the container from the host.

type RestartPolicy 

type RestartPolicy string

RestartPolicy represents the restart policy used for a container. 

const (
	RestartDisable       RestartPolicy = "no"
	RestartAlways        RestartPolicy = "always"
	RestartOnFailure     RestartPolicy = "on-failure"
	RestartUnlessStopped RestartPolicy = "unless-stopped"
)

func (RestartPolicy) IsValid 

func (r RestartPolicy) IsValid() bool

func (RestartPolicy) String 

func (r RestartPolicy) String() string

type Runtime 

type Runtime interface {
	SystemOps
	ContainerOps
	ImageOps
	EventOps
}

Runtime represents the standard set of methods for managing containers using different container runtimes.

type SystemOps 

type SystemOps interface {
	// Info returns a InfoResult with information about the host container runtime.
	Info(ctx context.Context) (InfoResult, error)

	// Login authenticates a user to a specified container registry.
	// If no ServerAddress is specified, docker.io registry will be used.
	Login(ctx context.Context, auth AuthConfig) error

	// Close terminates the connection to the runtime.
	Close() error
}

SystemOps represents a set of methods for managing the host container runtime.

type WaitCondition 

type WaitCondition string

WaitCondition represents a state of a container which has to be reached for the condition to be met. 

const (
	WaitConditionNotRunning WaitCondition = "not-running"
	WaitConditionNextExit   WaitCondition = "next-exit"
	WaitConditionRemoved    WaitCondition = "removed"
)

func (WaitCondition) IsValid 

func (w WaitCondition) IsValid() bool

func (WaitCondition) String 

func (w WaitCondition) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.