procutil

README

procutil

This repository contains a go package for various processes.

License

MIT

Documentation

Overview

Package procutil implements wrapper for various processes.

Index

• type Command
  • func (e *Command) Cleanup() error
  • func (e *Command) Init(ctx context.Context, isTty bool) error
  • func (e *Command) Start(Out, Err io.Writer, In io.Reader) error
  • func (e *Command) StartPty(tm io.ReadWriteCloser, TERM string, resizeChan <-chan term.WindowSize) error
  • func (e *Command) Stop() error
  • func (e *Command) Wait() (int, error)
• type DockerExecStreamer
  • func (des *DockerExecStreamer) Attach(ctx context.Context, isPty bool) error
  • func (des *DockerExecStreamer) Detach(ctx context.Context) error
  • func (des *DockerExecStreamer) Init(ctx context.Context, Term string, isPty bool) error
  • func (des *DockerExecStreamer) ResizeTo(ctx context.Context, size term.WindowSize) error
  • func (des *DockerExecStreamer) Result(ctx context.Context) (int, error)
  • func (des *DockerExecStreamer) StreamInput(ctx context.Context, stdin io.Reader, restoreTerms func(), ...)
  • func (des *DockerExecStreamer) StreamOutput(ctx context.Context, stdout, stderr io.Writer, restoreTerms func(), ...)
  • func (des *DockerExecStreamer) String() string
• type DualCloser
  • func NewDualCloser(closer io.Closer) DualCloser
• type DualCloserWrapper
  • func (w *DualCloserWrapper) Close() (err error)
  • func (w *DualCloserWrapper) CloseWrite() (err error)
• type ExecProcess
  • func (sp *ExecProcess) Cleanup() error
  • func (sp *ExecProcess) Init(ctx context.Context, isPty bool) error
  • func (sp *ExecProcess) Start(Term string, resizeChan <-chan term.WindowSize, isPty bool) (term.Terminal, error)
  • func (sp *ExecProcess) Stderr() (io.ReadCloser, error)
  • func (sp *ExecProcess) Stdin() (io.WriteCloser, error)
  • func (sp *ExecProcess) Stdout() (io.ReadCloser, error)
  • func (sp *ExecProcess) Stop() (err error)
  • func (sp *ExecProcess) String() string
  • func (sp *ExecProcess) Wait() (code int, err error)
• type Process
• type Streamer
• type StreamingProcess
  • func NewDockerExecProcess(client client.APIClient, containerID string, command []string) *StreamingProcess
  • func (sp *StreamingProcess) Cleanup() error
  • func (sp *StreamingProcess) Init(ctx context.Context, isTerm bool) error
  • func (sp *StreamingProcess) Start(Term string, resizeChan <-chan term.WindowSize, isPty bool) (term.Terminal, error)
  • func (sp *StreamingProcess) Stderr() (io.ReadCloser, error)
  • func (sp *StreamingProcess) Stdin() (io.WriteCloser, error)
  • func (sp *StreamingProcess) Stdout() (io.ReadCloser, error)
  • func (sp *StreamingProcess) Stop() (err error)
  • func (sp *StreamingProcess) String() string
  • func (sp *StreamingProcess) Wait() (code int, err error)

Types

type Command

type Command struct {
	Process Process
	// contains filtered or unexported fields
}

Command is an object that allow interacting with an underlying process.

Unlike a Process, a command is safe to be called repeatedly and by multiple goroutines.

func (*Command) Cleanup

func (e *Command) Cleanup() error

Cleanup cleans up this process. Cleanup may be called at any point

func (*Command) Init

func (e *Command) Init(ctx context.Context, isTty bool) error

Init initializes the underlying process by providing it with an appropriate context. When context is nil, a new background context is initialized.

Once the context is closed, the command will be killed.

Init must be called once.

func (*Command) Start

func (e *Command) Start(Out, Err io.Writer, In io.Reader) error

Start starts the process and sends output to the provided streams. Calls Close() on the provided streams when they are closed.

Init() must be called before a call to Start(). If this is not the case, an error is returned.

Start() and StartPty() may only be called once. Subsequently calls will produce an error.

func (*Command) StartPty

func (e *Command) StartPty(tm io.ReadWriteCloser, TERM string, resizeChan <-chan term.WindowSize) error

StartPty runs this process on the given terminal.

Closes the Reader and Writer of tm using the semantics of DualCloser.

Init() must be called before a call to StartPty(). If this is not the case, an error is returned.

