actions

Documentation

Overview

Package actions includes: 1. a set of transformers for default cipkg actions

• core.ActionCommand
• core.ActionFilesCopy
• core.ActionCIPDExport
• core.ActionURLFetch

2. ActionProcessor and Transformer for converting Action to Derivation and registering user defined action.

Index

• Variables
• func ActionCIPDExportExecutor(ctx context.Context, a *core.ActionCIPDExport, out string) error
• func ActionCIPDExportTransformer(a *core.ActionCIPDExport, deps []Package) (*core.Derivation, error)
• func ActionCommandTransformer(a *core.ActionCommand, deps []Package) (*core.Derivation, error)
• func ActionFilesCopyTransformer(a *core.ActionFilesCopy, deps []Package) (*core.Derivation, error)
• func ActionURLFetchExecutor(ctx context.Context, a *core.ActionURLFetch, out string) (err error)
• func ActionURLFetchTransformer(a *core.ActionURLFetch, deps []Package) (*core.Derivation, error)
• func MustSetExecutor[M proto.Message](r *ReexecRegistry, execFunc Executor[M])
• func MustSetTransformer[M proto.Message](ap *ActionProcessor, tf Transformer[M])
• func ReexecDerivation(m proto.Message, hostEnv bool) (*core.Derivation, error)
• func RegisterEmbed(ref string, e embed.FS)
• func SetExecutor[M proto.Message](r *ReexecRegistry, execFunc Executor[M]) error
• func SetTransformer[M proto.Message](ap *ActionProcessor, tf Transformer[M]) error
• type ActionProcessor
  • func NewActionProcessor() *ActionProcessor
  • func (ap *ActionProcessor) Process(buildPlat string, pm core.PackageManager, a *core.Action) (Package, error)
• type Executor
• type Package
• type ReadLinkFS
• type ReexecRegistry
  • func NewReexecRegistry() *ReexecRegistry
  • func (r *ReexecRegistry) Intercept(ctx context.Context)
• type Transformer

Variables

var (
	ErrExecutorExisted      = errors.New("executor for the message type already existed")
	ErrReexecRegistrySealed = errors.New("executor can't be set after Intercept being called")
)

var (
	ErrTransformerExisted    = errors.New("transformer for the message type already existed")
	ErrActionProcessorSealed = errors.New("transformer can't be set after processor being used")
)

var (
	ErrUnsupportedAction = errors.New("unsupported action spec")
)

Functions

func ActionCIPDExportExecutor

func ActionCIPDExportExecutor(ctx context.Context, a *core.ActionCIPDExport, out string) error

ActionCIPDExportExecutor is the default executor for core.ActionCIPDExport. It will use the cipd binary/script (or cipd.bat/cipd.exe on windows) on PATH to export the packages required.

func ActionCIPDExportTransformer

func ActionCIPDExportTransformer(a *core.ActionCIPDExport, deps []Package) (*core.Derivation, error)

ActionCIPDExportTransformer is the default transformer for core.ActionCIPDExport.

func ActionCommandTransformer

func ActionCommandTransformer(a *core.ActionCommand, deps []Package) (*core.Derivation, error)

ActionCommandTransformer is the default transformer for core.ActionCommand.

func ActionFilesCopyTransformer

func ActionFilesCopyTransformer(a *core.ActionFilesCopy, deps []Package) (*core.Derivation, error)

ActionFilesCopyTransformer is the default transformer for core.ActionFilesCopy.

func ActionURLFetchExecutor

func ActionURLFetchExecutor(ctx context.Context, a *core.ActionURLFetch, out string) (err error)

ActionURLFetchExecutor is the default executor for core.ActionURLFetch.

func ActionURLFetchTransformer

func ActionURLFetchTransformer(a *core.ActionURLFetch, deps []Package) (*core.Derivation, error)

ActionURLFetchTransformer is the default transformer for core.ActionURLFetch.

func MustSetExecutor

func MustSetExecutor[M proto.Message](r *ReexecRegistry, execFunc Executor[M])

MustSetExecutor set the executor for the action specification M similar to SetExecutor, but will panic if any error happened.

func MustSetTransformer

