Help us shape the future of Go! Take the 2026 Go Developer Survey

forge_lib_docker

package
v0.57.29 Latest Latest
Warning

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

 Go to latest Published: Oct 26, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source 
const ConfigID = ControllerID

ConfigID is the string used to identify this config object.

View Source 
const ControllerID = "forge/lib/docker"

ControllerID is the ID of the controller.

Variables

View Source 
var Version = controller.MustParseVersion("0.0.1")

Version is the version of the controller implementation.

Functions

func ApplyWorkdirBind 

func ApplyWorkdirBind(conf *Config, hostPath, containerPath string) error

ApplyWorkdirBind adds the single POSIX bind mount for a supervised Workdir. A Docker bind mount bypasses the FSHandle writer, so its caller must flush and prove quiescence before collecting diff evidence.

func BuildDockerEnv 

func BuildDockerEnv(conf *Config) []string

BuildDockerEnv renders the complete configured CLI environment as KEY=value arguments.

Types

type Admission 

type Admission interface {
	// Reserve debits the declared target request for one Execution attempt.
	// It waits while the Worker admits no new work, and returns an error only
	// for a failed request or an ended context.
	Reserve(ctx context.Context, executionKey string, conf *Config) (Reservation, error)
}

Admission reserves Worker capacity before a Docker runtime is created.

type Config 

type Config struct {

	// DockerPath is the docker CLI executable path.
	// Defaults to "docker" when empty.
	DockerPath string `protobuf:"bytes,1,opt,name=docker_path,json=dockerPath,proto3" json:"dockerPath,omitempty"`
	// DockerEnv is the explicit environment for the docker CLI subprocess.
	// No host environment is inherited unless configured here.
	DockerEnv map[string]string `` /* 175-byte string literal not displayed */
	// Image is the container image to create.
	Image string `protobuf:"bytes,3,opt,name=image,proto3" json:"image,omitempty"`
	// Workdir is the container working directory.
	Workdir string `protobuf:"bytes,4,opt,name=workdir,proto3" json:"workdir,omitempty"`
	// Env is the explicit environment passed to the container.
	// No host environment is inherited.
	Env map[string]string `` /* 147-byte string literal not displayed */
	// Mounts is the ordered list of bind mounts passed to docker create.
	Mounts []*Mount `protobuf:"bytes,6,rep,name=mounts,proto3" json:"mounts,omitempty"`
	// Command is appended after the image as the container command.
	Command []string `protobuf:"bytes,7,rep,name=command,proto3" json:"command,omitempty"`
	// StopTimeoutSeconds is passed to docker stop when cancellation stops a
	// container. Docker's default stop timeout is used when zero.
	StopTimeoutSeconds uint32 `protobuf:"varint,8,opt,name=stop_timeout_seconds,json=stopTimeoutSeconds,proto3" json:"stopTimeoutSeconds,omitempty"`
	// MilliCpu is the CPU requested by this target in milli-cores.
	MilliCpu uint64 `protobuf:"varint,9,opt,name=milli_cpu,json=milliCpu,proto3" json:"milliCpu,omitempty"`
	// MemoryBytes is the memory requested by this target in bytes.
	MemoryBytes uint64 `protobuf:"varint,10,opt,name=memory_bytes,json=memoryBytes,proto3" json:"memoryBytes,omitempty"`
	// OutputDir is the container directory where the command writes outputs.
	// Each file named after an entry in outputs becomes that output after a zero
	// exit. Required when outputs is set.
	OutputDir string `protobuf:"bytes,11,opt,name=output_dir,json=outputDir,proto3" json:"outputDir,omitempty"`
	// Outputs lists the output names the command may write to output_dir.
	// A file absent after exit leaves its output unset.
	Outputs []string `protobuf:"bytes,12,rep,name=outputs,proto3" json:"outputs,omitempty"`
	// contains filtered or unexported fields
}

Config configures the docker CLI exec controller. Creates one container, starts it, waits for completion, and stops it on execution cancellation.

func (*Config) CloneMessageVT 

func (m *Config) CloneMessageVT() protobuf_go_lite.CloneMessage

func (*Config) CloneVT 

func (m *Config) CloneVT() *Config

func (*Config) EqualMessageVT 

func (this *Config) EqualMessageVT(thatMsg any) bool

func (*Config) EqualVT 

func (this *Config) EqualVT(that *Config) bool

func (*Config) EqualsConfig 

func (c *Config) EqualsConfig(other config.Config) bool

EqualsConfig checks if the other config is equal.

func (*Config) GetCommand 

