runenv

type Clock ¶

type Clock interface {
	Now() time.Time
	Since(time.Time) time.Duration
	Sleep(context.Context, time.Duration) error
}

Clock is the time seam.

type Code ¶

type Code string

Code is a stable, grep-able failure identity printed with every error.

const (
	CodeConfigInvalid         Code = "CI_CONFIG_INVALID"
	CodeProfileUnsupported    Code = "CI_PROFILE_UNSUPPORTED"
	CodeGinkgoReportInvalid   Code = "CI_GINKGO_REPORT_INVALID"
	CodeDockerWSLDistroGone   Code = "CI_DOCKER_WSL_DISTRO_MISSING"
	CodeDockerWSLInstall      Code = "CI_DOCKER_WSL_INSTALL_FAILED"
	CodeDockerWSLDaemon       Code = "CI_DOCKER_WSL_DAEMON_NOT_READY"
	CodeDockerCLIChecksum     Code = "CI_DOCKER_CLI_CHECKSUM_MISMATCH"
	CodeDockerWSLSSHNotReady  Code = "CI_DOCKER_WSL_SSH_NOT_READY"
	CodeDockerWSLSSHAuth      Code = "CI_DOCKER_WSL_SSH_AUTH_FAILED"
	CodeDockerWSLEndpoint     Code = "CI_DOCKER_WSL_ENDPOINT_MISMATCH"
	CodeDockerWSLOracle       Code = "CI_DOCKER_WSL_ORACLE_INVALID"
	CodeDockerWSLSetupTimeout Code = "CI_DOCKER_WSL_SETUP_TIMEOUT"
	CodeDockerWSLCleanup      Code = "CI_DOCKER_WSL_CLEANUP_FAILED"
)

type Command ¶

type Command struct {
	Path    string
	Args    []string
	Env     []string // NAME=value overlay; replaces same-named parent entries
	Dir     string
	Timeout time.Duration
	// Stdout and Stderr optionally receive output live, in addition to the
	// tail-capped capture returned in CommandResult.
	Stdout io.Writer
	Stderr io.Writer
}

Command describes one subprocess. Env is an overlay applied to the parent environment of that process only; nothing mutates the global environment.

type CommandResult ¶

type CommandResult struct {
	ExitCode int // -1 when the process did not exit normally
	Stdout   string
	Stderr   string
	TimedOut bool
}

CommandResult is the bounded outcome of a Command. Stdout and Stderr hold only the last maxCaptureBytes of output.

type Dependencies ¶

type Dependencies struct {
	Run   Runner
	Files FileStore
	Clock Clock
	Net   Dialer
	HTTP  Downloader

	GOOS    string
	Environ func() []string
	Out     io.Writer
	Err     io.Writer
}

Dependencies bundles every side effect so command logic is unit-testable.

func NewDefaultDependencies() *Dependencies

type Dialer ¶

type Dialer interface {
	DialContext(ctx context.Context, network, address string) (net.Conn, error)
}

Dialer is the network seam used for readiness probes.

type Downloader ¶

type Downloader interface {
	Download(ctx context.Context, rawURL string, dst io.Writer, maxBytes int64) error
}

Downloader fetches an HTTPS resource into dst, failing if it exceeds maxBytes.

type ExecRunner ¶

type ExecRunner struct{}

ExecRunner runs real subprocesses with bounded capture and a hard timeout.

func (ExecRunner) Run(ctx context.Context, c Command) (CommandResult, error)

type FileStore ¶

type FileStore interface {
	ReadFile(name string) ([]byte, error)
	WriteFile(name string, data []byte, perm fs.FileMode) error
	AppendFile(name string, data []byte, perm fs.FileMode) error
	MkdirAll(path string, perm fs.FileMode) error
	Stat(name string) (fs.FileInfo, error)
	Remove(name string) error
	RemoveAll(path string) error
}

FileStore is the filesystem seam. WriteFile is atomic (temp file + rename).

type GitHubFiles ¶

type GitHubFiles struct {
	EnvPath  string
	PathPath string
	Files    FileStore
	Out      io.Writer
}

GitHubFiles appends to the GITHUB_ENV and GITHUB_PATH special files. An empty path means the helper runs outside Actions: the value is printed (redacted) to Out instead, so local runs need no GitHub context.

func (g GitHubFiles) AddPath(dir string) error

func (g GitHubFiles) SetEnv(name, value string) error

type OsFileStore ¶

type OsFileStore struct{}

func (OsFileStore) AppendFile(name string, data []byte, perm fs.FileMode) error

func (OsFileStore) MkdirAll(p string, perm fs.FileMode) error

func (OsFileStore) ReadFile(name string) ([]byte, error)

func (OsFileStore) Remove(name string) error

func (OsFileStore) RemoveAll(p string) error

func (OsFileStore) Stat(name string) (fs.FileInfo, error)

func (OsFileStore) WriteFile(name string, data []byte, perm fs.FileMode) (err error)

type Runner ¶

type Runner interface {
	Run(context.Context, Command) (CommandResult, error)
}

Runner executes a Command. A nonzero exit status is reported through CommandResult.ExitCode, not through the error; the error is reserved for failure to start or for cancellation of the parent context.

type StageError ¶

type StageError struct {
	Code     Code
	Stage    string
	Elapsed  time.Duration
	ExitCode *int
	Artifact string
	Detail   string // already redacted and bounded
	Err      error
}

StageError is a typed, stage-scoped failure. Fields other than Code, Stage and Err are optional and rendered only when set.

func ConfigError(format string, args ...any) *StageError

func NewStageError(code Code, stage string, err error) *StageError

func UnsupportedProfileError(format string, args ...any) *StageError

func (e *StageError) Error() string

func (e *StageError) Unwrap() error

func (e *StageError) WithArtifact(path string) *StageError

func (e *StageError) WithDetail(output string) *StageError

func (e *StageError) WithElapsed(d time.Duration) *StageError

func (e *StageError) WithExitCode(code int) *StageError