Documentation
¶
Overview ¶
The ADR-055 phase-2 build primitive, agent side: a BuildKit build driven against the LOCAL daemon's embedded builder — the exact rail `docker build` uses — with the context read from the mounted tree. The image lands in the daemon's store (moby exporter); only plain-text progress leaves the server.
Package hostops is the ADR-054 host-operations adapter: the typed file primitives the control plane executes on a server's /var/lib/akerdock tree through the agent channel — the same rail, vocabulary discipline and mandatory-agent stance as the Docker runtime (ADR-051/052). The agent side is pure Go on the bind-mounted tree: the helper image is distroless, so there is no shell, and nothing outside the enumerated vocabulary runs.
The ADR-054 pipe primitives, agent side: container exec ↔ host file with compression, host file ↔ presigned URL. Pure Go — the helper image has no shell, no gzip, no curl — and strictly local: the payload moves between the container, the mounted tree and the bucket without ever crossing the control plane.
Index ¶
- Constants
- type Local
- func (l *Local) BuildImage(ctx context.Context, p agentwire.ImageBuildParams) (io.ReadCloser, error)
- func (l *Local) Chown(_ context.Context, p agentwire.FileChownParams) error
- func (l *Local) CopyFile(_ context.Context, p agentwire.FileCopyParams) error
- func (l *Local) EnsureDir(_ context.Context, p agentwire.DirEnsureParams) error
- func (l *Local) ExecToFile(ctx context.Context, p agentwire.ExecToFileParams) (agentwire.ExecToFileResult, error)
- func (l *Local) FileToExec(ctx context.Context, p agentwire.FileToExecParams) (agentwire.FileToExecResult, error)
- func (l *Local) FileToURL(ctx context.Context, p agentwire.FileToURLParams) error
- func (l *Local) HashFile(_ context.Context, path string) (agentwire.FileHashResult, error)
- func (l *Local) ReadFile(_ context.Context, p agentwire.FileReadParams) (agentwire.FileReadResult, error)
- func (l *Local) Remove(_ context.Context, p agentwire.FileRemoveParams) error
- func (l *Local) Stat(_ context.Context, path string) (agentwire.FileStatResult, error)
- func (l *Local) URLToFile(ctx context.Context, p agentwire.URLToFileParams) error
- func (l *Local) WriteFile(_ context.Context, p agentwire.FileWriteParams) error
- type Ops
- type Sender
- type Source
Constants ¶
const Root = "/var/lib/akerdock"
Root is the only tree host-ops may touch. Anything outside it — agent provisioning, first-contact validation, break-glass — is SSH's remit.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Local ¶
type Local struct {
Root string
RT dockerruntime.Runtime
}
Local executes the vocabulary on the local filesystem — the agent side. Every path is resolved against Root before anything is touched; the guard is authoritative here, whatever the control plane sent. RT is the LOCAL Docker runtime the pipe primitives exec through; nil refuses them.
func DetectLocal ¶
func DetectLocal(rt dockerruntime.Runtime) *Local
DetectLocal returns the Local rooted at Root when the tree is present, nil when it is not — a helper created before the ADR-054 mount (spec < 7) has no host tree, and nil makes the executor answer that plainly instead of ENOENT-ing on every call. rt powers the pipe primitives.
func (*Local) BuildImage ¶
func (l *Local) BuildImage(ctx context.Context, p agentwire.ImageBuildParams) (io.ReadCloser, error)
BuildImage solves the dockerfile.v0 frontend over a gRPC session hijacked on the local Docker API — dockerd's embedded BuildKit, so caching, secrets and Dockerfile semantics are exactly `docker build`'s. Secrets arrive in the typed params and are attached as session secrets, mounted for single RUNs and never written to a layer (INV-003, §5.2).
func (*Local) ExecToFile ¶
func (l *Local) ExecToFile(ctx context.Context, p agentwire.ExecToFileParams) (agentwire.ExecToFileResult, error)
ExecToFile runs the exec and streams its stdout — gzipped on request — into the target file, hashing exactly what lands on disk.
func (*Local) FileToExec ¶
func (l *Local) FileToExec(ctx context.Context, p agentwire.FileToExecParams) (agentwire.FileToExecResult, error)
FileToExec streams the file — gunzipped on request — into the exec's stdin and reports its exit code with the merged output tail.
func (*Local) FileToURL ¶
FileToURL uploads the file with a plain PUT — the presigned URL arrived in the command body over the encrypted channel, never argv (INV-003). A non-2xx answer fails with the body's tail: an S3 error names its cause and carries no credential.
func (*Local) ReadFile ¶
func (l *Local) ReadFile(_ context.Context, p agentwire.FileReadParams) (agentwire.FileReadResult, error)
type Ops ¶
type Ops interface {
WriteFile(ctx context.Context, p agentwire.FileWriteParams) error
ReadFile(ctx context.Context, p agentwire.FileReadParams) (agentwire.FileReadResult, error)
Remove(ctx context.Context, p agentwire.FileRemoveParams) error
Stat(ctx context.Context, path string) (agentwire.FileStatResult, error)
Chown(ctx context.Context, p agentwire.FileChownParams) error
CopyFile(ctx context.Context, p agentwire.FileCopyParams) error
EnsureDir(ctx context.Context, p agentwire.DirEnsureParams) error
// The pipe primitives (tranche C): bulk transfers executed agent-side so
// the payload never crosses the control plane — a dump can be tens of
// gigabytes, and relaying it would make every backup depend on the
// instance's bandwidth. Only the typed verdict travels back.
ExecToFile(ctx context.Context, p agentwire.ExecToFileParams) (agentwire.ExecToFileResult, error)
FileToExec(ctx context.Context, p agentwire.FileToExecParams) (agentwire.FileToExecResult, error)
FileToURL(ctx context.Context, p agentwire.FileToURLParams) error
URLToFile(ctx context.Context, p agentwire.URLToFileParams) error
HashFile(ctx context.Context, path string) (agentwire.FileHashResult, error)
// BuildImage (ADR-055 phase 2) runs a BuildKit build against the local
// daemon — the context is a host path local to the agent — and returns
// its plain-text progress stream; the stream's terminal error is the
// build's failure.
BuildImage(ctx context.Context, p agentwire.ImageBuildParams) (io.ReadCloser, error)
}
Ops is the host-file vocabulary. Signatures speak the wire types directly: they ARE this vocabulary's SDK, exactly as the Docker SDK types are the runtime adapter's.
type Sender ¶
type Sender interface {
Command(ctx context.Context, method string, params any) (json.RawMessage, error)
Stream(ctx context.Context, method string, params any) (io.ReadCloser, error)
}
Sender carries typed commands to a server's agent — the unary calls and the one streamed build — satisfied by the same live and relayed connections the Docker runtime rides.
Source Files
Directories