runner

package
v0.35.0 Latest Latest
Warning

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

 Go to latest Published: Apr 27, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var LogLevelEnvName = "CI_FUNCS_LOG_LEVEL"
View Source 
var StepDefinedInGitLabJob = NewNamedStepReference("", nil)

StepDefinedInGitLabJob is a step defined in a GitLab jobs using the run: syntax or STEPS: variable

Functions

func NewStepRunnerError added in v0.34.0 

func NewStepRunnerError(format string, args ...any) error

NewStepRunnerError creates a StepRunnerError from a format string.

func WithStepsCtxExportFile added in v0.7.0 

func WithStepsCtxExportFile(exportFile *StepFile) func(*StepsContext)

func WithStepsCtxOutputFile added in v0.7.0 

func WithStepsCtxOutputFile(outputFile *StepFile) func(*StepsContext)

func WithStepsCtxStepResults added in v0.7.0 

func WithStepsCtxStepResults(results map[string]*proto.StepResult) func(*StepsContext)

Types

type BuiltinContext added in v0.33.0 

type BuiltinContext interface {
	GetInput(name string, kind Kind) (*structpb.Value, error)
	GetInputWithDefault(name string, kind Kind, inputSpec map[string]*proto.Spec_Content_Input) (*structpb.Value, error)
	GetEnv(name string) string
	GetEnvs() map[string]string
	GetEnvList() []string
	LookupEnv(key string) (string, bool)
	WorkDir() string
	ProjectDir() string
	Pipe() (io.Writer, io.Writer)
	GetExportFile() string
	GetOutputFile() string
	GetJobVars() map[string]*structpb.Value
	ListenCancel(context.Context) (context.Context, context.CancelFunc)
	GracefulExitDelay() time.Duration
}

BuiltinContext provides the execution context for builtin functions. It exposes only the minimal set of methods a builtin needs, preventing access to other steps' results or internal runner state.

func NewBuiltinContext added in v0.33.0 

func NewBuiltinContext(sc *StepsContext) BuiltinContext

NewBuiltinContext extracts only the data a builtin needs from a StepsContext. The returned value holds no reference to StepsContext or its step results. It does retain a reference to GlobalContext via LookupEnv so that builtins can see environment variables exported by prior steps.

type Describer 

type Describer interface {
	Describe() string
}

Describer types know how to describe themselves in a language to be read by humans

type Environment 

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

Environment represents environment variables. Environment variables are used in places such as the step export_file, step definitions with ENV, and OS environment. Environment does not merge maps, and so does not lose information. Merging of environments occurs when values are retrieved. An environment can be added as "lexical scope", these values have higher precedence when looking up a variable. Mutations to the environment take precedence over initialized variables, most recent mutations have the highest precedence

func GlobalEnvironment added in v0.6.0 

func GlobalEnvironment(parent *Environment, jobVars JobVariables) (*Environment, error)

GlobalEnvironment sets environment variables that are always available for any step

func NewEmptyEnvironment 

func NewEmptyEnvironment() *Environment

func NewEnvironment 

func NewEnvironment(vars map[string]string) *Environment

func NewEnvironmentFromOS 

func NewEnvironmentFromOS(rejectIf ...func(string) bool) (*Environment, error)

NewEnvironmentFromOS returns the environment variables found in the OS runtime. Variables can be filtered by name, passing no names will return all variables.

func NewEnvironmentFromOSWithKnownVars 

func NewEnvironmentFromOSWithKnownVars() (*Environment, error)

func NewKVEnvironment 

func NewKVEnvironment(keyValues ...string) *Environment

NewKVEnvironment creates an environment from a list of key values

func (*Environment) AddLexicalScope 

func (e *Environment) AddLexicalScope(vars map[string]string) *Environment

func (*Environment) Len 

func (e *Environment) Len() int

func (*Environment) Mutate 

func (e *Environment) Mutate(env *Environment)

Mutate adds a mutation to the environment.

func (*Environment) ValueOf 

func (e *Environment) ValueOf(key string) string

ValueOf returns the value of a specific environment variable. This ensures consistency by acquiring locks in the same order as Values().

func (*Environment) Values 

func (e *Environment) Values() map[string]string

Values returns a merged map of all environment variables. This method ensures a consistent snapshot by acquiring all locks in the chain.

type ErrorCtx added in v0.2.0 

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

func NewErrorCtx added in v0.2.0 

func NewErrorCtx(description string, additionalCxt []byte) *ErrorCtx

func (*ErrorCtx) Errorf added in v0.2.0 

func (e *ErrorCtx) Errorf(ctx context.Context, message string, v ...any) error

type ExecResult 

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

func NewExecResult 

func NewExecResult(workDir string, cmdArgs []string, exitCode int) *ExecResult

func (*ExecResult) ToProto 

func (ec *ExecResult) ToProto() *proto.StepResult_ExecResult

type Function added in v0.33.0 

type Function interface {
	Describer
	Run(ctx ctx.Context, stepsCtx *StepsContext) (*proto.StepResult, error)
}

type FunctionDescriptor added in v0.24.0 

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

FunctionDescriptor describes a Function that has been fetched

func NewFunctionDescriptor added in v0.24.0 

func NewFunctionDescriptor(spec *proto.Spec, definition *proto.Definition, dir string) *FunctionDescriptor

NewFunctionDescriptor creates a FunctionDescriptor If the function has been fetched, directory should be the location where the function files are downloaded If the function is dynamic, dir should be empty string

func (*FunctionDescriptor) DefinitionOutputs added in v0.24.0 

func (sd *FunctionDescriptor) DefinitionOutputs() map[string]*structpb.Value

func (*FunctionDescriptor) DelegateTo added in v0.24.0 

func (sd *FunctionDescriptor) DelegateTo() string

func (*FunctionDescriptor) DescribeType added in v0.24.0 

func (sd *FunctionDescriptor) DescribeType() string

func (*FunctionDescriptor) Dir added in v0.24.0 

func (sd *FunctionDescriptor) Dir() string

func (*FunctionDescriptor) Env added in v0.24.0 

func (sd *FunctionDescriptor) Env() map[string]string

func (*FunctionDescriptor) ExecCommand added in v0.24.0 

func (sd *FunctionDescriptor) ExecCommand() []string

func (*FunctionDescriptor) ExecWorkDir added in v0.24.0 

func (sd *FunctionDescriptor) ExecWorkDir() string

func (*FunctionDescriptor) FunctionName added in v0.24.0 

func (sd *FunctionDescriptor) FunctionName() string

func (*FunctionDescriptor) IsDelegateOutputs added in v0.24.0 

func (sd *FunctionDescriptor) IsDelegateOutputs() bool

func (*FunctionDescriptor) IsTypeExec added in v0.24.0 

func (sd *FunctionDescriptor) IsTypeExec() bool

func (*FunctionDescriptor) IsTypeFunction added in v0.24.0 

func (sd *FunctionDescriptor) IsTypeFunction() bool

func (*FunctionDescriptor) IsTypeSteps added in v0.24.0 

func (sd *FunctionDescriptor) IsTypeSteps() bool

func (*FunctionDescriptor) SpecInputWithName added in v0.24.0 

func (sd *FunctionDescriptor) SpecInputWithName(name string) (*proto.Spec_Content_Input, bool)

func (*FunctionDescriptor) SpecInputs added in v0.24.0 

func (sd *FunctionDescriptor) SpecInputs() map[string]*proto.Spec_Content_Input

func (*FunctionDescriptor) SpecOutputs added in v0.24.0 

func (sd *FunctionDescriptor) SpecOutputs() map[string]*proto.Spec_Content_Output

func (*FunctionDescriptor) Steps added in v0.24.0 

func (sd *FunctionDescriptor) Steps() []*proto.Step

func (*FunctionDescriptor) ToProto added in v0.24.0 

func (sd *FunctionDescriptor) ToProto() *proto.SpecDefinition

type GlobalContext 

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

func NewGlobalContext 

func NewGlobalContext(workDir string, job JobVariables, env *Environment, stdout, stderr io.Writer, jobCtrl *JobCtrl) *GlobalContext

func (*GlobalContext) AddGlobalEnv added in v0.7.0 

func (gc *GlobalContext) AddGlobalEnv(env *Environment)

func (*GlobalContext) Env 

func (gc *GlobalContext) Env() *Environment

func (*GlobalContext) EnvWithLexicalScope added in v0.7.0 

func (gc *GlobalContext) EnvWithLexicalScope(envVars map[string]string) *Environment

func (*GlobalContext) Job 

func (gc *GlobalContext) Job() JobVariables

func (*GlobalContext) JobCtrl added in v0.35.0 

func (gc *GlobalContext) JobCtrl() *JobCtrl

JobCtrl returns the process lifecycle controls for the job.

func (*GlobalContext) Logf added in v0.2.0 

func (gc *GlobalContext) Logf(format string, v ...any) error

func (*GlobalContext) LookupEnv added in v0.20.0 

func (gc *GlobalContext) LookupEnv(key string) (string, bool)

func (*GlobalContext) Pipe added in v0.7.0 

func (gc *GlobalContext) Pipe() (io.Writer, io.Writer)

func (*GlobalContext) ProjectDir added in v0.18.0 

func (gc *GlobalContext) ProjectDir() string

func (*GlobalContext) WorkDir 

func (gc *GlobalContext) WorkDir() string

type JobCtrl added in v0.35.0 

type JobCtrl struct {
	GracefulExitDelay time.Duration
	// contains filtered or unexported fields
}

JobCtrl holds process lifecycle controls for a job, including the signal channel used to communicate cancellation to running steps and the grace period before the step should forcibly exit after cancellation.

JobCtrl must be constructed via NewJobCtrl. Using a zero-value JobCtrl is a programming error and will panic.

func NewJobCtrl added in v0.35.0 

func NewJobCtrl(gracefulExitDelay time.Duration) *JobCtrl

NewJobCtrl creates a JobCtrl with the given graceful exit delay. The delay controls how long a step has to exit cleanly after receiving a cancellation signal before it is force-killed.

func (*JobCtrl) Cancelled added in v0.35.0 

func (j *JobCtrl) Cancelled() <-chan struct{}

Cancelled returns a channel that is closed when the job has been cancelled.

func (*JobCtrl) ListenCancel added in v0.35.0 

func (j *JobCtrl) ListenCancel(ctx context.Context) (context.Context, context.CancelFunc)

ListenCancel returns a context derived from ctx that is cancelled when either the parent ctx is cancelled or RequestCancel is called on this JobCtrl. The caller must invoke the returned cancel func to release resources.

func (*JobCtrl) RequestCancel added in v0.35.0 

func (j *JobCtrl) RequestCancel()

RequestCancel signals all running steps to cancel. It is idempotent and safe to call from multiple goroutines.

type JobVariables added in v0.16.0 

type JobVariables map[string]*structpb.Value

func (JobVariables) ProjectDir added in v0.18.0 

func (v JobVariables) ProjectDir() string

func (JobVariables) StringValueOf added in v0.16.0 

func (v JobVariables) StringValueOf(key string) string

type Kind added in v0.17.0 

type Kind int
const (
	KindNull Kind = iota + 1 // same types as structpb.Value Kind
	KindNumber
	KindString
	KindBool
	KindStruct
	KindList
)

func ValueToKind added in v0.17.0 

func ValueToKind(value *structpb.Value) (Kind, error)

func (Kind) String added in v0.17.0 

func (k Kind) String() string

type NamedStepReference 

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

NamedStepReference is a step that is loaded using a name and a reference

func NewNamedStepReference 

func NewNamedStepReference(name string, ref *proto.Step_Reference) *NamedStepReference

func (*NamedStepReference) Describe added in v0.2.0 

func (sr *NamedStepReference) Describe() string

func (*NamedStepReference) ToProtoStep 

func (sr *NamedStepReference) ToProtoStep(params *StepParams) *proto.Step

type StepFile 

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

func NewStepFile 

func NewStepFile(path string) *StepFile

func NewStepFileInDir 

func NewStepFileInDir(dir string) (*StepFile, error)

func NewStepFileInTmp 

func NewStepFileInTmp() (*StepFile, error)

func (*StepFile) Path 

func (s *StepFile) Path() string

func (*StepFile) ReadDotEnv 

func (s *StepFile) ReadDotEnv() (map[string]string, error)

func (*StepFile) ReadEnvironment 

func (s *StepFile) ReadEnvironment(ctx context.Context) (*Environment, error)

func (*StepFile) ReadKeyValueLines 

func (s *StepFile) ReadKeyValueLines(ctx context.Context) (map[string]*structpb.Value, error)

func (*StepFile) ReadStepResult 

func (s *StepFile) ReadStepResult(ctx context.Context) (*proto.StepResult, error)

func (*StepFile) ReadValues 

func (s *StepFile) ReadValues(ctx context.Context, specOutputs map[string]*proto.Spec_Content_Output) (map[string]*structpb.Value, error)

func (*StepFile) Remove 

func (s *StepFile) Remove() error

type StepFileLine added in v0.2.0 

type StepFileLine struct {
	Name  *string         `json:"name"`
	Value *structpb.Value `json:"value"`
}

type StepFunc added in v0.17.0 

type StepFunc func(ctx context.Context, builtinCtx BuiltinContext) error

StepFunc is the implementation of a builtin step function.

type StepFuncFinder added in v0.17.0 

type StepFuncFinder func(stepName string) (*proto.Spec, StepFunc, error)

type StepFunctionRepository added in v0.17.0 

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

func NewStepFunctionRepository added in v0.17.0 

func NewStepFunctionRepository() *StepFunctionRepository

func (*StepFunctionRepository) Find added in v0.17.0 

func (r *StepFunctionRepository) Find(step string) (*proto.Spec, StepFunc, error)

func (*StepFunctionRepository) Register added in v0.17.0 

func (r *StepFunctionRepository) Register(step string, spec *proto.Spec, stepFunc StepFunc) error

type StepParams added in v0.28.0 

type StepParams struct {
	Inputs map[string]*structpb.Value
	Env    *Environment
}

StepParams is the inputs and environment passed to a function in a step In the following example, step params is the inputs{a: b} and env{c: d} run:

  • name: my_func func: gitlab.com/funcs/my_func inputs: {a: b} env: {c: d}

func NewEmptyStepParams added in v0.28.0 

func NewEmptyStepParams() *StepParams

func NewStepParams added in v0.28.0 

func NewStepParams(inputs map[string]*structpb.Value, env *Environment) *StepParams

func (*StepParams) InputsWithDefault added in v0.28.0 

func (p *StepParams) InputsWithDefault(specInputs map[string]*proto.Spec_Content_Input) map[string]*structpb.Value

type StepParser 

type StepParser interface {
	Parse(*GlobalContext, *FunctionDescriptor, *StepParams, StepReference) (Function, error)
}

type StepReference 

type StepReference interface {
	ToProtoStep(*StepParams) *proto.Step
	Describer
}

StepReference knows how the step was loaded

type StepResource 

type StepResource interface {
	Fetch(context.Context, *expression.InterpolationContext) (*FunctionDescriptor, error)
}

StepResource knows how to load a Step

type StepResultBuilder 

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

func NewStepResultBuilder 

func NewStepResultBuilder(loadedFrom StepReference, params *StepParams, funcDesc *FunctionDescriptor) *StepResultBuilder

func (*StepResultBuilder) Build 

func (bldr *StepResultBuilder) Build() *proto.StepResult

func (*StepResultBuilder) BuildFailure 

func (bldr *StepResultBuilder) BuildFailure() *proto.StepResult

func (*StepResultBuilder) ObserveEnv 

func (bldr *StepResultBuilder) ObserveEnv(env *Environment, err error) error

func (*StepResultBuilder) ObserveExecutedCmd 

func (bldr *StepResultBuilder) ObserveExecutedCmd(execResult *ExecResult, err error) error

func (*StepResultBuilder) ObserveExports 

func (bldr *StepResultBuilder) ObserveExports(exports *Environment, err error) (*Environment, error)

func (*StepResultBuilder) ObserveOutputs 

func (bldr *StepResultBuilder) ObserveOutputs(outputs map[string]*structpb.Value, err error) error

func (*StepResultBuilder) ObserveStepResult 

func (bldr *StepResultBuilder) ObserveStepResult(stepResult *proto.StepResult, err error) (*proto.StepResult, error)

func (*StepResultBuilder) WithEnv 

func (bldr *StepResultBuilder) WithEnv(env map[string]string) *StepResultBuilder

func (*StepResultBuilder) WithExecResult 

func (bldr *StepResultBuilder) WithExecResult(executedCmd *ExecResult) *StepResultBuilder

func (*StepResultBuilder) WithExports 

func (bldr *StepResultBuilder) WithExports(exports *Environment) *StepResultBuilder

func (*StepResultBuilder) WithOutputs 

func (bldr *StepResultBuilder) WithOutputs(outputs map[string]*structpb.Value) *StepResultBuilder

func (*StepResultBuilder) WithSubStepResult 

