docker

package
v0.17.0 Latest Latest
Warning

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

Go to latest
Published: Oct 10, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package docker launches a session worker as a psyb0t/peen sibling container.

The container runs the same `peen worker` command a native worker runs, so a Docker worker is the same program in a different environment rather than a remote tool backend.

Every daemon call goes through the Client interface in this file. The interface is the seam a real daemon client implements, which is what lets the launch rules, mount construction, host identity, and ownership-safe lifecycle be tested without a daemon. It is not a simulation of Docker.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func SocketGID

func SocketGID(socketPath string) int

SocketGID reports the group that owns the Docker socket.

A host-like profile mounts that socket into the worker, and the worker account needs this group to use it. Zero means the group could not be read, which refuses such a profile rather than launching a worker that cannot use the socket it was given.

Types

type Client

type Client interface {
	// CreateContainer creates without starting and returns the container ID.
	CreateContainer(
		ctx context.Context,
		request CreateRequest,
	) (string, error)

	// AttachStdin writes the launch document to the created container's stdin,
	// which is how a Docker worker receives its credential without it ever
	// appearing in the container's command line or environment.
	AttachStdin(
		ctx context.Context,
		containerID string,
		document []byte,
	) error

	// PullImage fetches a reference the daemon does not already hold.
	//
	// The Engine API's container create does not pull, unlike the docker CLI,
	// which pulls on a 404 and retries. A controller that never pulls cannot
	// start a worker on a host that has not seen the image before.
	PullImage(ctx context.Context, reference string) error

	// StreamLogs follows one container's combined stdout and stderr until the
	// container exits or the reader is closed. The worker's records reach the
	// controller's own sinks this way, because a worker never receives the
	// audit directory and cannot write to it itself.
	StreamLogs(
		ctx context.Context,
		containerID string,
	) (io.ReadCloser, error)

	StartContainer(ctx context.Context, containerID string) error
	StopContainer(ctx context.Context, containerID string) error
	RemoveContainer(ctx context.Context, containerID string) error
	InspectContainer(
		ctx context.Context,
		containerID string,
	) (ContainerState, error)

	// InspectImage reports one image's local ID and its repository digests.
	// The launcher uses it to record what actually ran, which a container
	// inspect cannot give: that call returns a local image ID, not a digest.
	InspectImage(
		ctx context.Context,
		reference string,
	) (ImageIdentity, error)
}

Client is the daemon surface this package needs.

It is deliberately small. Every method here is one the launcher actually calls, so a fake implements exactly the daemon behavior under test.

func NewDaemonClient

func NewDaemonClient(socketPath string) (Client, error)

NewDaemonClient opens a client for the controller's own Docker socket.

type ContainerState

type ContainerState struct {
	ID string

	// Running distinguishes a container still serving its session from one
	// that exited while the controller was away.
	Running bool

	// ExitCode is meaningful only when Running is false.
	ExitCode int

	// ImageID is the daemon's local content ID for the image this container
	// runs. It is not a repository digest, and the launcher does not record it
	// as one.
	ImageID string

	// Labels carry the ownership marks the controller checks before acting.
	Labels map[string]string
}

ContainerState is what the daemon reports about one container.

type CreateRequest

type CreateRequest struct {
	// Name is deterministic: peen-worker-<session-uuid>.
	Name string

	Image string

	// Entrypoint overrides the image's own entrypoint. BuildCreateRequest never
	// sets it, so a worker always runs the image's Peen entrypoint and its
	// privilege drop. It exists for the image-entrypoint contract test, which
	// keeps that entrypoint and replaces only the program it finally execs.
	Entrypoint []string

	// Command is the worker subcommand. The image never decides what to run.
	Command []string

	Mounts []worker.Mount

	// User is root only while the image entrypoint reconciles the host account
	// and drops to it. The agent itself never runs as this user.
	User string

	// Groups are supplementary group IDs the worker needs, such as the Docker
	// socket's group when the profile mounts it.
	Groups []string

	// Env carries HOME, USER, LOGNAME, the configuration directory, and the
	// launch document path. It never carries the credential itself.
	Env map[string]string

	// WorkingDirectory is the session workspace at its literal host path.
	WorkingDirectory string

	// NetworkDisabled asks the daemon for an isolated network.
	NetworkDisabled bool

	// NoNewPrivileges prevents a non-escalating worker from gaining privilege
	// after the entrypoint has dropped to the host account.
	NoNewPrivileges bool

	// Labels are exactly peen.managed and peen.session.
	Labels map[string]string
}

CreateRequest is one fully resolved worker container launch.

Every field comes from operator configuration and the controller's own host identity. Nothing here is taken from model output or a client request.

func BuildCreateRequest

func BuildCreateRequest(spec LaunchSpec) (CreateRequest, error)

BuildCreateRequest turns operator configuration and the controller's host identity into one container launch.

Paths are literal. The workspace, the global configuration, the worker socket root, and every extra mount appear inside the worker at the same absolute path they have on the host, so paths in prompts, hooks, logs, and tool calls stay truthful. The only relocation is one an operator wrote as a mount target.

