tagwright/core
Shared Go building blocks for the tagwright suite. The first piece is
runtime, a container-runtime abstraction over Docker and Podman. It talks to a
Docker Engine API-compatible socket and exposes the operations the suite's tools
need: list and inspect containers, watch the socket for lifecycle events, read
compose project/service labels, stop and start containers, exec into them, and a
set of normalized Container and Mount types so callers do not deal in
engine-specific shapes. A single request-and-mapping core is shared by a Docker
adapter and a Podman adapter that differ only in their default socket path and
how they read compose identity off a container's labels.
This module is a leaf: its only non-stdlib dependency is the Docker SDK. It was
extracted from ballast so a second consumer can share the same abstraction.
Install
go get github.com/tagwright/core
Import it as github.com/tagwright/core/runtime.
Optional capabilities
The base Runtime interface is the stable contract every adapter satisfies:
list, inspect, watch, exec, stop, start, kill, restart, and close. Capabilities
added after v0.2.0 land as separate optional interfaces rather than new
Runtime methods, so a new capability never breaks an existing consumer's mock
or alternate Runtime implementation. A consumer type-asserts for the
capability it wants:
if ni, ok := rt.(runtime.NetworkInspector); ok {
nets, err := ni.ListNetworks(ctx)
// ...
}
NetworkInspector (v0.3.0): ListNetworks(ctx) returns each network's subnet
CIDRs, driver, internal flag, and labels, for classifying a destination as
own-network, LAN, or internet. Both the Docker and Podman adapters satisfy it.
Provisioner (v0.4.0): stand up and tear down throwaway objects to prove a
restore in a sandbox with no path to production. PullImage, CreateNetwork
(always internal, no external routing), RemoveNetwork, CreateVolume,
RemoveVolume, CreateContainer (volume mounts, on a network, no published
ports, created but started only on request), and RemoveContainer (with its
anonymous volumes). Every create spec carries a Labels map so a caller can
find and sweep orphans after a crash. The caller owns teardown, not core.
Both the Docker and Podman adapters satisfy it. This is the surface
ballast's ballast verify command drives.
Normalized types
Container: id, name, state, labels, mounts, compose project and service,
image, log driver, env, health, and Networks.
ContainerNetwork: one network a container is attached to, and the IP
addresses it holds on that network.
Network: a network's name, id, driver, internal flag, subnet CIDRs, and
labels.
Mount: a normalized bind, tmpfs, or named-volume mount.
Versions
- v0.4.0: provisioning. The
Provisioner optional capability
(PullImage, CreateNetwork, RemoveNetwork, CreateVolume,
RemoveVolume, CreateContainer, RemoveContainer) with its NetworkSpec,
VolumeSpec, ContainerSpec, and VolumeMount spec types, for standing up
a throwaway restore sandbox on an isolated network. Adds an optional
ExecSpec.Stdin field so Exec can pipe a dump into a restoring process
(nil keeps the prior behavior). Both changes are additive: the Runtime
interface is unchanged.
- v0.3.0: network introspection.
NetworkInspector.ListNetworks, Network,
ContainerNetwork, and Container.Networks, for egress classification.
- v0.2.0:
Kill and Restart, and Container gains image, log driver, env,
and health.
- v0.1.0: initial extraction from ballast. The
Runtime abstraction over Docker
and Podman with normalized Container and Mount types.
Testing
Coverage is documented honestly in docs/TESTING.md, broken
down by capability and by engine: what is proven against a live socket, what is
compile-verified only, and what is still untested against a real Podman host.
The security posture, and what a consumer is granting when it hands core a
runtime socket, is written up in docs/SECURITY.md.
Licensed under GPL-3.0-or-later. See LICENSE.