gomoteclient

type BuilderType string

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

type CommandError struct {
	// Args is the (secret-redacted) argument vector that was executed.
	Args []string
	// ExitCode is the process exit code, or -1 if the process did not start.
	ExitCode int
	// Stderr is the captured standard error of the command.
	Stderr string
	// Err is the underlying execution error.
	Err error
}

type Config struct {
	// BinaryPath, if set, is an explicit path to a gomote binary. It is
	// validated and resolved to an absolute path. When empty, the client
	// resolves the binary from PATH and then, if AllowBootstrap is true,
	// bootstraps one into SandboxDir.
	BinaryPath string

	// SandboxDir is the directory used to build and cache a bootstrapped
	// gomote. When empty it defaults to <os.UserCacheDir>/gomoteclient.
	SandboxDir string

	// GomoteVersion is the module version installed during bootstrap, for
	// example a tag or pseudo-version of golang.org/x/build. When empty,
	// bootstrap resolves "@latest" (not reproducible; logged as a warning).
	GomoteVersion string

	// AllowBootstrap permits the client to download and build gomote when it
	// is not otherwise available. It defaults to false: a missing binary is
	// then a hard error rather than an implicit network build.
	AllowBootstrap bool

	// Server overrides the coordinator address (gomote's global -server flag,
	// for example "gomote.golang.org:443"). When empty, gomote's built-in
	// default is used. The value is validated to reject argument injection.
	Server string

	// Retry governs transient-failure handling. The zero value is replaced by
	// DefaultRetryPolicy; individual zero fields are filled with defaults.
	Retry RetryPolicy

	// Env is the explicit environment passed to the gomote subprocess. When
	// nil, a curated allowlist is derived from the host environment (see the
	// package documentation). Provide a value to fully control isolation.
	Env []string

	// DefaultTimeout bounds a single command attempt when neither the caller's
	// context nor RetryPolicy.PerAttempt sets a deadline. Zero means no
	// implicit deadline.
	DefaultTimeout time.Duration

	// Logger receives structured, secret-redacted diagnostics. When nil, logs
	// are discarded.
	Logger *slog.Logger
}

type CreateOptions struct {
	// BuilderType is the gomote builder type, e.g. "gotip-linux-amd64". Required.
	BuilderType BuilderType
	// SetUpEnv are environment variables applied to the new instance via -e.
	SetUpEnv []EnvVar
	// Setup requests that gomote push GOROOT and build the Go toolchain on the
	// new instance (the -setup flag). It is off by default.
	Setup bool
	// RetrySafe permits transparent retries of Create. It is off by default
	// because a retried create can leak buildlets; enable it only when the
	// caller cleans up orphans.
	RetrySafe bool
}

type EnvVar struct {
	Key   string
	Value string
}

type GetOptions struct {
	// Dir is the remote directory to archive (-dir). Optional.
	Dir string
	// Output is the local path to write the downloaded .tar.gz to. Required.
	Output string
}

type Info struct {
	// BinaryPath is the absolute path to the resolved gomote binary.
	BinaryPath string
	// BinarySource indicates how the binary was located.
	BinarySource Source
	// SandboxDir is the configured sandbox directory (may be empty).
	SandboxDir string
	// SandboxReady reports whether the binary was built into the sandbox.
	SandboxReady bool
	// GomoteVersion is the module version when known (bootstrap builds), else "".
	GomoteVersion string
	// ActiveInstances are the IDs of instances created via this Client that
	// have not been destroyed, sorted lexically.
	ActiveInstances []string
	// Env is the redacted environment passed to the gomote subprocess.
	Env []string
}

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

type InstanceInfo struct {
	ID  string
	Raw string // the full, unparsed line as printed by gomote list
}

type JitterMode int

type LsOptions struct {
	// Dir is the remote directory to list, relative to the work dir. Optional.
	Dir string
	// Recursive lists directories recursively (-R).
	Recursive bool
	// Digest requests file digests (-d).
	Digest bool
	// Skip is a list of relative directories to skip (-skip), joined with ",".
	Skip []string
}

type Option func(*Config)

type PutOptions struct {
	// Source is the local file to upload. Required.
	Source string
	// Dest is the destination path on the instance. Optional.
	Dest string
	// Mode optionally sets the destination Unix file mode (-mode). When zero,
	// gomote defaults to the source file's mode.
	Mode os.FileMode
}

type PutTarOptions struct {
	// Dir is the destination directory on the instance (-dir).
	Dir string
	// File is the local .tar.gz archive to upload. Required.
	File string
}

type RetryPolicy struct {
	// MaxAttempts is the total number of attempts (not counting only retries).
	MaxAttempts int
	// BaseDelay is the first backoff interval.
	BaseDelay time.Duration
	// MaxDelay caps the exponential backoff interval.
	MaxDelay time.Duration
	// Multiplier is the exponential growth factor between attempts.
	Multiplier float64
	// Jitter selects the randomization strategy.
	Jitter JitterMode
	// PerAttempt optionally bounds each individual attempt.
	PerAttempt time.Duration
	// Retryable classifies a failed result as transient (retryable) or not.
	// When nil, defaultRetryable is used.
	Retryable func(res RunResult, err error) bool
}

type RunOptions struct {
	// Dir is the working directory on the instance (-dir).
	Dir string
	// Path sets the remote PATH (-path); elements are joined with ",". The
	// gomote tokens $PATH and $WORKDIR are passed through verbatim, and the
	// special element "EMPTY" runs with no $PATH at all.
	Path []string
	// Env are environment variables for the command (-e).
	Env []EnvVar
	// System runs the command in the system context rather than the work
	// directory (-system). gomote also implies this when Command is absolute.
	System bool
	// Debug requests debug information about the command before it runs (-debug).
	Debug bool
	// Firewall enables the outbound firewall for the instance lifetime (-firewall).
	Firewall bool
	// BuilderEnv selects an alternate builder to emulate; it must share the same
	// underlying host type (-builderenv).
	BuilderEnv string
	// Until reruns the command until its output matches this regexp (-until).
	// Bound it with the context to avoid running forever.
	Until string
	// Command is the remote program to execute. Required.
	Command string
	// Args are the remote program's arguments. They may begin with "-".
	Args []string
}

type RunResult struct {
	Stdout   []byte
	Stderr   []byte
	ExitCode int
}

type Source int