The launch document is not built into the container. It goes in over stdin after creation, so the credential never appears in the command line, the environment, or any image layer.

type HostIdentity

type HostIdentity struct {
	Username  string
	GroupName string
	UID       int
	GID       int
	Home      string

	// SupplementaryGIDs are the extra groups the worker needs, such as the
	// Docker socket's group when a host-like profile mounts it.
	SupplementaryGIDs []int
}

HostIdentity is the account a Docker worker runs as.

It is the control user's own identity, so files a worker creates in the workspace are owned by the same account that owns the workspace on the host. There is no fallback to an image-local user or a fixed UID: an incomplete identity refuses the launch instead.

func CurrentHostIdentity

func CurrentHostIdentity() (HostIdentity, error)

CurrentHostIdentity reads the control process's own account.

The lookup fails when the process runs as a UID with no passwd entry, which is what `docker run --user uid:gid` produces against an image that does not carry that account. The error names the two variables that resolve it, because the underlying message reports only the unknown id.

func CurrentHostIdentityWithOverride

func CurrentHostIdentityWithOverride(
	username string,
	home string,
) (HostIdentity, error)

CurrentHostIdentityWithOverride returns the controller process identity, using an explicit username and home when the process has no passwd entry.

`docker run --user uid:gid` is the correct way to preserve host ownership, but the numeric identity commonly does not exist in the image's passwd database. A Docker controller supplies PEEN_HOST_USERNAME and PEEN_HOST_HOME for that case. They must be supplied together. Native controllers leave both empty and keep the operating system lookup as the source of truth.

func (HostIdentity) BootstrapEnvironment

func (i HostIdentity) BootstrapEnvironment(groups []string) map[string]string

BootstrapEnvironment tells the image entrypoint which host account to create or reconcile before it drops to it, including the supplementary groups this launch resolved. Every Docker worker gets these values because a bare numeric UID and GID do not make the host username available inside the image.

func (HostIdentity) Environment

func (i HostIdentity) Environment() map[string]string

Environment is the identity as the worker's own process sees it.

func (HostIdentity) Groups

func (i HostIdentity) Groups() []string

Groups renders the supplementary groups the worker needs.

func (HostIdentity) User

func (i HostIdentity) User() string

User renders the identity as the daemon's "uid:gid" user form.

func (HostIdentity) Validate

func (i HostIdentity) Validate() error

Validate refuses an identity a worker cannot safely run as.

type ImageIdentity

type ImageIdentity struct {
	ID string

	// RepoDigests are the immutable repository references this image is known
	// by, in `repository@sha256:...` form. An image built locally and never
	// pushed or pulled reports none.
	RepoDigests []string
}

ImageIdentity is what the daemon reports about one image.

ID is the daemon's local content ID. It is deliberately separate from RepoDigests, because a local ID is not a registry digest and recording one in the other's place would claim an identity nobody can resolve later.

type LaunchSpec

type LaunchSpec struct {
	Document worker.LaunchDocument
	Profile  worker.Profile
	Identity HostIdentity

	// RuntimeEnvironment is the controller-selected subset of its deployment
	// environment a worker needs to build the same agent runtime. It includes
	// provider credentials by their operator-chosen names, never the private
	// worker launch credential. Controller-only keys are rejected below.
	RuntimeEnvironment map[string]string

	// Image overrides the profile's image. A deployment that pins one
	// release-matched psyb0t/peen image sets it once rather than repeating it
	// in every profile.
	Image string

	// DockerSocketGID is the host GID of the Docker socket. It is required
	// when the profile mounts that socket, because the worker account needs
	// the group to use it.
	DockerSocketGID int
}

LaunchSpec is everything needed to build one worker container.

type Launcher

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

Launcher starts session workers as psyb0t/peen containers.

func New

func New(options Options) (*Launcher, error)

New validates the launcher's dependencies.

The host identity is checked here rather than at launch, so a deployment whose control account cannot own worker files fails at startup instead of on the first session.

func (*Launcher) Kind

func (l *Launcher) Kind() worker.Kind

Kind reports the profile kind this launcher serves.

func (*Launcher) Launch

func (l *Launcher) Launch(
	ctx context.Context,
	request worker.LaunchRequest,
) (worker.Process, error)

Launch creates, feeds, and starts one worker container.

The launch document goes in over stdin after creation, so the credential is never part of the container's command, environment, labels, or image.

type Options

type Options struct {
	// Client is the daemon surface. A launcher without one cannot exist,
	// which is how the absence of Docker authority becomes a startup decision
	// rather than a per-launch surprise.
	Client Client

	// Identity is the host account every worker runs as.
	Identity HostIdentity

	// Image overrides the image for every Docker profile. Empty leaves each
	// profile's image in effect. A local development image is valid here.
	Image string

	// DockerSocketGID is the host GID of the Docker socket, needed only by a
	// profile that mounts it into the worker.
	DockerSocketGID int

	// RuntimeEnvironment is the controller-selected configuration and named
	// provider credential set a Docker worker needs. It excludes controller
	// state and authority, and New validates it before any session launches.
	RuntimeEnvironment map[string]string
}

Options builds a Docker worker launcher.

Jump to

Keyboard shortcuts

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