shell

Documentation

Index

• Variables
• type CommandExecutor
• type CommandGenerator
  • func (cmd *CommandGenerator) Run(script string) (*CommandResults, error)
• type CommandResults
  • func (c *CommandResults) Append(op string, toAppend *CommandResults) *CommandResults
  • func (c *CommandResults) Cons(op string, toAppend *CommandResults) *CommandResults
  • func (c *CommandResults) Eq(cmd *CommandResults) bool
  • func (c *CommandResults) ExitStatuses() (results []uint32)
  • func (c *CommandResults) ExitStrings() (results []string)
  • func (c *CommandResults) First() *CommandResults
  • func (c *CommandResults) GetMessages() (output []string)
  • func (c *CommandResults) Last() *CommandResults
  • func (c *CommandResults) OpEq(cmd *CommandResults) bool
  • func (c *CommandResults) OutputMap() map[string]string
  • func (c *CommandResults) Reverse() *CommandResults
  • func (c *CommandResults) Summarize() string
  • func (c *CommandResults) SummarizeAll() (summaries []string)
  • func (c *CommandResults) Uniq() *CommandResults
  • func (c *CommandResults) UniqOp() *CommandResults
  • func (c *CommandResults) Unlink(cmd *CommandResults) (removed *CommandResults, results *CommandResults)
  • func (c *CommandResults) UnlinkWhen(f func(*CommandResults) bool) *CommandResults
• type Preparer
  • func (p *Preparer) Prepare(render resource.Renderer) (resource.Task, error)
• type ResultsContext
• type Shell
  • func (s *Shell) Apply() (resource.TaskStatus, error)
  • func (s *Shell) Check(r resource.Renderer) (resource.TaskStatus, error)
  • func (s *Shell) Diffs() map[string]resource.Diff
  • func (s *Shell) Error() error
  • func (s *Shell) FailingDep(name string, task resource.TaskStatus)
  • func (s *Shell) HasChanges() bool
  • func (s *Shell) HealthCheck() (*resource.HealthStatus, error)
  • func (s *Shell) Messages() (messages []string)
  • func (s *Shell) StatusCode() resource.StatusLevel
  • func (s *Shell) Value() string

Variables

var (
	ErrTimedOut = errors.New("execution timed out")
)

Currently when a script executes beyond it's alloted time a timeout will occur and nil is returned by timeoutExec. The goroutine running the script will continue to drain stdout and stderr from the process sockets and they will be GCed when the script finally finishes. This means that there is no mechanism for getting the output of a script when it has timed out. A proposed solution to this would be to implement a ReadUntilWouldBlock-type function that would allow us to read into a buffer from a ReadCloser until the read operation would block, then return the contents of the buffer (along with some marker if we recevied an error or EOF). Then exec function would then take in pointers to buffers for stdout and stderr and populate them directly, so that if the script execution timed out we would still have a reference to those buffers.

Types

type CommandExecutor

type CommandExecutor interface {
	Run(string) (*CommandResults, error)
}

A CommandExecutor supports running a script and returning the results wrapped in a *CommandResults structure.

type CommandGenerator

type CommandGenerator struct {
	Interpreter string
	Flags       []string
	Dir         string
	Env         []string
	Timeout     *time.Duration
}

CommandGenerator provides a container to wrap generating a system command

func (*CommandGenerator) Run

func (cmd *CommandGenerator) Run(script string) (*CommandResults, error)

Run will generate a new command and run it with optional timeout parameters

type CommandResults

type CommandResults struct {
	ResultsContext
	ExitStatus uint32
	Stdout     string
	Stderr     string
	Stdin      string
	State      *os.ProcessState
}

CommandResults hold the resulting state of command execution

func (*CommandResults) Append

func (c *CommandResults) Append(op string, toAppend *CommandResults) *CommandResults

Append adds an element to the end of the list

func (*CommandResults) Cons

func (c *CommandResults) Cons(op string, toAppend *CommandResults) *CommandResults

Cons a command result to another command result, allowing the capture of multiple runs of a task with a session.

func (*CommandResults) Eq

func (c *CommandResults) Eq(cmd *CommandResults) bool

Eq tests command results for equality

func (*CommandResults) ExitStatuses

func (c *CommandResults) ExitStatuses() (results []uint32)

ExitStatuses returns a slice with the exit status of all the commands

func (*CommandResults) ExitStrings

func (c *CommandResults) ExitStrings() (results []string)

ExitStrings returns a list of strings containing the operation type and exit status in the form of Operation (code).

func (*CommandResults) First

func (c *CommandResults) First() *CommandResults

First returns the head of the results list

func (*CommandResults) GetMessages

func (c *CommandResults) GetMessages() (output []string)

GetMessages will return a set of output messages from all result sets

func (*CommandResults) Last

func (c *CommandResults) Last() *CommandResults

Last returns the last element in the list

func (*CommandResults) OpEq

func (c *CommandResults) OpEq(cmd *CommandResults) bool

