Documentation
¶
Overview ¶
Package docker is a thin, READ-ONLY Docker Engine API client that talks to the loopback docker-socket-proxy (plan §3) — never the raw socket. It deliberately implements only the handful of read endpoints the proxy's verb allowlist permits (CONTAINERS/INFO/VERSION), instead of pulling in the full Docker Go SDK: that keeps the binary near the ~12–18 MB footprint target (plan §2) and the dependency/supply-chain surface minimal (plan §15). Container-supplied fields (names, labels, image) are untrusted input and must be output-encoded by callers (html/template does this).
Index ¶
- Constants
- type Client
- func (c *Client) Info(ctx context.Context) (Info, error)
- func (c *Client) InspectContainer(ctx context.Context, id string) (ContainerInspect, error)
- func (c *Client) ListContainers(ctx context.Context, all bool) ([]Container, error)
- func (c *Client) StatsOneShot(ctx context.Context, id string) (Stats, error)
- func (c *Client) StreamLogs(ctx context.Context, id string, tail int, follow bool, onLine func(string)) error
- func (c *Client) Version(ctx context.Context) (Version, error)
- type Container
- type ContainerInspect
- type Info
- type Stats
- type Version
Constants ¶
const ( LabelProject = "com.docker.compose.project" LabelService = "com.docker.compose.service" LabelWorkingDir = "com.docker.compose.project.working_dir" LabelConfigFiles = "com.docker.compose.project.config_files" // LabelOneOff marks a `docker compose run` container ("True"). These are transient one-shot // containers (cron scheduled_tasks, backup/restore sidecars) — NOT supervised services — so // the monitor/self-heal must exclude them from the app snapshot. LabelOneOff = "com.docker.compose.oneoff" )
Compose label keys Mooring groups containers by (an app = one project) and targets `docker compose` with (the project dir + config files).
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a read-only Engine API client over the loopback socket-proxy.
func New ¶
New returns a client targeting a loopback proxy address (host:port). The caller (config validation) guarantees the address is loopback.
func (*Client) InspectContainer ¶
InspectContainer returns the detailed state of one container.
func (*Client) ListContainers ¶
ListContainers lists containers. all=true includes stopped ones.
func (*Client) StatsOneShot ¶
StatsOneShot returns a single, immediate stats sample (no daemon-side double read). CPU% is derived by the caller from deltas between successive samples.
func (*Client) StreamLogs ¶
func (c *Client) StreamLogs(ctx context.Context, id string, tail int, follow bool, onLine func(string)) error
StreamLogs follows a container's logs through the read-only socket-proxy (read plane — no docker child, no semaphore), demultiplexing the stdcopy framing and invoking onLine per (truncated) line until ctx is done or the stream ends.
type Container ¶
type Container struct {
ID string `json:"Id"`
Names []string `json:"Names"`
Image string `json:"Image"`
State string `json:"State"` // running|exited|created|paused|...
Status string `json:"Status"` // human string, e.g. "Up 3 hours (healthy)"
Labels map[string]string `json:"Labels"`
NetworkSettings containerNetworkSummary `json:"NetworkSettings"`
}
Container is the subset of a GET /containers/json entry we use.
func (Container) ConfigFiles ¶
ConfigFiles returns the compose config file paths for the project, dropping empty/whitespace entries (a stray "" would become `docker compose -f ""`).
func (Container) IPs ¶
IPs returns the container's non-empty per-network IPv4 addresses, sorted by network name for a deterministic order (so a re-render of the same replica set produces byte-identical config and skips a needless Caddy reload).
func (Container) OneOff ¶ added in v0.7.0
OneOff reports whether this is a transient `compose run` one-shot container (cron task or backup/restore sidecar) rather than a supervised long-running service.
func (Container) Project ¶
Project returns the compose project label (the app key), or "" if unlabeled.
func (Container) WorkingDir ¶
WorkingDir returns the compose project working directory (the app run_dir).
type ContainerInspect ¶
type ContainerInspect struct {
ID string `json:"Id"`
Name string `json:"Name"`
RestartCount int `json:"RestartCount"`
State struct {
Status string `json:"Status"`
Running bool `json:"Running"`
ExitCode int `json:"ExitCode"`
OOMKilled bool `json:"OOMKilled"`
StartedAt string `json:"StartedAt"`
FinishedAt string `json:"FinishedAt"`
Health *struct {
Status string `json:"Status"` // healthy|unhealthy|starting
FailingStreak int `json:"FailingStreak"`
} `json:"Health"`
} `json:"State"`
Config struct {
Image string `json:"Image"`
Labels map[string]string `json:"Labels"`
} `json:"Config"`
Mounts []struct {
Type string `json:"Type"` // bind | volume | tmpfs
Name string `json:"Name"` // volume name ("" for binds; a 64-hex hash for anonymous volumes)
RW bool `json:"RW"`
} `json:"Mounts"`
}
ContainerInspect is the subset of GET /containers/{id}/json we use.
func (ContainerInspect) HasSharedRWVolume ¶
func (ci ContainerInspect) HasSharedRWVolume() bool
HasSharedRWVolume reports whether the container has a read-write mount that would be SHARED across replicas (a host bind or a named volume) — the auto-scaling C3 disqualifier. Anonymous volumes (a 64-hex name) are per-replica scratch and don't count; tmpfs never counts.
func (ContainerInspect) HealthStatus ¶
func (ci ContainerInspect) HealthStatus() string
HealthStatus returns the container's healthcheck status, or "none" if it has no healthcheck.
type Info ¶
type Info struct {
Containers int `json:"Containers"`
ContainersRunning int `json:"ContainersRunning"`
ContainersStopped int `json:"ContainersStopped"`
Images int `json:"Images"`
NCPU int `json:"NCPU"`
MemTotal int64 `json:"MemTotal"`
ServerVersion string `json:"ServerVersion"`
}
Info is the subset of GET /info we use.
type Stats ¶
type Stats struct {
CPUStats cpuStats `json:"cpu_stats"`
PreCPUStats cpuStats `json:"precpu_stats"`
MemoryStats struct {
Usage uint64 `json:"usage"`
Limit uint64 `json:"limit"`
Stats map[string]uint64 `json:"stats"`
} `json:"memory_stats"`
}
Stats is the subset of GET /containers/{id}/stats we use (raw counters; CPU% is computed from deltas between successive one-shot samples).
func (Stats) CPUPercentBetween ¶
CPUPercentBetween computes instantaneous CPU% from this sample's counters versus a previous sample's counters (Docker's formula). prevTotal/prevSystem are the previous one-shot's cpu_usage.total_usage / system_cpu_usage. Returns 0 when no meaningful delta exists yet (first sample).
Source Files