util

Documentation

Overview

Package util provides utility operations used in building sansshell system services.

Index

• Constants
• Variables
• func IsStreamToTerminal(stream io.Writer) bool
• func OptionSlicesEqual(a, b []Option) bool
• func OptionsEqual(a, b Option) bool
• func TrimString(s string) string
• func ValidPath(path string) error
• type CommandRun
  • func RunCommand(ctx context.Context, bin string, args []string, opts ...Option) (*CommandRun, error)
• type ExecuteState
• type IntSliceFlags
  • func (i *IntSliceFlags) Set(val string) error
  • func (i *IntSliceFlags) String() string
• type KeyValue
• type KeyValueSliceFlag
  • func (i *KeyValueSliceFlag) Set(val string) error
  • func (i *KeyValueSliceFlag) String() string
• type LimitedBuffer
  • func NewLimitedBuffer(max uint) *LimitedBuffer
  • func (l *LimitedBuffer) Bytes() []byte
  • func (l *LimitedBuffer) Read(p []byte) (int, error)
  • func (l *LimitedBuffer) String() string
  • func (l *LimitedBuffer) Truncated() bool
  • func (l *LimitedBuffer) Write(p []byte) (int, error)
• type Option
  • func CommandGroup(gid uint32) Option
  • func CommandUser(uid uint32) Option
  • func EnvVar(evar string) Option
  • func FailOnStderr() Option
  • func StderrMax(max uint) Option
  • func StdoutMax(max uint) Option
• type StringSliceCommaOrWhitespaceFlag
  • func (s *StringSliceCommaOrWhitespaceFlag) Set(val string) error
  • func (s *StringSliceCommaOrWhitespaceFlag) String() string
• type StringSliceFlag
  • func (s *StringSliceFlag) Set(val string) error
  • func (s *StringSliceFlag) String() string

Constants

const DefRunBufLimit = 10 * 1024 * 1024

DefRunBufLimit is the default limit we'll buffer for stdout/stderr from RunCommand exec'ing a process.

const MaxBuf = 1024

MaxBuf is the maximum we should allow stdout or stderr to be when sending back in an error string. grpc has limits on how large a returned error can be (generally 4-8k depending on language).

Variables

var StreamingChunkSize = 128 * 1024

StreamingChunkSize is the chunk size we use when sending replies on a stream. TODO(jchacon): Make this configurable

Functions

func IsStreamToTerminal

func IsStreamToTerminal(stream io.Writer) bool

IsStreamToTerminal checks if the stream is connected to a terminal Could not be covered with test, requires manual testing on changes

func OptionSlicesEqual

func OptionSlicesEqual(a, b []Option) bool

OptionsEqual returns true if the results of applying all elements of both Option slices are equal

func OptionsEqual

func OptionsEqual(a, b Option) bool

OptionsEqual returns true if the results of applying both Options are equal

func TrimString

func TrimString(s string) string

TrimString will return the given string truncated to MAX_BUF size so it can be used in grpc error replies.

func ValidPath

func ValidPath(path string) error

ValidPath ensures the path passed in is both absolute and clean.

Types

type CommandRun

type CommandRun struct {
	Stdout   *LimitedBuffer
	Stderr   *LimitedBuffer
	Error    error
	ExitCode int
}

CommandRun groups all of the status and output from executing a command.

func RunCommand

func RunCommand(ctx context.Context, bin string, args []string, opts ...Option) (*CommandRun, error)

RunCommand will take the given binary and args and execute it returning all relevent state (stdout, stderr, errors, etc). The returned buffers for stdout and stderr are limited by possible options but default limit to DefRunBufLimit.

The binary must be a clean absolute path or an error will result and nothing will be run. Any other errors (starting or from waiting) are recorded in the Error field. Errors returned directly will be a status.Error and Error will be whatever the exec library returns.

type ExecuteState

type ExecuteState struct {
	Conn *proxy.Conn
	// Dir is a directory where additional files per target can be written.
	Dir string
	// Output stream to write log lines related to particular target host.
	Out []io.Writer
	// Error stream to write log lines related to particular target host.
	Err []io.Writer
}

ExecuteState is used by client packages in services to pass relevant state down to subcommands.

type IntSliceFlags

type IntSliceFlags []int64

IntSliceFlags is a custom flag for a list of ints in a comma separated list.