Start() and StartPty() may only be called once. Subsequently calls will produce an error.

func (*Command) Stop

func (e *Command) Stop() error

Stop stops the underlying process. When an underlying process is not running, returns an error. When the process has already finished running, returns nil.

func (*Command) Wait

func (e *Command) Wait() (int, error)

Wait waits for this process.

type DockerExecStreamer

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

DockerExecStreamer is a streamer that streams data to and from a remote docker exec process

func (*DockerExecStreamer) Attach

func (des *DockerExecStreamer) Attach(ctx context.Context, isPty bool) error

Attach attaches to this DockerExecStreamer

func (*DockerExecStreamer) Detach

func (des *DockerExecStreamer) Detach(ctx context.Context) error

Detach detaches from the stream

func (*DockerExecStreamer) Init

func (des *DockerExecStreamer) Init(ctx context.Context, Term string, isPty bool) error

Init initializes this docker exec streamer

func (*DockerExecStreamer) ResizeTo

func (des *DockerExecStreamer) ResizeTo(ctx context.Context, size term.WindowSize) error

ResizeTo resizes the remote stream

func (*DockerExecStreamer) Result

func (des *DockerExecStreamer) Result(ctx context.Context) (int, error)

Result returns the result of the stream

func (*DockerExecStreamer) StreamInput

func (des *DockerExecStreamer) StreamInput(ctx context.Context, stdin io.Reader, restoreTerms func(), doneChan chan struct{})

StreamInput streams input to the remote stream

func (*DockerExecStreamer) StreamOutput

func (des *DockerExecStreamer) StreamOutput(ctx context.Context, stdout, stderr io.Writer, restoreTerms func(), errChan chan error)

StreamOutput streams output from the remote stream

func (*DockerExecStreamer) String

func (des *DockerExecStreamer) String() string

type DualCloser

type DualCloser interface {
	Close() error      // Close closes the read stream of this object.
	CloseWrite() error // CloseWrite closes the write stream of this object.
}

DualCloser is an object that can close it's read and write streams.

func NewDualCloser

func NewDualCloser(closer io.Closer) DualCloser

NewDualCloser returns a new DualCloser that implements the semantics of closer.

When closer is a DualCloser return it unchanged. Otherwise returns a DualCloserWrapper.

type DualCloserWrapper

type DualCloserWrapper struct {

	// Closer may implement Closer or DualCloser
	Closer io.Closer
	// contains filtered or unexported fields
}

DualCloserWrapper implements DualCloser. It wraps an existing io.Closer and calls closer.Close() as soon as both Close() and CloseWrite() have been called.

The Close() and CloseWrite() methods can safely be called concurrently.

A DualCloserWrapper may not be copied.

func (*DualCloserWrapper) Close

func (w *DualCloserWrapper) Close() (err error)

Close syncronously calls Closer.Close() as soon as CloseWrite() and Close() have been called.

func (*DualCloserWrapper) CloseWrite

func (w *DualCloserWrapper) CloseWrite() (err error)

CloseWrite syncronously calls Closer.Close() as soon as CloseWrite() and Close() have been called.

type ExecProcess

type ExecProcess struct {
	Command string   // command to run
	Args    []string // arguments for the command
	Workdir string   // workding directory of the process, defaults to ""
	Env     []string // Environment variables of the form "KEY=VALUE"
	// contains filtered or unexported fields
}

ExecProcess ia a process that is executed via a syscall to exec(). It implements the Process interface.

func (*ExecProcess) Cleanup

func (sp *ExecProcess) Cleanup() error

Cleanup cleans up this process, typically killing it

func (*ExecProcess) Init

func (sp *ExecProcess) Init(ctx context.Context, isPty bool) error

Init initializes this process

func (*ExecProcess) Start

func (sp *ExecProcess) Start(Term string, resizeChan <-chan term.WindowSize, isPty bool) (term.Terminal, error)

Start starts this process

func (*ExecProcess) Stderr

func (sp *ExecProcess) Stderr() (io.ReadCloser, error)

Stderr returns a pipe to Stderr

func (*ExecProcess) Stdin

func (sp *ExecProcess) Stdin() (io.WriteCloser, error)

Stdin returns a pipe to Stdin

func (*ExecProcess) Stdout

func (sp *ExecProcess) Stdout() (io.ReadCloser, error)

Stdout returns a pipe to Stdout

func (*ExecProcess) Stop

func (sp *ExecProcess) Stop() (err error)

