granitic: Index | Files

package ctl

import ""

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

If the RuntimeControl facility is enabled for a Granitic application (see ), 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.


Package Files

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


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

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

func NewCommandLogicError Uses

func NewCommandLogicError(message string) *ws.CategorisedError

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

func NewCommandUnexpectedError Uses

func NewCommandUnexpectedError(message string) *ws.CategorisedError

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

type ByName Uses

type ByName struct{ Commands }

ByName is a 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

A Command represents an instruction that can be sent to Granitic to operate on a running instance of an application.

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

CommandDecorator is 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.Request, res *ws.Response)

Process implements handler.WsRequestProcessor.Process 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{}

UnmarshallTarget Implements handler.WsUnmarshallTarget.UnmarshallTarget

func (*CommandLogic) Validate Uses

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

Validate implements handler.WsRequestValidator.Validate

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

A CommandManager is created as a component as part of the RuntimeCtl facility, CommandManager acts a registry for all components that implement ctl.Command. See 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

Commands is a 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). Updated 2020-05-30. Refresh now. Tools for package owners.