command

package
v0.0.0-...-2fc0378 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: Apache-2.0 Imports: 78 Imported by: 0

Documentation

Overview

Package command defines the behavior of commands invoked by project configuration files.

Index

Constants

View Source
const (
	PASS = "PASS"
	FAIL = "FAIL"
	SKIP = "SKIP"
)

Variables

This section is empty.

Functions

func GetFullDisplayName

func GetFullDisplayName(cmdName, displayName string, blockInfo BlockInfo, funcInfo FunctionInfo) string

GetFullDisplayName returns the full, unambiguous display name for a command. cmdName is the type of command (e.g. shell.exec), displayName is the human-readable display name (if specified), or the command name (if no display name is given). blockInfo and funcInfo include contextual information about the block/func that the command is running in.

func GetWorkingDirectory

func GetWorkingDirectory(conf *internal.TaskConfig, path string) string

GetWorkingDirectory joins the conf.WorkDir A with B like this:

if B is relative, return A+B.
if B is absolute, return B.

We use this because B might be absolute.

func IsWorkdirBoundaryViolation

func IsWorkdirBoundaryViolation(conf *internal.TaskConfig, path string) bool

IsWorkdirBoundaryViolation returns true when a configured path resolves outside conf.WorkDir. It intentionally evaluates the configured path before legacy command-specific rewriting so telemetry captures tasks that request unsupported out-of-workdir paths, even if the command ultimately executes from a rewritten path under the workdir. Relative paths are resolved as GetWorkingDirectory resolves them, then filepath.Rel determines containment.

func ProcessVirtualTaskTestResultFiles

func ProcessVirtualTaskTestResultFiles(ctx context.Context, conf *internal.TaskConfig, logger client.LoggerProducer, info testresult.TestResultsInfo, taskCreatedAt, testResultsCreatedAt time.Time, groups []VirtualTaskTestResultFileGroup) (*apimodels.VirtualTaskTestResults, error)

ProcessVirtualTaskTestResultFiles parses the given test result file groups, uploads the test logs and test results to S3 on behalf of the virtual task identified by info, and returns the test result metadata.

func RegisterCommand

func RegisterCommand(name string, factory CommandFactory) error

func RegisteredCommandNames

func RegisteredCommandNames() []string

func SetWorkdirBoundaryAttribute

func SetWorkdirBoundaryAttribute(ctx context.Context, conf *internal.TaskConfig, paths ...string)

SetWorkdirBoundaryAttribute records whether any resolved path falls outside the task workdir on the span from the context. This is informational only; it does not block or error on violations.

func ToModelTestResults

func ToModelTestResults(results []*goTestResult, suiteName string) []testresult.TestResult

ToModelTestResults converts the implementation of LocalTestResults native to the goTest plugin to the implementation used by MCI tasks.

Types

type BlockInfo

type BlockInfo struct {
	// Block is the name of the block that the command is part of.
	Block BlockType
	// CmdNum is the ordinal of a command in the block.
	CmdNum int
	// TotalCmds is the total number of commands in the block.
	TotalCmds int
}

BlockInfo contains information about the enclosing block in which a function or standalone command runs. For example, this would contain information about the pre block that contains a particular shell.exec command.

type BlockType

type BlockType string

BlockType is the name of the block that a command runs in.

const (
	MainTaskBlock      BlockType = ""
	TaskTimeoutBlock   BlockType = "timeout"
	PreBlock           BlockType = "pre"
	SetupTaskBlock     BlockType = "setup_task"
	TeardownTaskBlock  BlockType = "teardown_task"
	SetupGroupBlock    BlockType = "setup_group"
	TeardownGroupBlock BlockType = "teardown_group"
	PostBlock          BlockType = "post"
)

type Command

type Command interface {
	// ParseParams takes a map of fields to values extracted from
	// the project config and passes them to the command. Any
	// errors parsing the information are returned.
	ParseParams(map[string]any) error

	// Execute runs the command using the agent's logger, communicator,
	// task config, and a channel for interrupting long-running commands.
	// Execute is called after ParseParams.
	Execute(context.Context, client.Communicator, client.LoggerProducer, *internal.TaskConfig) error

	// Name is the name of the command.
	Name() string

	// Type returns the command's type (e.g. system or test).
	Type() string
	// SetType sets the command's type (e.g. system or test).
	SetType(string)

	// FullDisplayName is the full display name for the command. The full
	// command name includes the command name (including the type of command and
	// the user-defined display name if any) as well as other relevant context
	// like the function and block the command runs in.
	FullDisplayName() string
	SetFullDisplayName(string)

	// IdleTimeout is the user-configurable timeout for how long an individual
	// command can run without writing output to the task logs. If the command
	// hits this timeout, then it will time out and stop early.
	// This timeout only applies in certain blocks, such as pre, setup group,
	// setup task, and the main task block.
	IdleTimeout() time.Duration
	SetIdleTimeout(time.Duration)

	// JasperManager is the Jasper process manager for the command. Jasper can
	// be used to run and manage processes that are started within commands.
	JasperManager() jasper.Manager
	SetJasperManager(jasper.Manager)

	// RetryOnFailure indicates whether the entire task should be retried if this command fails.
	RetryOnFailure() bool
	SetRetryOnFailure(bool)

	// FailureMetadataTags are user-defined tags which are not used directly by
	// Evergreen but can be used to allow users to set additional metadata about
	// the command/function if it fails.
	FailureMetadataTags() []string
	SetFailureMetadataTags([]string)
}

Command is an interface that defines a command A Command takes parameters as a map, and is executed after those parameters are parsed.

func MockCommandFactory

func MockCommandFactory() Command

MockCommandFactory is a factory used to produce a mock command for testing. should not be used in production.

func Render

func Render(c model.PluginCommandConf, project *model.Project, blockInfo BlockInfo) ([]Command, error)

Render takes a command specification and returns the commands to actually run. It resolves the command specification into either a single command (in the case of standalone command) or a list of commands (in the case of a function).

type CommandFactory

type CommandFactory func() Command

func GetCommandFactory

func GetCommandFactory(name string) (CommandFactory, bool)

type FunctionInfo

type FunctionInfo struct {
	// Function is the name of the function that the command is part of.
	Function string
	// SubCmdNum is the ordinal of the command within the function.
	SubCmdNum int
	// TotalSubCmds is the total number of sub-commands within the function.
	TotalSubCmds int
}

FunctionInfo contains information about the enclosing function in which a command runs. For example, this would contain information about the second shell.exec that runs in a function.

type VirtualTaskTestResultFileGroup

type VirtualTaskTestResultFileGroup struct {
	Type  string   `json:"type"`
	Files []string `json:"files"`
}

VirtualTaskTestResultFileGroup is a group of files of a single test result type.

type VirtualTaskTestResultsInput

type VirtualTaskTestResultsInput struct {
	Files     []VirtualTaskTestResultFileGroup `json:"files"`
	CreatedAt time.Time                        `json:"created_at,omitzero"`
}

VirtualTaskTestResultsInput describes the test result files to parse and upload for a virtual task.

func (VirtualTaskTestResultsInput) GetCreatedAt

func (tr VirtualTaskTestResultsInput) GetCreatedAt() time.Time

GetCreatedAt returns the time the test results were created.

func (VirtualTaskTestResultsInput) Validate

func (tr VirtualTaskTestResultsInput) Validate() error

Validate checks that the test results input is well-formed.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址