OpEq tests command results for equality using only the operation name

func (*CommandResults) OutputMap

func (c *CommandResults) OutputMap() map[string]string

OutputMap returns a map of fds by name and the output on them

func (*CommandResults) Reverse

func (c *CommandResults) Reverse() *CommandResults

Reverse will reverse the list

func (*CommandResults) Summarize

func (c *CommandResults) Summarize() string

Summarize provides an overall summary of the results of the command

func (*CommandResults) SummarizeAll

func (c *CommandResults) SummarizeAll() (summaries []string)

SummarizeAll returnes a list of summaries of a command result and it's ancestors

func (*CommandResults) Uniq

func (c *CommandResults) Uniq() *CommandResults

Uniq removes duplicate entries (as dicated by Eq) from the results list

func (*CommandResults) UniqOp

func (c *CommandResults) UniqOp() *CommandResults

UniqOp removes duplicate operation entries based just on their operation name

func (*CommandResults) Unlink

func (c *CommandResults) Unlink(cmd *CommandResults) (removed *CommandResults, results *CommandResults)

Unlink removes an element from the results list, and returns a tuple of the removed element and the updated list. If the Element to remove is the head of the list, then it will return the next element, otherwise return the current head.

func (*CommandResults) UnlinkWhen

func (c *CommandResults) UnlinkWhen(f func(*CommandResults) bool) *CommandResults

UnlinkWhen removes each element in the list when the provided function is true

type Preparer

type Preparer struct {
	// the shell interpreter that will be used for your scripts. `/bin/sh` is
	// used by default.
	Interpreter string `hcl:"interpreter"`

	// flags to pass to the `interpreter` binary to check validity. For
	// `/bin/sh` this is `-n`
	CheckFlags []string `hcl:"check_flags"`

	// flags to pass to the interpreter at execution time
	ExecFlags []string `hcl:"exec_flags"`

	// the script to run to check if a resource needs to be changed. It should
	// exit with exit code 0 if the resource does not need to be changed, and
	// 1 (or above) otherwise.
	Check string `hcl:"check"`

	// the script to run to apply the resource. Normal shell exit code
	// expectations apply (that is, exit code 0 for success, 1 or above for
	// failure.)
	Apply string `hcl:"apply"`

	// the amount of time the command will wait before halting forcefully. The
	// format is Go's duration string. A duration string is a possibly signed
	// sequence of decimal numbers, each with optional fraction and a unit
	// suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns",
	// "us" (or "µs"), "ms", "s", "m", "h".
	Timeout string `hcl:"timeout" doc_type:"duration string"`

	// the working directory this command should be run in
	Dir string `hcl:"dir"`

	// any environment variables that should be passed to the command
	Env map[string]string `hcl:"env"`
}

Preparer for shell tasks

Task allows you to run arbitrary shell commands on your system, first checking if the command should be run.

func (*Preparer) Prepare

func (p *Preparer) Prepare(render resource.Renderer) (resource.Task, error)

Prepare a new shell task

type ResultsContext

type ResultsContext struct {
	Operation string
	Next      *CommandResults
	Prev      *CommandResults
}

ResultsContext provides a linked list of CommandResults with a operation context that tells us the providence of the command.

type Shell

type Shell struct {
	CmdGenerator CommandExecutor
	CheckStmt    string
	ApplyStmt    string
	Dir          string
	Env          []string
	Status       *CommandResults
	CheckStatus  *CommandResults
	HealthStatus *resource.HealthStatus
	// contains filtered or unexported fields
}

Shell is a structure representing a task.

func (*Shell) Apply

func (s *Shell) Apply() (resource.TaskStatus, error)

Apply is a NOP for health checks

func (*Shell) Check

func (s *Shell) Check(r resource.Renderer) (resource.TaskStatus, error)

Check passes through to shell.Shell.Check() and then sets the health status

func (*Shell) Diffs

func (s *Shell) Diffs() map[string]resource.Diff

Diffs is required to implement resource.TaskStatus but there is no mechanism for defining diffs for shell operations, so returns a nil map.

func (*Shell) Error

func (s *Shell) Error() error

Error is required for TaskStatus

func (*Shell) FailingDep

func (s *Shell) FailingDep(name string, task resource.TaskStatus)

FailingDep tracks a failing dependency

func (*Shell) HasChanges

func (s *Shell) HasChanges() bool

HasChanges returns true if changes are required as determined by the the most recent run of check.

func (*Shell) HealthCheck

func (s *Shell) HealthCheck() (*resource.HealthStatus, error)

HealthCheck performs a health check

func (*Shell) Messages

func (s *Shell) Messages() (messages []string)

Messages returns a summary of the first execution of check and/or apply. Subsequent runs are surpressed.

func (*Shell) StatusCode

func (s *Shell) StatusCode() resource.StatusLevel

StatusCode returns the status code of the most recently executed command

func (*Shell) Value

func (s *Shell) Value() string

Value provides a value for the shell, which is the stdout data from the last executed command.