func (*IntSliceFlags) Set

func (i *IntSliceFlags) Set(val string) error

Set - see flag.Value

func (*IntSliceFlags) String

func (i *IntSliceFlags) String() string

String - see flag.Value

type KeyValue

type KeyValue struct {
	Key   string
	Value string
}

KeyValue is used below with KeyValueSliceFlag to construct foo=bar,baz=foo type of flags.

type KeyValueSliceFlag

type KeyValueSliceFlag []*KeyValue

KeyValueSliceFlag is a custom flag for a list of strings in a comma separated list of the form key=value,key=value

func (*KeyValueSliceFlag) Set

func (i *KeyValueSliceFlag) Set(val string) error

Set - see flag.Value

func (*KeyValueSliceFlag) String

func (i *KeyValueSliceFlag) String() string

String - see flag.Value

type LimitedBuffer

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

LimitedBuffer is a bytes.Buffer with the added limitation that it will not grow infinitely and will instead stop at a max size limit.

func NewLimitedBuffer

func NewLimitedBuffer(max uint) *LimitedBuffer

NewLimitedBuffer will create a LimitedBuffer with the given maximum size.

func (*LimitedBuffer) Bytes

func (l *LimitedBuffer) Bytes() []byte

Bytes - see bytes.Buffer

func (*LimitedBuffer) Read

func (l *LimitedBuffer) Read(p []byte) (int, error)

Read - see io.Reader

func (*LimitedBuffer) String

func (l *LimitedBuffer) String() string

String - see bytes.Buffer

func (*LimitedBuffer) Truncated

func (l *LimitedBuffer) Truncated() bool

Truncated will return true if the LimitedBuffer has filled and refused to write additional bytes.

func (*LimitedBuffer) Write

func (l *LimitedBuffer) Write(p []byte) (int, error)

Write acts exactly as a bytes.Buffer defines except if the underlying buffer has reached the max size no more bytes will be added. TODO: Implement remaining bytes.Buffer methods if needed. NOTE:

This is not an error condition and instead no more bytes
will be written and normal return will happen so writes
do not fail. Use the Truncated() method
to determine if this has happened.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option will run the apply operation to change required checking/state before executing RunCommand.

func CommandGroup

func CommandGroup(gid uint32) Option

CommandGroup is an option which sets the gid for the Command to run as.

func CommandUser

func CommandUser(uid uint32) Option

CommandUser is an option which sets the uid for the Command to run as.

func EnvVar

func EnvVar(evar string) Option

EnvVar is an option which sets an environment variable for the sub-processes. evar should be of the form foo=bar

func FailOnStderr

func FailOnStderr() Option

FailOnStderr is an option where the command will return an error if any output appears on stderr regardless of exit code. As we're often parsing the text output of specific commands as root this is a sanity check we're getting expected output. i.e. ps never returns anything on stderr so if some run does that's suspect. Up to callers to decide as some tools (yum...) like to emit stderr as debugging as they run.

func StderrMax

func StderrMax(max uint) Option

StderrMax is an option where the command run will limit output buffered from stdout to this many bytes before truncating.

func StdoutMax

func StdoutMax(max uint) Option

StdoutMax is an option where the command run will limit output buffered from stdout to this many bytes before truncating.

type StringSliceCommaOrWhitespaceFlag

type StringSliceCommaOrWhitespaceFlag struct {
	Target *[]string
}

StringSliceCommaOrWhitespaceFlag is the parsed form of a flag accepting either "foo,bar,baz" or "foo bar baz" style. This is useful in cases where we want to be more flexible in the input values we accept.

func (*StringSliceCommaOrWhitespaceFlag) Set

func (s *StringSliceCommaOrWhitespaceFlag) Set(val string) error

Set - see flag.Value

func (*StringSliceCommaOrWhitespaceFlag) String

func (s *StringSliceCommaOrWhitespaceFlag) String() string

String - see flag.String

type StringSliceFlag

type StringSliceFlag struct {
	Target *[]string
}

StringSliceFlag is the parsed form of a flag using "foo,bar,baz" style.

func (*StringSliceFlag) Set

func (s *StringSliceFlag) Set(val string) error

Set - see flag.Value

func (*StringSliceFlag) String

func (s *StringSliceFlag) String() string

String - see flag.String