command

Documentation

Overview

Package command facilitates calling commands within the guest-agent.

Index

• Variables
• func Close(_ context.Context)
• func PipeName(listener KnownListeners) string
• func SendCommand(ctx context.Context, req []byte, listener KnownListeners) []byte
• func Setup(ctx context.Context, listener KnownListeners) error
• type Handler
• type KnownListeners
  • func (l KnownListeners) String() string
• type Monitor
  • func CurrentMonitor() *Monitor
  • func (m *Monitor) Close() error
  • func (m *Monitor) RegisterHandler(cmd string, f Handler) error
  • func (m *Monitor) Start(ctx context.Context) error
  • func (m *Monitor) UnregisterHandler(cmd string) error
• type Request
• type Response
• type Server
  • func (c *Server) Close() error

Variables

var (
	// CmdNotFoundError is return when there is no handler for the request
	// command.
	CmdNotFoundError = Response{
		Status:        101,
		StatusMessage: "Could not find a handler for the requested command",
	}
	// BadRequestError is returned for invalid or unparseable JSON
	BadRequestError = Response{
		Status:        102,
		StatusMessage: "Could not parse valid JSON from request",
	}
	// ConnError is returned for errors from the underlying communication
	// protocol.
	ConnError = Response{
		Status:        103,
		StatusMessage: "Connection error",
	}
	// TimeoutError is returned when the timeout period elapses before valid JSON
	// is received.
	TimeoutError = Response{
		Status:        104,
		StatusMessage: "Connection timeout before reading valid request",
	}
	// HandlerError is returned when the handler function returns an non-nil
	// error. The status message will be replaced with the returned error string.
	HandlerError = Response{
		Status:        105,
		StatusMessage: "The command handler encountered an error processing your request",
	}
)

Functions

func Close

func Close(_ context.Context)

Close will close the internally managed command server, if it was initialized.

func PipeName

func PipeName(listener KnownListeners) string

PipeName returns the pipe for a given listener. Its basically a full pipe path as cfg.Unstable.CommandPipePath being the directory and id name.

func SendCommand

func SendCommand(ctx context.Context, req []byte, listener KnownListeners) []byte

SendCommand sends a command request over the configured pipe.

func Setup

func Setup(ctx context.Context, listener KnownListeners) error

Setup starts an internally managed command server. The agent configuration will decide the server options.

Types

type Handler

type Handler func(context.Context, []byte) ([]byte, error)

Handler functions are the business logic of commands. They must process json encoded as a byte slice which contains a Command field and optional arbitrary data, and return json which contains a Status, StatusMessage, and optional arbitrary data (again encoded as a byte slice). Returned errors will be passed onto the command requester.

type KnownListeners

type KnownListeners int

KnownListeners is the set of known pipes that can be used to send commands.

const (
	// ListenerGuestAgent pipe sends command to a running Guest Agent.
	ListenerGuestAgent KnownListeners = iota
	// ListenerCorePlugin pipe sends command to a running core plugin.
	ListenerCorePlugin
)

func (KnownListeners) String

func (l KnownListeners) String() string

String returns the string representation of the KnownListeners enum which help print enum fields as string when used with `%v` for example instead of numbers. Additionally, same string representation is used as identifiers.

type Monitor

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

Monitor is the structure which handles command registration and deregistration.

func CurrentMonitor

func CurrentMonitor() *Monitor

CurrentMonitor returns the current command monitor which can be used to register command handlers.

func (*Monitor) Close

func (m *Monitor) Close() error

Close stops the server from listening to commands.

func (*Monitor) RegisterHandler

func (m *Monitor) RegisterHandler(cmd string, f Handler) error

RegisterHandler registers f as the handler for cmd. If a command.Server has been initialized, it will be signalled to start listening for commands.

func (*Monitor) Start

func (m *Monitor) Start(ctx context.Context) error

Start begins listening for commands.

func (*Monitor) UnregisterHandler

func (m *Monitor) UnregisterHandler(cmd string) error

UnregisterHandler clears the handlers for cmd. If a command.Server has been initialized and there are no more handlers registered, the server will be signalled to stop listening for commands.

type Request

type Request struct {
	Command string
}

Request is the basic request structure. Command determines which handler the request is routed to. Callers may set additional arbitrary fields.

type Response

type Response struct {
	// Status code for the request. Meaning is defined by the caller, but
	// conventionally zero is success.
	Status int
	// StatusMessage is an optional message defined by the caller. Should
	// generally help a human understand what happened.
	StatusMessage string
}

Response is the basic response structure. Handlers may set additional arbitrary fields.

type Server

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

Server is the server structure which will listen for command requests and route them to handlers. Most callers should not interact with this directly.

func (*Server) Close

func (c *Server) Close() error

Close signals the server to stop listening for commands and stop waiting to listen.