runenv

package
v0.0.3 Latest Latest
Warning

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

Go to latest
Published: Sep 28, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package runenv manages the Docker env where agent runs execute.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FreePort

func FreePort() (uint16, error)

FreePort finds a random, unused TCP port on the host by asking the OS to bind to port 0 and reading back the assigned port. The listener is closed before returning, so the port is free for the caller to use.

func PullImage added in v0.0.2

func PullImage(ctx context.Context, cli *client.Client, imageRef string, policy agentconfig.ImagePullPolicy) error

PullImage pulls imageRef according to policy using the Docker API client. An empty policy is treated as ImagePullPolicyIfNotPresent.

Types

type Container

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

Container is an abstraction around Docker's container objects. It primarily adds logging and utility functions specific to abyss.

func NewContainer

func NewContainer(docker *DockerClient, containerID string) *Container

NewContainer initializes a new container.

func (*Container) CopyFileFromHost

func (d *Container) CopyFileFromHost(
	ctx context.Context, content []byte, containerPath string, mode os.FileMode,
) error

CopyFileFromHost copies a single file's content into the container identified by containerID. Parent directories of containerPath are created as needed.

func (*Container) CopyFromHost

func (d *Container) CopyFromHost(ctx context.Context, containerID, hostPath, containerDir string) error

CopyFromHost copies the file or directory at hostPath into the container identified by containerID, placing it under containerDir. Parent directories of containerDir that do not already exist inside the container are created. The basename of hostPath is preserved, so a host path of "/tmp/foo.txt" copied into "/opt/app" lands at "/opt/app/foo.txt".

func (*Container) CreateAgentStartFile added in v0.0.2

func (d *Container) CreateAgentStartFile(ctx context.Context) error

CreateAgentStartFile creates an empty start file inside the container at the default start file path, signaling that the agent should begin its work.

func (*Container) ExecBash

func (c *Container) ExecBash(ctx context.Context, script string) (stdout, stderr string, err error)

ExecBash runs script inside the container identified by containerID using "bash -c". It returns the script's stdout and stderr. If the script exits with a non-zero status, the returned error reports the exit code and the output is still returned so callers can inspect it.

func (*Container) ID

func (c *Container) ID() string

ID returns the Docker ID for the container.

func (*Container) Stop

func (c *Container) Stop(ctx context.Context, timeout time.Duration, remove bool) error

Stop stops and removes the container identified by containerID. It first sends a SIGTERM, waiting up to timeout for the container to exit, then falls back to SIGKILL if it is still running. The container is removed afterwards regardless of whether it exited on its own.

type ContainerBuildStep added in v0.0.2

type ContainerBuildStep func(context.Context, *Container) error

ContainerBuildStep runs after the Docker container has been started. They have access to the container's filesystem, shell, etc, but can't change the container's configuration like networking.

func NewParallelStep added in v0.0.3

func NewParallelStep(inner ...ContainerBuildStep) ContainerBuildStep

NewParallelStep returns a new ParallelStep with the given inner steps.

func WithCopyFiles added in v0.0.2

func WithCopyFiles(files []agentconfig.FileCopyConfig) ContainerBuildStep

WithCopyFiles returns a build step that copies each file declared in the agent config into the container. Files with Type "inline" use Source as the file contents; files with Type "path" read the contents from the host path in Source. Each file is written to its Target path inside the container, creating parent directories as needed. When a "path" entry points to a directory, the directory is copied recursively into the container at Target.

func WithSetupScripts added in v0.0.2

func WithSetupScripts(scripts []agentconfig.SetupScriptsConfig) ContainerBuildStep

WithSetupScripts returns a build step that copies each setup script into the container and executes it with bash. Scripts with Type "inline" use Source as the script contents; scripts with Type "file" read the contents from the host path in Source. Each script is written to a temporary path inside the container, made executable, and run before the agent starts.

type ContainerBuilder added in v0.0.2

type ContainerBuilder struct {
	ConfigPath string
	// contains filtered or unexported fields
}

ContainerBuilder accumulates build steps and starts a container. TODO this should be two separate "config-builder" and "container-builder" parts.

func NewContainerBuilder added in v0.0.2

func NewContainerBuilder(
	configPath string, config *ContainerConfig, steps ...ContainerPreBuildStep,
) (*ContainerBuilder, error)

NewContainerBuilder creates a builder, applying any pre-build steps to the config.

func (*ContainerBuilder) AddStep added in v0.0.2

func (b *ContainerBuilder) AddStep(step ContainerBuildStep)

AddStep appends a single build step to the builder.

func (*ContainerBuilder) AddSteps added in v0.0.2

func (b *ContainerBuilder) AddSteps(newSteps ...ContainerBuildStep)

AddSteps appends multiple build steps to the builder.

func (*ContainerBuilder) Build added in v0.0.2

Build starts the container and runs each build step against it.

type ContainerConfig added in v0.0.2

type ContainerConfig struct {
	Host     *container.HostConfig
	Config   *container.Config
	Endpoint *ContainerEndpoint

	// Name is the name to assign to the container. An empty name lets Docker
	// generate one.
	Name string

	// ContainerPort is the port the container exposes to the host.
	ContainerPort uint16

	// HostPort is the host port bound to ContainerPort. 0 lets Docker assign a
	// free port.
	HostPort uint16
}

