dockerlib

package module
v0.3.7 Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2026 License: MIT Imports: 46 Imported by: 0

Documentation

Overview

Package dockerlib is the activity-and-resource library over docker on a machine: install the engine, run containers. All bodies execute inside the per-(agent × run) container on the machine — with the machine's docker socket under their feet; the run workflow only orchestrates.

The durable half of dockerlib: containers, volumes, and networks are ENTITY RECORDS — owned in the tree, cascaded, transferable to a stand — whose lifecycle activities run on the machine's own (agent × run) executor. The executor lives while these records do.

Index

Constants

View Source
const (
	ContainerKind entity.KindName = "docker"
	VolumeKind    entity.KindName = "docker-volume"
	NetworkKind   entity.KindName = "docker-network"
)

Entity kinds.

Variables

This section is empty.

Functions

func Build

func Build(spec BuildSpec) activity.Call[BuildReport]

Build assembles an image with the machine's own buildx — full BuildKit (cache export, multi-stage, secrets) with nothing wrapped: the CLI the machine already has (Install brings it) does the work, the digest comes back through --metadata-file, never log parsing.

func Container

func Container(ctx pipeline.Context, agent pipeline.Agent, spec Spec, opts ...pipeline.ResourceOption) pipeline.Resource[Info]

Container declares a container on the agent's machine as an ORDINARY resource: an entity record in the tree — owned, cascaded, transferable to a stand. Its lifecycle runs on this agent's own executor, which lives while the record does.

func Install

func Install() activity.Call[InstallReport]

Install brings the docker engine onto the machine — converging: an engine that is already there is reported, not reinstalled. A library verb is a Call: run it with pipelineactivity.Activity on one agent or pipelineactivity.ActivityAll on a selection.

func Job added in v0.3.0

func Job(spec JobSpec) activity.Call[JobReport]

Job runs a container to completion on the machine: pull, create, start, stream its output to the run's logs line by line, wait, remove. It is the one-shot counterpart of Container — a verb, not a resource: nothing is owned, nothing stays behind but the log file.

Whether a second execution is acceptable is the CALLER'S knowledge: a job that loads data or sends a message wants activity.WithGuarantee(activity.AtMostOnce).

func Network

Network declares a docker network on the agent's machine as an ordinary resource — an owned entity record; it dies with its owner.

func Volume

Volume declares a docker volume on the agent's machine as an ordinary resource — an owned entity record; the data dies with its owner. The spec is docker's OWN type.

Types

type BuildReport

type BuildReport struct {
	Digest string   `json:"digest,omitempty"`
	Tags   []string `json:"tags,omitempty"`
}

BuildReport is the build's outcome: the immutable identity of what was built. The local image stays on the machine as cache — it is not a resource and owns nothing.

type BuildSpec

type BuildSpec struct {
	// Context is the build context directory.
	Context string `json:"context"`
	// File is the Dockerfile path; empty means <Context>/Dockerfile.
	File string `json:"file,omitempty"`
	// Tags to apply ("registry/name:tag").
	Tags []string `json:"tags,omitempty"`
	// Push pushes the tags after a successful build.
	Push bool `json:"push,omitempty"`
	// Target builds a specific stage.
	Target string `json:"target,omitempty"`
	// BuildArgs are --build-arg pairs.
	BuildArgs map[string]string `json:"buildArgs,omitempty"`
	// CacheFrom / CacheTo are buildx cache specs
	// ("type=registry,ref=...").
	CacheFrom []string `json:"cacheFrom,omitempty"`
	CacheTo   []string `json:"cacheTo,omitempty"`
}

BuildSpec describes one image build. Paths (Context, File) must be machine-valid — put the context under machine.Workspace() and this holds by construction (same absolute path in the container, on the machine, and for the daemon).

type Info

type Info struct {
	Id string `json:"id"`
}

Info is the output of a running container resource.

type InstallReport

type InstallReport struct {
	Version string `json:"version"`
	// Installed is false when the engine was already there.
	Installed bool `json:"installed"`
}

InstallReport is what Install returns.

type JobReport added in v0.3.0

type JobReport struct {
	ExitCode int `json:"exitCode"`
	// Stdout is the container's stdout, bounded to the first 256 KiB —
	// enough for a machine-readable answer (a JSON line, a version).
	Stdout string `json:"stdout,omitempty"`
	// Tail is the end of the merged stdout+stderr, last 16 KiB: where a
	// tool prints its summary or its error.
	Tail string `json:"tail,omitempty"`
	// LogPath is the full merged output on the machine — hand it to
	// artifact.FromAgentFile to keep it.
	LogPath string `json:"logPath,omitempty"`
}

JobReport is what came back from the container. A non-zero ExitCode is an OUTCOME, not an activity failure: the job ran, the caller decides what its exit status means. The activity fails only when the container could not be run at all.

type JobSpec added in v0.3.0

type JobSpec struct {
	// Name is the container's name on the machine. A leftover container
	// of the same name is replaced — the name is the job's identity.
	Name   string                `json:"name"`
	Config *container.Config     `json:"config"`
	Host   *container.HostConfig `json:"host,omitempty"`
}

JobSpec describes one THROWAWAY container with docker's OWN types — the same pair Container takes. Everything docker already has a word for stays in that word: the command is Config.Cmd, the environment is Config.Env, files reach the container through Host.Mounts (bind the directory a file resource wrote to), the network is Host.NetworkMode.

type NetworkInfo

type NetworkInfo struct {
	Id   string `json:"id"`
	Name string `json:"name"`
}

NetworkInfo is the output of a network resource.

type NetworkSpec

type NetworkSpec struct {
	Name    string                `json:"name"`
	Options network.CreateOptions `json:"options"`
}

NetworkSpec names a network with docker's own creation options.

type Spec

type Spec struct {
	Name   string                `json:"name"`
	Config *container.Config     `json:"config"`
	Host   *container.HostConfig `json:"host,omitempty"`
	// Scrape is a prometheus metrics endpoint the container exposes
	// (e.g. "http://localhost:9187/metrics"); the executor pulls it and
	// ships the samples — histograms and summaries included — as this
	// container's own metrics (Р-Н27).
	Scrape string `json:"scrape,omitempty"`
	// ScrapeEvery is the scrape step: 15s when zero, never under 1s. It
	// is the scrape's own and does not move the stats beat.
	ScrapeEvery time.Duration `json:"scrapeEvery,omitempty"`
}

Spec describes one container with docker's OWN types — structures their authors made, not ours.

type VolumeInfo

type VolumeInfo struct {
	Name       string `json:"name"`
	Mountpoint string `json:"mountpoint,omitempty"`
}

VolumeInfo is the output of a volume resource.

Directories

Path Synopsis
Package dockertest models Docker resource declarations and capability publication for pipeline tests.
Package dockertest models Docker resource declarations and capability publication for pipeline tests.
internal
contract
Package contract shares Docker resource wire types with adapters.
Package contract shares Docker resource wire types with adapters.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL