experiments

Documentation

Overview

Package experiments provides a global registry of enabled and disabled experiments.

It is intended for internal use by buildkite-agent only.

Index

• Constants
• Variables
• func Disable(ctx context.Context, key string) context.Context
• func Enabled(ctx context.Context) []string
• func IsEnabled(ctx context.Context, key string) bool
• func KnownAndEnabled(ctx context.Context) []string
• type State
  • func Enable(ctx context.Context, key string) (newctx context.Context, state State)
  • func EnableWithWarnings(ctx context.Context, l logger.Logger, key string) (context.Context, State)

Constants

const (
	// Available experiments
	AgentAPI                       = "agent-api"
	AllowArtifactPathTraversal     = "allow-artifact-path-traversal"
	DescendingSpawnPriority        = "descending-spawn-priority"
	InterpolationPrefersRuntimeEnv = "interpolation-prefers-runtime-env"
	NormalisedUploadPaths          = "normalised-upload-paths"
	OverrideZeroExitOnCancel       = "override-zero-exit-on-cancel"
	PTYRaw                         = "pty-raw"
	PolyglotHooks                  = "polyglot-hooks"
	ResolveCommitAfterCheckout     = "resolve-commit-after-checkout"
	UseZZGlob                      = "use-zzglob"

	// Promoted experiments
	ANSITimestamps         = "ansi-timestamps"
	AvoidRecursiveTrap     = "avoid-recursive-trap"
	FlockFileLocks         = "flock-file-locks"
	GitMirrors             = "git-mirrors"
	InbuiltStatusPage      = "inbuilt-status-page"
	IsolatedPluginCheckout = "isolated-plugin-checkout"
	JobAPI                 = "job-api"
	KubernetesExec         = "kubernetes-exec"
)

Variables

var (
	Available = map[string]struct{}{
		AgentAPI:                       {},
		AllowArtifactPathTraversal:     {},
		DescendingSpawnPriority:        {},
		InterpolationPrefersRuntimeEnv: {},
		NormalisedUploadPaths:          {},
		OverrideZeroExitOnCancel:       {},
		PolyglotHooks:                  {},
		ResolveCommitAfterCheckout:     {},
		UseZZGlob:                      {},
	}

	Promoted = map[string]string{
		ANSITimestamps:         standardPromotionMsg(ANSITimestamps, "v3.48.0"),
		AvoidRecursiveTrap:     standardPromotionMsg(AvoidRecursiveTrap, "v3.66.0"),
		FlockFileLocks:         standardPromotionMsg(FlockFileLocks, "v3.48.0"),
		GitMirrors:             standardPromotionMsg(GitMirrors, "v3.47.0"),
		InbuiltStatusPage:      standardPromotionMsg(InbuiltStatusPage, "v3.48.0"),
		IsolatedPluginCheckout: standardPromotionMsg(IsolatedPluginCheckout, "v3.67.0"),
		JobAPI:                 standardPromotionMsg(JobAPI, "v3.64.0"),
		KubernetesExec:         "The kubernetes-exec experiment has been replaced with the --kubernetes-exec flag as of agent v3.74.0",
	}
)

Functions

func Disable

func Disable(ctx context.Context, key string) context.Context

Disable a particular experiment in a new context.

func Enabled

func Enabled(ctx context.Context) []string

Enabled returns the keys of all the enabled experiments.

func IsEnabled

func IsEnabled(ctx context.Context, key string) bool

IsEnabled reports whether the named experiment is enabled in the context.

func KnownAndEnabled

func KnownAndEnabled(ctx context.Context) []string

KnownAndEnabled returns the keys of all the known and enabled experiments.

Types

type State

type State string

const (
	StateKnown    State = "known"
	StatePromoted State = "promoted"
	StateUnknown  State = "unknown"
)

Experiment states

func Enable

func Enable(ctx context.Context, key string) (newctx context.Context, state State)

Enable a particular experiment in a new context.

func EnableWithWarnings

func EnableWithWarnings(ctx context.Context, l logger.Logger, key string) (context.Context, State)

EnableWithWarnings enables an experiment in a new context, logging information about unknown and promoted experiments.