func (bldr *StepResultBuilder) WithSubStepResult(result *proto.StepResult) *StepResultBuilder

type StepRunnerError added in v0.34.0 

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

StepRunnerError marks an infrastructure fault: a bug in the step runner that the caller could not have prevented.

func (*StepRunnerError) Error added in v0.34.0 

func (e *StepRunnerError) Error() string

func (*StepRunnerError) Unwrap added in v0.34.0 

func (e *StepRunnerError) Unwrap() error

type StepsContext 

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

func NewStepsContext 

func NewStepsContext(globalCtx *GlobalContext, stepDir string, inputs map[string]*structpb.Value, env *Environment, options ...func(*StepsContext)) (*StepsContext, error)

func (*StepsContext) AddGlobalEnv added in v0.7.0 

func (s *StepsContext) AddGlobalEnv(env *Environment)

func (*StepsContext) Cleanup 

func (s *StepsContext) Cleanup()

func (*StepsContext) EnvWithLexicalScope added in v0.7.0 

func (s *StepsContext) EnvWithLexicalScope(envVars map[string]string) *Environment

func (*StepsContext) ExpandAndApplyEnv 

func (s *StepsContext) ExpandAndApplyEnv(env map[string]string) (*Environment, error)

func (*StepsContext) GetEnv added in v0.17.0 

func (s *StepsContext) GetEnv(name string) string

func (*StepsContext) GetEnvList 

func (s *StepsContext) GetEnvList() []string

func (*StepsContext) GetEnvs 

func (s *StepsContext) GetEnvs() map[string]string

func (*StepsContext) GetExportFile added in v0.17.0 

func (s *StepsContext) GetExportFile() string

func (*StepsContext) GetInput added in v0.17.0 

func (s *StepsContext) GetInput(name string, kind Kind) (*structpb.Value, error)

func (*StepsContext) GetInputWithDefault added in v0.18.0 

func (s *StepsContext) GetInputWithDefault(name string, kind Kind, inputSpec map[string]*proto.Spec_Content_Input) (*structpb.Value, error)

func (*StepsContext) GetJobVars added in v0.33.0 

func (s *StepsContext) GetJobVars() map[string]*structpb.Value

func (*StepsContext) GetOutputFile added in v0.17.0 

func (s *StepsContext) GetOutputFile() string

func (*StepsContext) GlobalCtx added in v0.33.0 

func (s *StepsContext) GlobalCtx() *GlobalContext

func (*StepsContext) GracefulExitDelay added in v0.35.0 

func (s *StepsContext) GracefulExitDelay() time.Duration

func (*StepsContext) JobCtrl added in v0.35.0 

func (s *StepsContext) JobCtrl() *JobCtrl

func (*StepsContext) ListenCancel added in v0.35.0 

func (s *StepsContext) ListenCancel(ctx context.Context) (context.Context, context.CancelFunc)

func (*StepsContext) LookupEnv added in v0.20.0 

func (s *StepsContext) LookupEnv(key string) (string, bool)

func (*StepsContext) Pipe added in v0.7.0 

func (s *StepsContext) Pipe() (io.Writer, io.Writer)

func (*StepsContext) ProjectDir added in v0.18.0 

func (s *StepsContext) ProjectDir() string

func (*StepsContext) ReadExportedEnv added in v0.7.0 

func (s *StepsContext) ReadExportedEnv(ctx context.Context) (*Environment, error)

func (*StepsContext) ReadOutputStepResult added in v0.7.0 

func (s *StepsContext) ReadOutputStepResult(ctx context.Context) (*proto.StepResult, error)

func (*StepsContext) ReadOutputValues added in v0.7.0 

func (s *StepsContext) ReadOutputValues(ctx context.Context, specOutputs map[string]*proto.Spec_Content_Output) (map[string]*structpb.Value, error)

func (*StepsContext) RecordResult 

func (s *StepsContext) RecordResult(stepResult *proto.StepResult)

RecordResult captures the result of a step even if it failed

func (*StepsContext) StepResults 

func (s *StepsContext) StepResults() []*proto.StepResult

func (*StepsContext) View 

func (s *StepsContext) View() *expression.InterpolationContext

func (*StepsContext) WorkDir added in v0.7.0 

func (s *StepsContext) WorkDir() string

Source Files

View all Source files

Directories

Path Synopsis
oci

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.