ContainerConfig holds the Docker host and container configuration used to build a container.

func (*ContainerConfig) Validate added in v0.0.2

func (c *ContainerConfig) Validate() *types.ValidationError

Validate ensures the required host and container configs are present.

type ContainerEndpoint

type ContainerEndpoint struct {
	// ContainerID is the ID of the started container.
	ContainerID string
	// IP is the address the host should connect to.
	IP string
	// Port is the host port bound to the container's exposed port.
	Port uint16
}

ContainerEndpoint describes how the host can reach a started container.

func (ContainerEndpoint) String

func (e ContainerEndpoint) String() string

String returns the endpoint as an "ip:port" address.

type ContainerPreBuildStep added in v0.0.2

type ContainerPreBuildStep func(*ContainerConfig) error

ContainerPreBuildStep is a step that runs before the container is started. They can modify the Docker configuration, but can't run bash scripts in the container or things like that.

func WithEnv added in v0.0.2

func WithEnv(envString string) ContainerPreBuildStep

WithEnv returns a pre-build step that appends an environment variable.

func WithExposeContainerPort added in v0.0.2

func WithExposeContainerPort(containerPort int) ContainerPreBuildStep

WithExposeContainerPort exposes the given port on the built container.

func WithExposePort added in v0.0.2

func WithExposePort(port network.Port) ContainerPreBuildStep

WithExposePort returns a pre-build step that marks a port as exposed.

func WithHostBind added in v0.0.2

func WithHostBind(from string, to string) ContainerPreBuildStep

WithHostBind returns a pre-build step that binds a host path into the container. Returns errors when it is unable to get a clean, absolute path to either of the provided paths.

func WithHostMounts added in v0.0.2

func WithHostMounts(cfg *agentconfig.DockerConfig) ContainerPreBuildStep

WithHostMounts creates a ContainerPreBuildStep that configures the container to mount any host mounts in the config.

Paths are normalized as part of this step, so relative paths are fine and will be resolved to absolute paths.

func WithImage added in v0.0.2

func WithImage(imgName string) ContainerPreBuildStep

WithImage returns a pre-build step that sets the container image.

func WithLabel added in v0.0.2

func WithLabel(label, value string) ContainerPreBuildStep

WithLabel returns a pre-build step that sets a container label.

type DockerClient

type DockerClient struct {
	Client *client.Client
	// contains filtered or unexported fields
}

DockerClient wraps the Docker SDK client and provides helpers for managing containers in a run environment.

func NewDockerClient

func NewDockerClient() (*DockerClient, error)

NewDockerClient creates a DockerClient configured from the environment (DOCKER_HOST, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_TLS_VERIFY).

func (*DockerClient) AbyssContainers

func (d *DockerClient) AbyssContainers(ctx context.Context) ([]container.Summary, error)

AbyssContainers lists containers that have the `abyss` label set.

func (*DockerClient) Close

func (d *DockerClient) Close() error

Close releases resources held by the underlying Docker client.

func (*DockerClient) GetContainer added in v0.0.2

func (d *DockerClient) GetContainer(containerID string) *Container

GetContainer returns a *Container. It does not validate that the provided containerID actually exists.

func (*DockerClient) StartContainer

func (d *DockerClient) StartContainer(
	ctx context.Context,
	config *container.Config,
	hostConfig *container.HostConfig,
	labels map[string]string,
	name string,
	containerPort uint16,
	hostPort uint16,
) (*Container, ContainerEndpoint, error)

StartContainer creates and starts a Docker container with the provided configuration, labels, name, and port mappings.

type ErrInvalidContainerMetadata added in v0.0.3

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

ErrInvalidContainerMetadata is returned when a container's abyss labels are malformed or absent.

func NewErrInvalidContainerMetadata added in v0.0.3

func NewErrInvalidContainerMetadata(msg string) *ErrInvalidContainerMetadata

NewErrInvalidContainerMetadata builds an error for invalid or missing container labels.

func (*ErrInvalidContainerMetadata) Error added in v0.0.3

Error formats the invalid metadata error.

type LabelMetadata added in v0.0.3

type LabelMetadata struct {
	AbyssVersion    string
	AgentConfigPath string
	AgentConfigHash string
}

LabelMetadata holds the abyss metadata stored in container labels.

func GetLabelMetadata added in v0.0.3

func GetLabelMetadata(summary *container.Summary) (*LabelMetadata, error)

GetLabelMetadata extracts abyss metadata from a container's labels. Returns an error for missing labels

func (*LabelMetadata) AddToMap added in v0.0.3

func (l *LabelMetadata) AddToMap(underlying map[string]string)

AddToMap writes the metadata labels into the given map.

func (*LabelMetadata) ToMap added in v0.0.3

func (l *LabelMetadata) ToMap() map[string]string

ToMap returns the metadata as a map of container labels.

type ParallelStep added in v0.0.3

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

ParallelStep runs multiple ContainerBuildSteps in parallel to improve startup performance.

func (*ParallelStep) Run added in v0.0.3

func (p *ParallelStep) Run(ctx context.Context, container *Container) error

Run implements ContainerBuildStep by running all of the inner steps in parallel and returning after they are all complete.

Jump to

Keyboard shortcuts

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