engineclient

Documentation

Overview

Package engineclient owns the long-lived cavet-engine container for one repository: lifecycle, exec plumbing, report copy-out, and path translation (cli-spec §10). It knows Docker and paths; it never parses findings.

Index

• func ContainerName(root string) string
• func ContainerToHost(root, containerPath string) string
• func HostToContainer(root, hostPath string) string
• func RepoRelative(containerPath, target string) string
• type Client
  • func New(image, pinnedDigest, root string) *Client
  • func (c *Client) CopyOut(ctx context.Context, containerPath string) ([]byte, error)
  • func (c *Client) EnsureRunning(ctx context.Context) error
  • func (c *Client) Exec(ctx context.Context, cmd []string) (ExecResult, error)
  • func (c *Client) ImageDigest(ctx context.Context, ref string) (string, error)
  • func (c *Client) ImagePresent(ctx context.Context) error
  • func (c *Client) Name() string
  • func (c *Client) NextScanDir() string
  • func (c *Client) Ping(ctx context.Context) error
  • func (c *Client) Pull(ctx context.Context, ref string) (io.ReadCloser, error)
  • func (c *Client) Remove(ctx context.Context) error
  • func (c *Client) Status(ctx context.Context) (running, healthy bool, imageID string, err error)
• type ExecResult

Functions

func ContainerName

func ContainerName(root string) string

ContainerName derives the stable per-repository container name.

func ContainerToHost

func ContainerToHost(root, containerPath string) string

ContainerToHost maps a /workspace-relative container path back to the host.

func HostToContainer

func HostToContainer(root, hostPath string) string

HostToContainer maps a host path under the repository root into the container mount. Paths outside the mount map to "".

func RepoRelative

func RepoRelative(containerPath, target string) string

RepoRelative strips a scan target prefix (/workspace or /scan/<n>) from a container path, yielding a repository-relative slash path. Already-relative paths pass through with any leading slash trimmed.

Types

type Client

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

func New

func New(image, pinnedDigest, root string) *Client

New builds a client. pinnedDigest may be empty in development (local image tag, no drift enforcement); production always pins (spec §3.4).

func (*Client) CopyOut

func (c *Client) CopyOut(ctx context.Context, containerPath string) ([]byte, error)

CopyOut retrieves a single file's bytes from the container. Reports are megabytes at worst (spike §5); read into memory and discard (cli-spec §10.3).

func (*Client) EnsureRunning

func (c *Client) EnsureRunning(ctx context.Context) error

EnsureRunning guarantees a healthy container: create if absent, restart if stopped (transparently, spec §7.1), verify the digest first. Digest drift is a hard stop, never silent scanning on a stale engine (cli-spec §10.2).

func (*Client) Exec

func (c *Client) Exec(ctx context.Context, cmd []string) (ExecResult, error)

Exec runs cmd in the container with stdout/stderr demultiplexed. Workdir is /workspace. Exit codes are data (gitleaks exits 1 on leaks — cli-spec §7); transport errors are the only error returns.

func (*Client) ImageDigest

func (c *Client) ImageDigest(ctx context.Context, ref string) (string, error)

ImageDigest returns the image's registry digest when it has one (locally built images have none) — the pin `cavet init` records.

func (*Client) ImagePresent

func (c *Client) ImagePresent(ctx context.Context) error

ImagePresent reports whether the engine image exists locally.

func (*Client) Name

func (c *Client) Name() string

func (*Client) NextScanDir

func (c *Client) NextScanDir() string

NextScanDir allocates a fresh staging directory inside the container. The name mixes the clock (unique across processes — the container outlives CLI invocations, so a bare counter would collide across commands) with a local counter (Windows clock granularity can repeat adjacent nanoseconds — measured). Dirs die with the container (cli-spec §6).

func (*Client) Ping

func (c *Client) Ping(ctx context.Context) error

Ping reports whether a Docker daemon is reachable.

func (*Client) Pull

func (c *Client) Pull(ctx context.Context, ref string) (io.ReadCloser, error)

Pull streams the image from its registry. Progress reporting is the caller's job; drain the reader to completion or the pull aborts.

func (*Client) Remove

func (c *Client) Remove(ctx context.Context) error

Remove force-removes the container; the container holds no unique state (cli-spec §5 engine stop).

func (*Client) Status

func (c *Client) Status(ctx context.Context) (running, healthy bool, imageID string, err error)

Status reports container state without side effects. healthy means the healthcheck currently passes (warm).

type ExecResult

type ExecResult struct {
	Stdout []byte
	Stderr []byte
	Code   int
}

ExecResult carries a container command's captured streams and exit code.