converge: Index | Files | Directories

package shell

import ""


Package Files

command_executor.go command_results.go preparer.go shell.go


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.

type CommandExecutor Uses

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

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

type CommandGenerator Uses

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 Uses

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

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

type CommandResults Uses

type CommandResults struct {

    // the exit status of the process
    ExitStatus uint32 `export:"exitstatus"`

    // the stdout data from the process
    Stdout string `export:"stdout"`

    // the stderr data from the process
    Stderr string `export:"stderr"`

    // the stdin data sent to the process
    Stdin string `export:"stdin"`

    State *os.ProcessState

CommandResults hold the resulting state of command execution

func (*CommandResults) Append Uses

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

Append adds an element to the end of the list

func (*CommandResults) Cons Uses

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 Uses

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

Eq tests command results for equality

func (*CommandResults) ExitStatuses Uses

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

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

func (*CommandResults) ExitStrings Uses

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 Uses

func (c *CommandResults) First() *CommandResults

First returns the head of the results list

func (*CommandResults) GetMessages Uses

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

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

func (*CommandResults) Last Uses

func (c *CommandResults) Last() *CommandResults

Last returns the last element in the list

func (*CommandResults) OpEq Uses

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

OpEq tests command results for equality using only the operation name

func (*CommandResults) OutputMap Uses

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

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

func (*CommandResults) Reverse Uses

func (c *CommandResults) Reverse() *CommandResults

Reverse will reverse the list

func (*CommandResults) Summarize Uses

func (c *CommandResults) Summarize() string

Summarize provides an overall summary of the results of the command

func (*CommandResults) SummarizeAll Uses

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

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

func (*CommandResults) Uniq Uses

func (c *CommandResults) Uniq() *CommandResults

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

func (*CommandResults) UniqOp Uses

func (c *CommandResults) UniqOp() *CommandResults

UniqOp removes duplicate operation entries based just on their operation name

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 Uses

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

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

type Preparer Uses

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" nonempty:"true"`

    // 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" nonempty:"true"`

    // the amount of time the command will wait before halting forcefully.
    Timeout *time.Duration `hcl:"timeout"`

    // 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 Uses

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

Prepare a new shell task

type ResultsContext Uses

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 Uses

type Shell struct {
    CmdGenerator CommandExecutor

    // the check statement
    CheckStmt string `export:"check"`

    // the apply statement
    ApplyStmt string `export:"apply"`

    // the working directory of the task
    Dir string `export:"dir"`

    // environment variables configured for the task
    Env []string `export:"env"`

    // the status of the task
    Status *CommandResults `re-export-as:"status"`

    // the status of the check phase
    CheckStatus *CommandResults `export:"checkstatus"`

    // the status of the health check
    HealthStatus *resource.HealthStatus `export:"healthstatus"`
    // contains filtered or unexported fields

Shell is a structure representing a task.

func (*Shell) Apply Uses

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

Apply is a NOP for health checks

func (*Shell) Check Uses

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

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

func (*Shell) Diffs Uses

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 Uses

func (s *Shell) Error() error

Error is required for TaskStatus

func (*Shell) ExportedFields Uses

func (s *Shell) ExportedFields() resource.FieldMap

ExportedFields returns the exported field map

func (*Shell) FailingDep Uses

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

FailingDep tracks a failing dependency

func (*Shell) HasChanges Uses

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 Uses

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

HealthCheck performs a health check

func (*Shell) Messages Uses

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 Uses

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

StatusCode returns the status code of the most recently executed command

func (*Shell) UpdateExportedFields Uses

func (s *Shell) UpdateExportedFields(resource.Task) error

UpdateExportedFields is a nop

func (*Shell) Value Uses

func (s *Shell) Value() string

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

func (*Shell) Warning Uses

func (s *Shell) Warning() string

Warning is required for TaskStatus



Package shell imports 15 packages (graph) and is imported by 3 packages. Updated 2016-12-25. Refresh now. Tools for package owners.