ctl

Documentation

Overview

Package ctl provides functionality for the runtime control of Granitic applications.

If the RuntimeControl facility is enabled for a Granitic application (see http://granitic.io/1.0/ref/runtime-control), the grnc-ctl command line utility can be used to issue commands to that application via HTTP. Note that the HTTP server and handlers instantiated to facilitate runtime control are completely separate from the HTTP server that handles user-defined web services.

Each command is associated with a component hosted in the IoC container that implements the ctl.Command interface described below. Granitic includes a number of built-in commands for common administration tasks, but users can create their own commands by implementing the Command interface on any component.

Index

• Constants
• func NewCommandClientError(message string) *ws.CategorisedError
• func NewCommandLogicError(message string) *ws.CategorisedError
• func NewCommandUnexpectedError(message string) *ws.CategorisedError
• type ByName
  • func (s ByName) Less(i, j int) bool
• type Command
• type CommandDecorator
  • func (cd *CommandDecorator) DecorateComponent(component *ioc.Component, container *ioc.ComponentContainer)
  • func (cd *CommandDecorator) OfInterest(component *ioc.Component) bool
• type CommandLogic
  • func (cl *CommandLogic) Process(ctx context.Context, req *ws.WsRequest, res *ws.WsResponse)
  • func (cl *CommandLogic) UnmarshallTarget() interface{}
  • func (cl *CommandLogic) Validate(ctx context.Context, se *ws.ServiceErrors, request *ws.WsRequest)
• type CommandManager
  • func (cm *CommandManager) All() []Command
  • func (cm *CommandManager) Find(name string) Command
  • func (cm *CommandManager) Register(command Command) error
• type CommandOutput
• type Commands
  • func (s Commands) Len() int
  • func (s Commands) Swap(i, j int)

Constants

const (
	Columns   = "COLUMNS"
	Paragraph = "PARAGRAPH"
)

A hint to the grnc-ctl command on how to render the output of a Command - either as paragraphs of free text or as two columns.

Functions

func NewCommandClientError

func NewCommandClientError(message string) *ws.CategorisedError

Creates a new *ws.CategorisedError of type ws.Client with the supplied message.

func NewCommandLogicError

func NewCommandLogicError(message string) *ws.CategorisedError

Creates a new *ws.CategorisedError of type ws.Logic with the supplied message.

func NewCommandUnexpectedError

func NewCommandUnexpectedError(message string) *ws.CategorisedError

Creates a new *ws.CategorisedError of type ws.Unexpected with the supplied message.

Types

type ByName

type ByName struct{ Commands }

Wrapping type to allow sorting of Commands by name

func (ByName) Less

func (s ByName) Less(i, j int) bool

Less returns true if the Command at index i has a name lexicographically earlier than the Command at index j.

type Command

type Command interface {
	// ExecuteCommand is called when grnc-ctl is used to invoke a command that matches this Command's Name() method.
	// It is expected to execute whatever functionality is represented by the Command and describe the outcome in a
	// *CommandOutput. If errors are encountered, they should be formatted and returned as a slice of *ws.CategorisedError.
	ExecuteCommand(qualifiers []string, args map[string]string) (*CommandOutput, []*ws.CategorisedError)

	// A unique name for this command. Names should be short and only contain letters, numbers, underscores and dashes.
	Name() string

	// A short description (recommended less than 80 characters) briefly explaining the purpose of the Command. This text
	// will be shown when a user runs grnc-ctl help
	Summmary() string

	// A formal description of how this Command should be called e.g. start [component] [-fw true] [-rc true].
	Usage() string

	// A detailed, free-text description of the purpose of this Command. This text will be shown when a user runs
	// grnc-ctl help command-name and each element of the slice will be rendered as a new paragraph.
	Help() []string
}

type CommandDecorator

type CommandDecorator struct {
	// Logger used by Granitic framework components. Automatically injected.
	FrameworkLogger logging.Logger

	// An instance of CommandManager to register discovered Commands with.
	CommandManager *CommandManager
}

Used by the Granitic IoC container to discover components implementing ctl.Command and registering them with an instance of ctl.CommandManager.

func (*CommandDecorator) DecorateComponent

func (cd *CommandDecorator) DecorateComponent(component *ioc.Component, container *ioc.ComponentContainer)

DecorateComponent registers the component with the CommandManager.

func (*CommandDecorator) OfInterest

func (cd *CommandDecorator) OfInterest(component *ioc.Component) bool

OfInterest checks to see if the supplied component implements ctl.Command.

type CommandLogic

type CommandLogic struct {
	// Logger used by Granitic framework components. Automatically injected.
	FrameworkLogger logging.Logger

	// An instance of CommandManager that contains all known commands.
	CommandManager *CommandManager
}

CommandLogic handles the validation of an HTTP call from grnc-ctl, matching that call to a ctl.Command and invoking that command. An instance of CommandLogic is automatically created as part of the RuntimeCtl facility and it is not required (or recommended) that user applications create components of this type.

func (*CommandLogic) Process

func (cl *CommandLogic) Process(ctx context.Context, req *ws.WsRequest, res *ws.WsResponse)

Implements handler.WsRequestProcessor. Whenever a valid request is handled, the name of the invoked command is logged at INFO level to assist with auditing.

func (*CommandLogic) UnmarshallTarget

func (cl *CommandLogic) UnmarshallTarget() interface{}

Implements handler.WsUnmarshallTarget

func (*CommandLogic) Validate

func (cl *CommandLogic) Validate(ctx context.Context, se *ws.ServiceErrors, request *ws.WsRequest)

Implements handler.WsRequestValidator.

type CommandManager

type CommandManager struct {
	// Logger used by Granitic framework components. Automatically injected.
	FrameworkLogger logging.Logger

	// A slice of command names that should not be registered, effectively disabling their use. Populated via configuration.
	Disabled []string

	// The contents of Disabled converted to a Set at facility instantiation time.
	DisabledLookup types.StringSet
	// contains filtered or unexported fields
}

Created as a component as part of the RuntimeCtl facility, CommandManager acts a registry for all components that implement ctl.Command. See http://granitic.io/1.0/ref/runtime-control for details on how to configure this component.

func (*CommandManager) All

func (cm *CommandManager) All() []Command

All returns a slice of all of the currently registered commands.

func (*CommandManager) Find

func (cm *CommandManager) Find(name string) Command

Find returns a command that has a Name() exactly matching the supplied string.

func (*CommandManager) Register

func (cm *CommandManager) Register(command Command) error

Register stores a reference to the supplied Command and will return it via the Find method, unless the name of the command is in the Disabled slice. Returns an error if the command's name is already in use.

type CommandOutput

type CommandOutput struct {
	// An optional text header that will be rendered as paragraph of text before the text of the OutputBody is displayed.
	OutputHeader string

	// Optional output text that will be rendered by grnc-ctl according to the hint in RenderHint. If column output is used,
	// each element in the outer slice is a row and each inner slice will be rendered as an indented column (up to a maxiumu of two
	// columns.
	OutputBody [][]string

	// Whether grnc-ctl should render the OutputBody as Columns or Paragraph
	RenderHint renderMode
}

A CommandOutput contains any output from a Command that should be displayed to the user of grnc-ctl.

type Commands

type Commands []Command

Convenience type to support sorting of slices of Commands.

func (Commands) Len

func (s Commands) Len() int

Len returns the number of Commands in the slice.

func (Commands) Swap

func (s Commands) Swap(i, j int)

Swap swaps the position of two Commands in a slice.