engineclient

Documentation

Overview

Package engineclient defines the EngineClient interface between concrete container engine adaptor implementations and the engine-neutral watcher core.

Sub-packages implement specific container engines adaptors.

Index

• Constants
• func IsProcesslessContainer(err error) bool
• func NewProcesslessContainerError(nameorid string, typ string) error
• type ContainerEvent
• type ContainerEventType
• type EngineClient
• type ErrProcesslessContainer
  • func (err ErrProcesslessContainer) Error() string
• type Preflighter
• type RucksackPacker
• type Trialer

Constants

const ProjectUnknown = "\000"

ProjectUnknown signals that the project name for a container event is unknown, as opposed to the zero project name.

Functions

func IsProcesslessContainer

func IsProcesslessContainer(err error) bool

IsProcesslessContainer returns true if the specified error is an ProcesslessContainerErr.

func NewProcesslessContainerError

func NewProcesslessContainerError(nameorid string, typ string) error

NewProcesslessContainerError returns a new ErrProcesslessContainer, stating the type of container and its name or ID.

Types

type ContainerEvent

type ContainerEvent struct {
	Type    ContainerEventType // type of lifecycle event.
	ID      string             // ID (or name) of container.
	Project string             // optional composer project name, or zero.
}

ContainerEvent is either a container lifecycle event of a container becoming alive, having died (more precise: its process exited), paused or unpaused.

type ContainerEventType

type ContainerEventType byte

ContainerEventType identifies and enumerates the container lifecycle events of "alive" containers, including their demise. Please do not confuse this lifecycle for alive containers with the usually much more comprehensive container lifecycles that include creating a container long before it might become alive: such stages are of no interest to us here; for instance, there's no container creation event, "only" the container start event.

const (
	ContainerStarted  ContainerEventType = iota // container has been started
	ContainerExited                             // container has terminated (exited)
	ContainerPaused                             // container has been paused
	ContainerUnpaused                           // container has been unpaused
)

type EngineClient

type EngineClient interface {
	// List all the currently alive and kicking containers. Return errors (only)
	// in case of (severe) conntection and daemon failures that aren't
	// transparent.
	List(ctx context.Context) ([]*whalewatcher.Container, error)
	// Query (only) the subset of container details of interest to us, given the
	// name or ID of a particular container.
	Inspect(ctx context.Context, nameorid string) (*whalewatcher.Container, error)
	// Stream container lifecycle events, limited to those events in the
	// lifecycle of containers getting born (=alive, as opposed to, say,
	// "conceived", dead/gone/"sleeping") and die.
	LifecycleEvents(ctx context.Context) (<-chan ContainerEvent, <-chan error)

	// (More or less) unique engine identifier; the exact format is
	// engine-specific.
	ID(ctx context.Context) string
	// Identifier of the type of container engine, such as "docker.com",
	// "containerd.io", et cetera.
	Type() string
	// Version information about the engine.
	Version(ctx context.Context) string
	// Container engine API path.
	API() string
	// Container engine PID, when known. Otherwise zero.
	PID() int

	// Underlying engine client (engine-specific).
	Client() interface{}

	// Clean up and release any engine client resources, if necessary.
	Close()
}

EngineClient defines the generic methods needed in order to watch the containers of a container engine, regardless of the specific type of engine.

type ErrProcesslessContainer

type ErrProcesslessContainer string

ErrProcesslessContainer is a custom error indicating that inspecting container details failed because it was a container without any process (yet or anymore), such as a container freshly created, and yet not started.

This usually happens due to transient changes between listing containers or processing lifecycle-related events and inspecting them, because there are no atomic operations available (and strictly necessary). There are already checks in place that usually avoid this error in static situations, but they can never give one hundred percent garantuees.

func (ErrProcesslessContainer) Error

func (err ErrProcesslessContainer) Error() string

Error returns the error message.

type Preflighter

type Preflighter interface {
	// Run "preflight" tasks just right before starting a Watch.
	Preflight(ctx context.Context)
}

Allow an engine client to do some final pre-flight operations right before starting a watch, where the preflight ops might require talking to a particular engine and thus should be controlled by a context.

The raison d'être at this time is to avoid a race condition in the Docker client API version negotiation that otherwise trips our race-enabled tests and thus makes us blind for race violations in our own code base.

type RucksackPacker

type RucksackPacker interface {
	Pack(container *whalewatcher.Container, inspection interface{})
}

RucksackPacker optionally adds additional information to the tracked container information, as kind of a Rucksack. It gets passed container engine-specific inspection information so as to be able to pick and pack application-specific container information beyond the stock information always maintained by the whalewatcher module.

type Trialer

type Trialer interface {
	Try(ctx context.Context) error
}

Trialer optionally allows an engine client to update cached engine information on the first attempt or on any retry afterwards. Any error returned will abort the current attempt, back off, and then a retry.