func MustSetTransformer[M proto.Message](ap *ActionProcessor, tf Transformer[M])

MustSetTransformer set the transformer for the action specification M and panic if any error happened.

func ReexecDerivation

func ReexecDerivation(m proto.Message, hostEnv bool) (*core.Derivation, error)

ReexecDerivation returns a derivation for re-executing the binary. It sets the FixedOutput using hash generated from action spec.

func RegisterEmbed

func RegisterEmbed(ref string, e embed.FS)

RegisterEmbed regists the embedded fs with ref. It can be retrieved by copy actions using embed source. Embedded fs need to be registered in init() for re-exec executor.

func SetExecutor

func SetExecutor[M proto.Message](r *ReexecRegistry, execFunc Executor[M]) error

SetExecutor set the executor for the action specification M. All executors must be set before calling .Intercept(). If there is a executor already registed for M, SetExecutor will return ErrExecutorExisted.

func SetTransformer

func SetTransformer[M proto.Message](ap *ActionProcessor, tf Transformer[M]) error

SetTransformer set the transformer for the action specification M.

Types

type ActionProcessor

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

ActionProcessor processes and transforms actions into packages.

func NewActionProcessor

func NewActionProcessor() *ActionProcessor

func (*ActionProcessor) Process

func (ap *ActionProcessor) Process(buildPlat string, pm core.PackageManager, a *core.Action) (Package, error)

Process transforms a given *core.Action into a self-contained Package, which includes all its dependencies also converted from *core.Action into Package.

type Executor

type Executor[M proto.Message] func(ctx context.Context, msg M, out string) error

Executor is the type of the Executor for action spec M. When the function is invoked, the action associated with the message spec should be executed. `out` is the output path for the artifacts generated by the executor.

type Package

type Package struct {
	Handler core.PackageHandler

	DerivationID string
	Derivation   *core.Derivation

	BuildDependencies   []Package
	RuntimeDependencies []Package

	ActionID string
	Action   *core.Action
}

Package represents a high-level package including: - A storage handler for the package. - The transformed derivation and its unique id. - All its dependencies. - The action responsible for the package's content. All dependencies will be available duing build time (e.g for testing) but only runtime dependencies will be ensured to be available at runtime. Potentially we can cache or reuse package to avoid transform the same action multiple times if performance is to be considered.

type ReadLinkFS

type ReadLinkFS interface {
	fs.FS

	// ReadLink returns the destination of the named symbolic link.
	// Link destinations will always be slash-separated paths.
	// NOTE: Although in the standard library the link destination is guaranteed
	// to be a path inside FS. We may return host destination for our use cases.
	ReadLink(name string) (string, error)
}

ReadLinkFS is the interface implemented by a file system that supports symbolic links. TODO(fancl): Replace it with https://github.com/golang/go/issues/49580

type ReexecRegistry

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

ReexecRegistry is the registry for actions that requires implemented in the binary itself.

By default, NewReexecRegistry registers the following Reexec Executors:

• core.ActionURLFetch
• core.ActionFilesCopy
• core.ActionCIPDExport

In order for a binary to work with reexec actions, you must call the .Intercept() function very early in your program's `main()`. This will intercept the invocation of this program and divert execution control to the registered Executor.

Programs may register additional Executors in this registry using SetExecutor or MustSetExecutor functions from this package.

func NewReexecRegistry

func NewReexecRegistry() *ReexecRegistry

func (*ReexecRegistry) Intercept

func (r *ReexecRegistry) Intercept(ctx context.Context)

Intercept executes the registed executor and exit if _CIPKG_EXEC_CMD is found. This is REQUIRED for reexec to function properly and need to be executed after init() because embed fs or other resources may be registered in init(). Any application using the framework must call the .Intercept() function very early in your program's `main()`. This will intercept the invocation of this program and divert execution control to the registered Executor. On windows, environment variable NoDefaultCurrentDirectoryInExePath will always be set to prevent searching binaries from current workding directory by default, which because of its relative nature, is forbidden by golang.

type Transformer

type Transformer[M proto.Message] func(M, []Package) (*core.Derivation, error)

Transformer is the function transforms an action specification to a derivation.