mcorpc

Documentation

Overview

Package mcorpc provides a compatibility layer between Choria and legacy MCollective SimpleRPC Agents

Agents can be written in the Go language, compiled into the binaries and be interacted with from the ruby MCollective client.

It's planned to provide a backward compatible interface so that old ruby agents, authorization and auditing will be usable inside the Choria daemon via a shell-out mechanism

Index

• Constants
• func NewChoriaAgentPlugin(metadata *agents.Metadata, ...) plugin.Pluggable
• func ParseRequestData(target interface{}, request *Request, reply *Reply) bool
• type Action
• type ActivationChecker
• type Agent
  • func New(name string, metadata *agents.Metadata, fw ChoriaFramework, log *logrus.Entry) *Agent
  • func (a *Agent) ActionNames() []string
  • func (a *Agent) HandleMessage(ctx context.Context, msg *choria.Message, request protocol.Request, ...)
  • func (a *Agent) Metadata() *agents.Metadata
  • func (a *Agent) MustRegisterAction(name string, f Action)
  • func (a *Agent) Name() string
  • func (a *Agent) RegisterAction(name string, f Action) error
  • func (a *Agent) ServerInfo() agents.ServerInfoSource
  • func (a *Agent) SetActivationChecker(ac ActivationChecker)
  • func (a *Agent) SetServerInfo(si agents.ServerInfoSource)
  • func (a *Agent) ShouldActivate() bool
• type AgentPlugin
  • func (p *AgentPlugin) PluginInstance() interface{}
  • func (p *AgentPlugin) PluginName() string
  • func (p *AgentPlugin) PluginType() plugin.Type
  • func (p *AgentPlugin) PluginVersion() string
• type ChoriaFramework
• type Reply
• type Request
• type StatusCode

Constants

const (
	// OK is the reply status when all worked
	OK = StatusCode(iota)

	// Aborted is status for when the action could not run, most failures in an action should set this
	Aborted

	// UnknownAction is the status for unknown actions requested
	UnknownAction

	// MissingData is the status for missing input data
	MissingData

	// InvalidData is the status for invalid input data
	InvalidData

	// UnknownError is the status general failures in agents should set when things go bad
	UnknownError
)

Functions

func NewChoriaAgentPlugin

func NewChoriaAgentPlugin(metadata *agents.Metadata, creator func(mgr server.AgentManager) (agents.Agent, error)) plugin.Pluggable

NewChoriaAgentPlugin creates a new plugin for an agent that allows it to plug into the Choria Plugin system

func ParseRequestData

func ParseRequestData(target interface{}, request *Request, reply *Reply) bool

ParseRequestData parses the request parameters received from the client into a target structure

Validation is supported, the example below does a `shellsafe` check on the data prior to returning it, should the check fail appropriate errors will be set on the reply data

Example used in a action:

  var rparams struct {
     Package string `json:"package" validate:"shellsafe"`
  }

  if !mcorpc.ParseRequestData(&rparams, req, reply) {
    // the function already set appropriate errors on reply
	   return
  }

  // do stuff with rparams.Package

Types

type Action

type Action func(context.Context, *Request, *Reply, *Agent, choria.ConnectorInfo)

Action is a function that implements a RPC Action

type ActivationChecker

type ActivationChecker func() bool

ActivationChecker is a function that can determine if an agent should be activated

type Agent

type Agent struct {
	Log              *logrus.Entry
	Config           *config.Config
	Choria           ChoriaFramework
	ServerInfoSource agents.ServerInfoSource
	// contains filtered or unexported fields
}

Agent is an instance of the MCollective compatible RPC agents

func New

func New(name string, metadata *agents.Metadata, fw ChoriaFramework, log *logrus.Entry) *Agent

New creates a new MCollective SimpleRPC compatible agent

func (*Agent) ActionNames

func (a *Agent) ActionNames() []string

ActionNames returns a list of known actions in the agent

