executorsubprocess

Documentation

Overview

Package executor handles subprocess execution for plugin actions.

The execution model:

1. Daemon resolves templates in action options using trigger context
2. Daemon spawns the plugin process (for shell: the configured shell)
3. Stdin receives resolved template content (for shell: not used, command is via -c arg)
4. Stdout and stderr are captured separately
5. Exit code and wall-clock duration are recorded

Index

• func Kill(cmd *exec.Cmd)
• func ResolveTemplate(s string, ctx *Context) (string, error)
• type ActionPluginInput
• type ActionPluginOutput
  • func ParseActionPluginOutput(stdout string) (*ActionPluginOutput, error)
• type Context
• type Request
  • func ActionPluginRequest(binaryPath string, input *ActionPluginInput, env []string, workDir string, ...) (*Request, error)
  • func ShellRequest(shellCmd string, command string) *Request
• type ResolveResult
  • func ResolveOptions(opts map[string]any, ctx *Context) (*ResolveResult, error)
• type Result
  • func Execute(ctx context.Context, req *Request) (*Result, error)

Functions

func Kill

func Kill(cmd *exec.Cmd)

Kill terminates the process group, giving the process a chance to clean up.

func ResolveTemplate

func ResolveTemplate(s string, ctx *Context) (string, error)

ResolveTemplate applies Go text/template substitution to s using the given context. Returns the original string unchanged if it contains no template expressions.

Types

type ActionPluginInput

type ActionPluginInput struct {
	ActionType string         `json:"action_type"`
	Options    map[string]any `json:"options"`
	Config     map[string]any `json:"config"`
	Test       bool           `json:"test"`
}

ActionPluginInput is the JSON payload sent to a plugin binary's stdin when executing an action.

type ActionPluginOutput

type ActionPluginOutput struct {
	Success bool   `json:"success"`
	Output  string `json:"output"`
	Error   string `json:"error"`
}

ActionPluginOutput is the JSON response read from the plugin binary's stdout.

func ParseActionPluginOutput

func ParseActionPluginOutput(stdout string) (*ActionPluginOutput, error)

ParseActionPluginOutput parses the stdout of a plugin action binary.

type Context

type Context struct {
	// Test is true when the action is invoked via `watch test` (dry-run/testing mode).
	// Plugins can use this to skip destructive operations or produce test output.
	Test bool

	// Set contains context variables from trigger events and --set flags.
	// These are promoted to top-level template variables (e.g. {{.RequestBody}}).
	Set map[string]string

	// Secrets holds resolved secret values keyed by secret name.
	// Available in templates via {{secret "name"}}.
	Secrets map[string]string
	// contains filtered or unexported fields
}

Context holds the variables available during template resolution.

type Request

type Request struct {
	// Command is the executable to run (e.g., "sh", "/usr/bin/python3").
	Command string

	// Args are the command arguments (e.g., ["-c", "echo hello"]).
	Args []string

	// Stdin is optional content piped to the process's stdin.
	Stdin string

	// Env is additional environment variables (key=value format).
	Env []string

	// WorkingDir is the working directory. Empty means inherit.
	WorkingDir string

	// Timeout is the maximum execution time. Zero means no timeout.
	Timeout time.Duration
}

Request describes a subprocess to execute.

func ActionPluginRequest

func ActionPluginRequest(binaryPath string, input *ActionPluginInput, env []string, workDir string, timeout time.Duration) (*Request, error)

ActionPluginRequest builds a Request that spawns the plugin binary with the ActionPluginInput serialized as JSON on stdin.

func ShellRequest

func ShellRequest(shellCmd string, command string) *Request

ShellRequest builds a Request for executing a shell command. shellCmd is the shell invocation (e.g., "sh -c" or "bash -c"). command is the resolved command string to execute.

type ResolveResult

type ResolveResult struct {
	Options       map[string]any
	SensitiveKeys map[string]bool
}

ResolveResult holds resolved options and tracks which keys accessed secrets.

func ResolveOptions

func ResolveOptions(opts map[string]any, ctx *Context) (*ResolveResult, error)

ResolveOptions resolves templates in all string values of an options map. Non-string values are passed through unchanged. Returns a ResolveResult that includes which option keys accessed secrets via {{secret "name"}}.

type Result

type Result struct {
	Stdout   string
	Stderr   string
	ExitCode int
	Duration time.Duration
}

Result captures the outcome of a subprocess execution.

func Execute

func Execute(ctx context.Context, req *Request) (*Result, error)

Execute runs a subprocess and captures its output.