func (x *Config) GetCommand() []string

func (*Config) GetConfigID 

func (c *Config) GetConfigID() string

GetConfigID returns the unique string for this configuration type.

func (*Config) GetDockerEnv 

func (x *Config) GetDockerEnv() map[string]string

func (*Config) GetDockerPath 

func (x *Config) GetDockerPath() string

func (*Config) GetEnv 

func (x *Config) GetEnv() map[string]string

func (*Config) GetImage 

func (x *Config) GetImage() string

func (*Config) GetMemoryBytes 

func (x *Config) GetMemoryBytes() uint64

func (*Config) GetMilliCpu 

func (x *Config) GetMilliCpu() uint64

func (*Config) GetMounts 

func (x *Config) GetMounts() []*Mount

func (*Config) GetOutputDir 

func (x *Config) GetOutputDir() string

func (*Config) GetOutputs 

func (x *Config) GetOutputs() []string

func (*Config) GetStopTimeoutSeconds 

func (x *Config) GetStopTimeoutSeconds() uint32

func (*Config) GetWorkdir 

func (x *Config) GetWorkdir() string

func (*Config) MarshalJSON 

func (x *Config) MarshalJSON() ([]byte, error)

MarshalJSON marshals the Config to JSON.

func (*Config) MarshalProtoJSON 

func (x *Config) MarshalProtoJSON(s *json.MarshalState)

MarshalProtoJSON marshals the Config message to JSON.

func (*Config) MarshalProtoText 

func (x *Config) MarshalProtoText() string

func (*Config) MarshalToSizedBufferVT 

func (m *Config) MarshalToSizedBufferVT(dAtA []byte) (int, error)

func (*Config) MarshalToVT 

func (m *Config) MarshalToVT(dAtA []byte) (int, error)

func (*Config) MarshalVT 

func (m *Config) MarshalVT() (dAtA []byte, err error)

func (*Config) ProtoMessage 

func (*Config) ProtoMessage()

func (*Config) Reset 

func (x *Config) Reset()

func (*Config) SizeVT 

func (m *Config) SizeVT() (n int)

func (*Config) String 

func (x *Config) String() string

func (*Config) UnmarshalJSON 

func (x *Config) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals the Config from JSON.

func (*Config) UnmarshalProtoJSON 

func (x *Config) UnmarshalProtoJSON(s *json.UnmarshalState)

UnmarshalProtoJSON unmarshals the Config message from JSON.

func (*Config) UnmarshalVT 

func (m *Config) UnmarshalVT(dAtA []byte) error

func (*Config) Validate 

func (c *Config) Validate() error

Validate validates the configuration.

type Config_DockerEnvEntry 

type Config_DockerEnvEntry struct {
	Key   string `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
	Value string `protobuf:"bytes,2,opt,name=value,proto3" json:"value,omitempty"`
	// contains filtered or unexported fields
}

func (*Config_DockerEnvEntry) GetKey 

func (x *Config_DockerEnvEntry) GetKey() string

func (*Config_DockerEnvEntry) GetValue 

func (x *Config_DockerEnvEntry) GetValue() string

func (*Config_DockerEnvEntry) MarshalJSON 

func (x *Config_DockerEnvEntry) MarshalJSON() ([]byte, error)

MarshalJSON marshals the Config_DockerEnvEntry to JSON.

func (*Config_DockerEnvEntry) MarshalProtoJSON 

func (x *Config_DockerEnvEntry) MarshalProtoJSON(s *json.MarshalState)

MarshalProtoJSON marshals the Config_DockerEnvEntry message to JSON.

func (*Config_DockerEnvEntry) MarshalProtoText 

func (x *Config_DockerEnvEntry) MarshalProtoText() string

func (*Config_DockerEnvEntry) ProtoMessage 

func (*Config_DockerEnvEntry) ProtoMessage()

func (*Config_DockerEnvEntry) Reset 

func (x *Config_DockerEnvEntry) Reset()

func (*Config_DockerEnvEntry) String 

func (x *Config_DockerEnvEntry) String() string

func (*Config_DockerEnvEntry) UnmarshalJSON 

func (x *Config_DockerEnvEntry) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals the Config_DockerEnvEntry from JSON.

func (*Config_DockerEnvEntry) UnmarshalProtoJSON 

func (x *Config_DockerEnvEntry) UnmarshalProtoJSON(s *json.UnmarshalState)

UnmarshalProtoJSON unmarshals the Config_DockerEnvEntry message from JSON.

type Config_EnvEntry 

type Config_EnvEntry struct {
	Key   string `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
	Value string `protobuf:"bytes,2,opt,name=value,proto3" json:"value,omitempty"`
	// contains filtered or unexported fields
}