func (*Agent) HandleMessage

func (a *Agent) HandleMessage(ctx context.Context, msg *choria.Message, request protocol.Request, conn choria.ConnectorInfo, outbox chan *agents.AgentReply)

HandleMessage attempts to parse a choria.Message as a MCollective SimpleRPC request and calls the agents and actions associated with it

func (*Agent) Metadata

func (a *Agent) Metadata() *agents.Metadata

Metadata retrieves the agent metadata

func (*Agent) MustRegisterAction

func (a *Agent) MustRegisterAction(name string, f Action)

MustRegisterAction registers an action and panics if it fails

func (*Agent) Name

func (a *Agent) Name() string

Name retrieves the name of the agent

func (*Agent) RegisterAction

func (a *Agent) RegisterAction(name string, f Action) error

RegisterAction registers an action into the agent

func (*Agent) ServerInfo

func (a *Agent) ServerInfo() agents.ServerInfoSource

ServerInfo returns the stored server info source

func (*Agent) SetActivationChecker

func (a *Agent) SetActivationChecker(ac ActivationChecker)

SetActivationChecker sets the function that can determine if the agent should be active

func (*Agent) SetServerInfo

func (a *Agent) SetServerInfo(si agents.ServerInfoSource)

SetServerInfo stores the server info source that owns this agent

func (*Agent) ShouldActivate

func (a *Agent) ShouldActivate() bool

ShouldActivate checks if the agent should be active using the method set in SetActivationChecker

type AgentPlugin

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

AgentPlugin is a choria plugin

func (*AgentPlugin) PluginInstance

func (p *AgentPlugin) PluginInstance() interface{}

PluginInstance implements plugin.Pluggable

func (*AgentPlugin) PluginName

func (p *AgentPlugin) PluginName() string

PluginName implements plugin.Pluggable

func (*AgentPlugin) PluginType

func (p *AgentPlugin) PluginType() plugin.Type

PluginType implements plugin.Pluggable

func (*AgentPlugin) PluginVersion

func (p *AgentPlugin) PluginVersion() string

PluginVersion implements plugin.Pluggable

type ChoriaFramework

type ChoriaFramework interface {
	Configuration() *config.Config
	FacterDomain() (string, error)
	FacterCmd() string
	MiddlewareServers() (srvcache.Servers, error)
	BuildInfo() *build.Info
	NewTransportFromJSON(data string) (message protocol.TransportMessage, err error)
	ProvisionMode() bool
	UniqueID() string
	NewRequestID() (string, error)
	Certname() string
}

ChoriaFramework provides access to the choria framework

type Reply

type Reply struct {
	Statuscode      StatusCode  `json:"statuscode"`
	Statusmsg       string      `json:"statusmsg"`
	Data            interface{} `json:"data"`
	DisableResponse bool        `json:"-"`
}

Reply is the reply data as stipulated by MCollective RPC system. The Data has to be something that can be turned into JSON using the normal Marshal system

type Request

type Request struct {
	Agent      string           `json:"agent"`
	Action     string           `json:"action"`
	Data       json.RawMessage  `json:"data"`
	RequestID  string           `json:"requestid"`
	SenderID   string           `json:"senderid"`
	CallerID   string           `json:"callerid"`
	Collective string           `json:"collective"`
	TTL        int              `json:"ttl"`
	Time       time.Time        `json:"time"`
	Filter     *protocol.Filter `json:"-"`
}

Request is a request as defined by the MCollective RPC system. The input data is stored in Data as JSON text unprocessed, the system at this level has no idea what is in there. In your Agent you can choose to use the ParseRequestData function to translate this for you or just do whatever JSON parsing you like

type StatusCode

type StatusCode uint8

StatusCode is a reply status as defined by MCollective SimpleRPC - integers 0 to 5

See the constants OK, RPCAborted, UnknownRPCAction, MissingRPCData, InvalidRPCData and UnknownRPCError