granitic: github.com/graniticio/granitic/ctl Index | Files

package ctl

import "github.com/graniticio/granitic/ctl"

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

Package Files

command.go decorator.go handler.go manager.go

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.

func NewCommandClientError Uses

func NewCommandClientError(message string) *ws.CategorisedError

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

func NewCommandLogicError Uses

func NewCommandLogicError(message string) *ws.CategorisedError

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

func NewCommandUnexpectedError Uses

func NewCommandUnexpectedError(message string) *ws.CategorisedError

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

type ByName Uses

type ByName struct{ Commands }

Wrapping type to allow sorting of Commands by name

func (ByName) Less Uses

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 Uses

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 Uses

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 Uses

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

DecorateComponent registers the component with the CommandManager.

func (*CommandDecorator) OfInterest Uses

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

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

type CommandLogic Uses

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 Uses

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 Uses

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

Implements handler.WsUnmarshallTarget

func (*CommandLogic) Validate Uses

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

Implements handler.WsRequestValidator.

type CommandManager Uses

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 Uses

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

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

func (*CommandManager) Find Uses

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

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

func (*CommandManager) Register Uses

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 Uses

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 Uses

type Commands []Command

Convenience type to support sorting of slices of Commands.

func (Commands) Len Uses

func (s Commands) Len() int

Len returns the number of Commands in the slice.

func (Commands) Swap Uses

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

Swap swaps the position of two Commands in a slice.

Package ctl imports 10 packages (graph) and is imported by 2 packages. Updated 2018-02-10. Refresh now. Tools for package owners.