func (*Config_EnvEntry) GetKey 

func (x *Config_EnvEntry) GetKey() string

func (*Config_EnvEntry) GetValue 

func (x *Config_EnvEntry) GetValue() string

func (*Config_EnvEntry) MarshalJSON 

func (x *Config_EnvEntry) MarshalJSON() ([]byte, error)

MarshalJSON marshals the Config_EnvEntry to JSON.

func (*Config_EnvEntry) MarshalProtoJSON 

func (x *Config_EnvEntry) MarshalProtoJSON(s *json.MarshalState)

MarshalProtoJSON marshals the Config_EnvEntry message to JSON.

func (*Config_EnvEntry) MarshalProtoText 

func (x *Config_EnvEntry) MarshalProtoText() string

func (*Config_EnvEntry) ProtoMessage 

func (*Config_EnvEntry) ProtoMessage()

func (*Config_EnvEntry) Reset 

func (x *Config_EnvEntry) Reset()

func (*Config_EnvEntry) String 

func (x *Config_EnvEntry) String() string

func (*Config_EnvEntry) UnmarshalJSON 

func (x *Config_EnvEntry) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals the Config_EnvEntry from JSON.

func (*Config_EnvEntry) UnmarshalProtoJSON 

func (x *Config_EnvEntry) UnmarshalProtoJSON(s *json.UnmarshalState)

UnmarshalProtoJSON unmarshals the Config_EnvEntry message from JSON.

type Controller 

type Controller struct {
	// contains filtered or unexported fields
}

Controller implements the docker CLI execution controller.

func NewController 

func NewController(
	le *logrus.Entry,
	bus bus.Bus,
	conf *Config,
	admission Admission,
) *Controller

NewController constructs a docker controller.

func (*Controller) Close 

func (c *Controller) Close() error

Close releases any resources used by the controller.

func (*Controller) Execute 

func (c *Controller) Execute(ctx context.Context) (retErr error)

Execute executes the docker container lifecycle.

func (*Controller) GetControllerInfo 

func (c *Controller) GetControllerInfo() *controller.Info

GetControllerInfo returns information about the controller.

func (*Controller) HandleDirective 

func (c *Controller) HandleDirective(ctx context.Context, inst directive.Instance) ([]directive.Resolver, error)

HandleDirective asks if the handler can resolve the directive.

func (*Controller) InitForgeExecController 

func (c *Controller) InitForgeExecController(
	ctx context.Context,
	inputVals forge_target.InputMap,
	handle forge_target.ExecControllerHandle,
) error

InitForgeExecController initializes the Forge execution controller.

type DockerRunner 

type DockerRunner interface {
	// Run executes the named binary with args and env, returning stdout.
	Run(ctx context.Context, name string, args []string, env []string) ([]byte, error)
	// Logs reads both output streams from a completed container.
	Logs(ctx context.Context, name, containerID string, env []string) ([]byte, []byte, error)
}

DockerRunner executes one docker CLI command and returns its stdout. The env parameter is the complete subprocess environment; implementations must not inherit the host environment.

type ExecDockerRunner 

type ExecDockerRunner struct{}

ExecDockerRunner runs docker CLI commands as subprocesses with an explicitly constructed environment. Run returns stdout for parsing and includes stderr in failure errors, so Docker warnings cannot corrupt parsed values such as container IDs. Logs returns both streams separately.

func NewExecDockerRunner 

func NewExecDockerRunner() *ExecDockerRunner

NewExecDockerRunner constructs a subprocess docker runner.

func (*ExecDockerRunner) Logs 

func (r *ExecDockerRunner) Logs(ctx context.Context, name, containerID string, env []string) ([]byte, []byte, error)

Logs reads a container's stdout and stderr without mixing the streams.

func (*ExecDockerRunner) Run 

func (r *ExecDockerRunner) Run(ctx context.Context, name string, args []string, env []string) ([]byte, error)

Run executes the named binary with args and env, returning stdout.

type Factory 

type Factory struct {
	// contains filtered or unexported fields
}

Factory constructs a docker controller.

func NewWorkerFactory 

func NewWorkerFactory(bus bus.Bus, admission Admission) *Factory

NewWorkerFactory binds Docker execution to one Worker's admission.

The name differs from NewFactory on purpose: Bldr bundles every package that declares NewFactory as a bus-level factory, but this one is registered only by the Worker that owns the admission.

