Documentation
¶
Overview ¶
Package docker launches a session worker as a psyb0t/peen sibling container.
The container runs the same `peen worker` command a control 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 ¶
- func ReadonlyProxySocketPath(document worker.LaunchDocument) string
- func SocketGID(socketPath string) int
- func ValidateFullAccessSocket(agentSpaces *worker.AgentSpaceSet, socketGID int) error
- type Client
- type ContainerState
- type CreateRequest
- type HostIdentity
- type ImageIdentity
- type LaunchSpec
- type Launcher
- type Options
- type ReadonlyProxy
- type ReadonlyProxyStarter
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ReadonlyProxySocketPath ¶ added in v0.20.0
func ReadonlyProxySocketPath(document worker.LaunchDocument) string
ReadonlyProxySocketPath is where the controller runs a `docker: readonly` worker's proxy: beside the worker socket in the session's own directory, so the worker reaches it through the mount it already has and no other session can.
func SocketGID ¶
SocketGID reports the group that owns the Docker socket.
A `docker: full` 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.
func ValidateFullAccessSocket ¶ added in v0.19.0
func ValidateFullAccessSocket( agentSpaces *worker.AgentSpaceSet, socketGID int, ) error
ValidateFullAccessSocket refuses, at startup, a `docker: full` agent space whose socket group the worker account cannot be given. A socket owned by group 0 is such a case, and finding it at the first launch would leave a controller that reports ready and cannot start that worker.
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 ¶
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 agent space 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
// NetworkMode is the network the agent space names: none, bridge, or host.
NetworkMode worker.NetworkMode
// 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 `docker: full` 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. Host 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
AgentSpace worker.AgentSpace
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
// ImageOverride replaces every agent space's image. A deployment that pins
// one release-matched image sets it once rather than repeating it in every
// profile.
ImageOverride string
// ImageFallback is the image a worker runs when there is no override and
// the agent space names none. It must never take precedence over a
// profile's own image.
ImageFallback string
// DockerSocketPath is the host socket the controller resolved. A
// `docker: full` agent space mounts it at the conventional path inside
// the worker.
DockerSocketPath string
// DockerSocketGID is the host GID of the Docker socket. It is required
// when the agent space 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 ¶
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) 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
// ImageOverride replaces the image of every Docker profile. Empty leaves
// each profile's image in effect. A local development image is valid here.
ImageOverride string
// ImageFallback is the image a profile that names none runs. It never
// replaces a profile's own image.
ImageFallback string
// DockerSocketPath is the controller's own Docker socket. A `docker: full`
// profile mounts it, and a `docker: readonly` proxy forwards to it.
DockerSocketPath string
// DockerSocketGID is the host GID of the Docker socket, needed only by a
// profile with `docker: full`.
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
// StartReadonlyProxy starts the proxy a `docker: readonly` worker reaches
// the daemon through. Nil starts the real dockerproxy.Server.
StartReadonlyProxy ReadonlyProxyStarter
}
Options builds a Docker worker launcher.
type ReadonlyProxy ¶ added in v0.20.0
type ReadonlyProxy interface {
Close() error
}
ReadonlyProxy is a running `docker: readonly` proxy as the launcher holds it. Close stops it, ends its open connections, and removes its socket.
type ReadonlyProxyStarter ¶ added in v0.20.0
type ReadonlyProxyStarter func( ctx context.Context, socketPath, upstreamSocketPath string, ) (ReadonlyProxy, error)
ReadonlyProxyStarter starts a proxy that listens on socketPath and forwards read requests to the daemon at upstreamSocketPath.