Stop is used to stop a running process.

func (*ExecProcess) String

func (sp *ExecProcess) String() string

String turns ShellProcess into a string

func (*ExecProcess) Wait

func (sp *ExecProcess) Wait() (code int, err error)

Wait waits for the process and returns the exit code

type Process

type Process interface {
	fmt.Stringer

	// Init initializes this process.
	// ctx represents a context that should be used to run the process in.
	// isPty indicates if this process should be run inside a pty and will be passed accordingly to Start().
	Init(ctx context.Context, isPty bool) error

	// Stdout returns the standard output of this process.
	Stdout() (io.ReadCloser, error)
	// Stderr returns the standard error of this process.
	Stderr() (io.ReadCloser, error)
	// Stdin returns the standard input of this process.
	Stdin() (io.WriteCloser, error)

	// Start starts this process and (if started on a pty) returns the appropriate terminal instance.
	//
	// Term is the name of tty to run this on. It is typically stored in the 'TERM' env variable.
	// resizeChan is a channel that will resize a WindowSize object everytime the tty is resized.
	// isPty indiccates if the process should be started on a pty. When it is false, Term and resizeChan will be zeroed.
	// when isPty is true, resizeChan is guaranteed to not be nil.
	//
	// The returned terminal, if any, should be closed by the caller and does not need to be manually cleaned up.
	Start(Term string, resizeChan <-chan term.WindowSize, isPty bool) (term.Terminal, error)

	// Stop is used to stop a process that is betweeen the start and wait phases.
	Stop() error

	// Wait waits for this process to exit and returns the exit code.
	Wait() (int, error)

	// Cleanup should be called at the end of the lifecyle of the process to clean it up.
	Cleanup() error
}

Process is an object that can be executed and has input and output streams.

A process may only be used by one caller at the same time; it is not goroutine safe. Apart from the String() method, methods may only be called at most once.

type Streamer

type Streamer interface {
	fmt.Stringer

	Init(ctx context.Context, Term string, isPty bool) error // init initializes this streamer

	StreamOutput(ctx context.Context, stdout, stderr io.Writer, restoreTerms func(), errChan chan error) // stream output streams output to stdout and stderr
	StreamInput(ctx context.Context, stdin io.Reader, restoreTerms func(), doneChan chan struct{})       // stream input streams input from stdin

	Attach(ctx context.Context, isPty bool) error             // attach attaches to this stream
	ResizeTo(ctx context.Context, size term.WindowSize) error // resize resizes the remote stream
	Result(ctx context.Context) (int, error)                  // result returns the exit code of the streamed process
	Detach(ctx context.Context) error                         // deteach detaches from this stream
}

Streamer represents a connection to a remote stream.

type StreamingProcess

type StreamingProcess struct {
	// environment
	Streamer Streamer
	// contains filtered or unexported fields
}

StreamingProcess represents a process that uses a streamer to connect to a remote process.

It automatically initializes a local (tty, pty) pair when needed.

func NewDockerExecProcess

func NewDockerExecProcess(client client.APIClient, containerID string, command []string) *StreamingProcess

NewDockerExecProcess creates a process that executes within a docker container.

func (*StreamingProcess) Cleanup

func (sp *StreamingProcess) Cleanup() error

Cleanup cleans up this process, typically to kill it.

func (*StreamingProcess) Init

func (sp *StreamingProcess) Init(ctx context.Context, isTerm bool) error

Init initializes this StreamingProcess

func (*StreamingProcess) Start

func (sp *StreamingProcess) Start(Term string, resizeChan <-chan term.WindowSize, isPty bool) (term.Terminal, error)

Start starts this process

func (*StreamingProcess) Stderr

func (sp *StreamingProcess) Stderr() (io.ReadCloser, error)

Stderr returns a pipe to Stderr

func (*StreamingProcess) Stdin

func (sp *StreamingProcess) Stdin() (io.WriteCloser, error)

Stdin returns a pipe to Stdin

func (*StreamingProcess) Stdout

func (sp *StreamingProcess) Stdout() (io.ReadCloser, error)

Stdout returns a pipe to Stdout

func (*StreamingProcess) Stop

func (sp *StreamingProcess) Stop() (err error)

Stop stops the streaming process

func (*StreamingProcess) String

func (sp *StreamingProcess) String() string

String turns StreamingProcess into a string

func (*StreamingProcess) Wait

func (sp *StreamingProcess) Wait() (code int, err error)

Wait waits for the process and returns the exit code