func (*Factory) Construct 

func (t *Factory) Construct(
	ctx context.Context,
	conf config.Config,
	opts controller.ConstructOpts,
) (controller.Controller, error)

Construct constructs the associated controller given configuration.

func (*Factory) ConstructConfig 

func (t *Factory) ConstructConfig() config.Config

ConstructConfig constructs an instance of the controller configuration.

func (*Factory) GetConfigID 

func (t *Factory) GetConfigID() string

GetConfigID returns the configuration ID for the controller.

func (*Factory) GetControllerID 

func (t *Factory) GetControllerID() string

GetControllerID returns the unique ID for the controller.

func (*Factory) GetVersion 

func (t *Factory) GetVersion() controller.Version

GetVersion returns the version of this controller.

type Mount 

type Mount struct {

	// HostPath is the host source path.
	HostPath string `protobuf:"bytes,1,opt,name=host_path,json=hostPath,proto3" json:"hostPath,omitempty"`
	// ContainerPath is the target path inside the container.
	ContainerPath string `protobuf:"bytes,2,opt,name=container_path,json=containerPath,proto3" json:"containerPath,omitempty"`
	// ReadOnly marks the bind mount read-only.
	ReadOnly bool `protobuf:"varint,3,opt,name=read_only,json=readOnly,proto3" json:"readOnly,omitempty"`
	// contains filtered or unexported fields
}

Mount configures one docker bind mount.

func (*Mount) CloneMessageVT 

func (m *Mount) CloneMessageVT() protobuf_go_lite.CloneMessage

func (*Mount) CloneVT 

func (m *Mount) CloneVT() *Mount

func (*Mount) EqualMessageVT 

func (this *Mount) EqualMessageVT(thatMsg any) bool

func (*Mount) EqualVT 

func (this *Mount) EqualVT(that *Mount) bool

func (*Mount) GetContainerPath 

func (x *Mount) GetContainerPath() string

func (*Mount) GetHostPath 

func (x *Mount) GetHostPath() string

func (*Mount) GetReadOnly 

func (x *Mount) GetReadOnly() bool

func (*Mount) MarshalJSON 

func (x *Mount) MarshalJSON() ([]byte, error)

MarshalJSON marshals the Mount to JSON.

func (*Mount) MarshalProtoJSON 

func (x *Mount) MarshalProtoJSON(s *json.MarshalState)

MarshalProtoJSON marshals the Mount message to JSON.

func (*Mount) MarshalProtoText 

func (x *Mount) MarshalProtoText() string

func (*Mount) MarshalToSizedBufferVT 

func (m *Mount) MarshalToSizedBufferVT(dAtA []byte) (int, error)

func (*Mount) MarshalToVT 

func (m *Mount) MarshalToVT(dAtA []byte) (int, error)

func (*Mount) MarshalVT 

func (m *Mount) MarshalVT() (dAtA []byte, err error)

func (*Mount) ProtoMessage 

func (*Mount) ProtoMessage()

func (*Mount) Reset 

func (x *Mount) Reset()

func (*Mount) SizeVT 

func (m *Mount) SizeVT() (n int)

func (*Mount) String 

func (x *Mount) String() string

func (*Mount) UnmarshalJSON 

func (x *Mount) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals the Mount from JSON.

func (*Mount) UnmarshalProtoJSON 

func (x *Mount) UnmarshalProtoJSON(s *json.UnmarshalState)

UnmarshalProtoJSON unmarshals the Mount message from JSON.

func (*Mount) UnmarshalVT 

func (m *Mount) UnmarshalVT(dAtA []byte) error

type Reservation 

type Reservation interface {
	// Launch records stop custody and fences Docker create and start against drain.
	// A drain that fences the launch returns forge_runtime.ErrCapacityDraining
	// and voids the reservation; the caller releases it and reserves again.
	Launch(ctx context.Context, createAndStart func(runtimeName string) error) error
	// Release stops the runtime and credits capacity once.
	Release(ctx context.Context) error
}

Reservation fences one named Docker runtime and releases its capacity.

type Stopper 

type Stopper struct {
	// contains filtered or unexported fields
}

Stopper stops Docker runtimes by their persisted CLI identity.

func NewStopper 

func NewStopper(runner DockerRunner) *Stopper

NewStopper constructs an idempotent Docker runtime stopper.

func (*Stopper) StopRuntime 

func (s *Stopper) StopRuntime(ctx context.Context, rt forge_runtime.BackendRuntimeIdentity) (bool, error)

StopRuntime confirms that the named Docker container has stopped or gone.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.