Documentation
¶
Overview ¶
Package docker executes commands and transfers files inside a running container. It implements invoke.Environment, verified against the invoketest contract suite.
The daemon is found the way the docker command finds it: an endpoint passed to WithHost, then a context named by WithContext or DOCKER_CONTEXT, then DOCKER_HOST, then the endpoint recorded by the current context — which is where installations that do not use the conventional socket, such as Colima and Rancher Desktop, put theirs.
The daemon must serve Engine API version 1.40 or newer, which Docker 19.03 was the first to do. That is the oldest version Docker's client library speaks, and an older daemon is refused when the Environment is created — as is a DOCKER_API_VERSION naming an older version.
Commands are delivered to the daemon as a real argument vector, so nothing is reinterpreted by a shell, and environment variables travel over the API rather than on a command line. Signal delivery needs a shell in the container to record the in-container process id; a container without one reports the capability as unavailable rather than accepting signals and dropping them. Without a shell, Close and cancellation cannot stop a command either: they end its input and let it go, returning at once with an outcome that says it was abandoned, while the command runs on in the container until it ends. Path lookup, uploads and the check Start makes before running a command need the shell too; downloads do not. Without that check, a missing executable or working directory is reported the way the daemon reports it, as exit status 127.
Index ¶
- type Config
- type Environment
- func (e *Environment) Capabilities() invoke.Capabilities
- func (e *Environment) Close() error
- func (e *Environment) Download(ctx context.Context, remotePath, localPath string, ...) error
- func (e *Environment) LookPath(ctx context.Context, name string) (string, error)
- func (e *Environment) OS() invoke.TargetOS
- func (e *Environment) Start(ctx context.Context, cmd invoke.Command, stdio invoke.IO) (invoke.Process, error)
- func (e *Environment) Upload(ctx context.Context, localPath, remotePath string, ...) error
- type Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Container is the container name or ID to execute in. Required.
Container string
// User is the user commands run as, in the same form docker accepts
// ("root", "1000", "1000:1000"). Empty means the container's own
// default.
User string
// Privileged runs commands with elevated privileges.
Privileged bool
// Host is the daemon endpoint, outranking every other source. Empty
// means the endpoint the local docker installation is configured to
// use, found in the order the package documentation gives: a context
// named by Context or DOCKER_CONTEXT, then DOCKER_HOST, then the
// current context's.
Host string
// Context names a docker context to take the endpoint from,
// overriding whichever one is current — and DOCKER_HOST, as the
// docker command's own --context flag does.
Context string
// Timeout bounds daemon calls that must not block indefinitely; zero
// or negative means 30s. See [WithTimeout] for which calls those are.
Timeout time.Duration
}
Config holds the settings for executing in a container. Callers normally build it with New and the With options rather than by hand; NewFromConfig accepts one directly.
type Environment ¶
type Environment struct {
// contains filtered or unexported fields
}
Environment is a connection to a running container.
func New ¶
New connects to the daemon and returns an Environment for the named container, which must already be running.
ctx bounds establishing the connection only — which is several round trips to the daemon, not one. It does not govern the Environment afterwards, which lives until Close.
func NewFromConfig ¶
func NewFromConfig(ctx context.Context, cfg *Config) (*Environment, error)
NewFromConfig connects using a Config assembled directly. ctx bounds establishing the connection, as in New.
func (*Environment) Capabilities ¶
func (e *Environment) Capabilities() invoke.Capabilities
Capabilities reports the container's optional features.
Signal delivery requires a shell to record the in-container process id; without one the capability is not declared, so signal requests fail rather than being silently dropped.
Terminal allocation is available: the daemon's exec API takes a terminal flag and an initial size.
func (*Environment) Close ¶
func (e *Environment) Close() error
Close marks the environment closed, stops transfers in flight and waits for them, then terminates commands still running and waits for each outcome to settle. It is idempotent.
A command in a container without a shell cannot be terminated: Close lets it go instead, its Wait returns at once saying it was abandoned, and it runs on in the container until it ends.
The daemon client closes only its idle connections, so a call Close does not own and that is already under way, such as a LookPath, runs to its end; one begun afterwards fails with invoke.ErrClosed.
func (*Environment) Download ¶
func (e *Environment) Download(ctx context.Context, remotePath, localPath string, opts ...invoke.TransferOption) error
Download copies a path out of the container. See download; Close stops it as it does an Upload.
func (*Environment) OS ¶
func (e *Environment) OS() invoke.TargetOS
OS reports the container's operating system, detected once at connect time.
func (*Environment) Start ¶
func (e *Environment) Start(ctx context.Context, cmd invoke.Command, stdio invoke.IO) (invoke.Process, error)
Start runs cmd in the container and returns a handle to it.
func (*Environment) Upload ¶
func (e *Environment) Upload(ctx context.Context, localPath, remotePath string, opts ...invoke.TransferOption) error
Upload copies a local file or directory tree into the container. See upload; Close stops it, and it then fails wrapping invoke.ErrClosed.
type Option ¶
type Option func(*Config)
Option configures a Config.
func WithContext ¶ added in v0.3.0
WithContext takes the daemon endpoint from the named docker context, rather than from whichever one the installation currently selects — overriding an ambient DOCKER_HOST too, as the docker command's own --context flag does.
Naming a context that cannot be read fails, rather than falling back to the default endpoint: the fallback is a different daemon, and commands would run somewhere the caller did not choose.
func WithPrivileged ¶
func WithPrivileged() Option
WithPrivileged runs commands with elevated privileges.
func WithTimeout ¶
WithTimeout bounds daemon calls that must not block indefinitely. Zero or negative means the default, 30s.
It bounds each of the provider's own calls on its own: the container inspect and the probes New makes, the kill a Signal, Close or cancellation sends, the status asked for once a command's output ends, and the cleanup after a command or an upload. For Start's pre-flight check, LookPath and upload staging, this setting bounds only status polling after output ends; it does not cap exec creation, attachment or output collection.
It is not a bound on a command or a transfer the caller asked for, which only their context and Close limit. Nor is it the ssh provider's WithTimeout, which bounds dialling and the handshake of a connection.