plugin

package
v0.0.0-...-900fa13 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 11, 2015 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	PluginTagPrefix      = "plugin"
	PluginExpandAllowed  = "expand"
	PluginExpandStartTag = "${"
	PluginExpandEndTag   = "}"
)
View Source 
const (
	// These PageScope constants determine which page a panel hooks into
	TaskPage    PageScope = "task"
	BuildPage   PageScope = "build"
	VersionPage PageScope = "version"

	// These pagePosition constants determine where on a page a panel is
	// injected. If no position is given, it defaults to PageCenter
	PageLeft   pagePosition = "Left"
	PageRight  pagePosition = "Right"
	PageCenter pagePosition = "Center"
)

Variables

View Source 
var Published []Plugin

Published is an array of all plugins that have made themselves visible to the Evergreen system. A Plugin can add itself by appending an instance of itself to this array on init, i.e. by adding the following to its source file: 

func init(){
	plugin.Publish(&MyCoolPlugin{})
}

This list is then used by Agent, API, and UI Server code to register the published plugins.

Functions

func ExpandValues 

func ExpandValues(input interface{}, expansions *command.Expansions) error

Taking in the input and expansions map, apply the expansions to any appropriate fields in the input. The input must be a pointer to a struct so that the underlying struct can be modified.

func GetTask 

func GetTask(request *http.Request) *model.Task

GetTask returns the task object for a plugin API request at runtime, it is a valuable helper function for API PluginRoute handlers.

func IsExpandable 

func IsExpandable(param string) bool

IsExpandable returns true if the passed in string contains an expandable parameter

func Publish 

func Publish(plugin Plugin)

Publish is called in a plugin's "init" func to announce that plugin's presence to the entire plugin package. This architecture is designed to make it easy to add new external plugin code to Evergreen by simply importing the new plugin's package in plugin/config/installed_plugins.go

Packages implementing the Plugin interface MUST call Publish in their init code in order for Evergreen to detect and use them.

See the documentation of the 10gen.com/mci/plugin/config package for more

func SetTask 

func SetTask(request *http.Request, task *model.Task)

SetTask puts the task for an API request into the context of a request. This task can be retrieved in a handler function by using "GetTask()"

func StaticWebRootFromSourceFile 

func StaticWebRootFromSourceFile() string

StaticWebRootFromSourceFile is a helper for quickly grabbing the folder of the source file that calls it. This makes it very easy to establish a static root for a plugin, by simply declaring: 

{StaticRoot: plugin.StaticWebRootFromSourceFile()}

in a plugin's PanelConfig definition.

func WriteJSON 

func WriteJSON(w http.ResponseWriter, statusCode int, data interface{})

WriteJSON writes data encoded in JSON format (Content-type: "application/json") to the ResponseWriter with the supplied HTTP status code. Writes a 500 error if the data cannot be JSON-encoded.

Types

type Command 

type Command interface {
	// ParseParams takes a map of fields to values extracted from
	// the project config and passes them to the command. Any
	// errors parsing the information are returned.
	ParseParams(params map[string]interface{}) error

	// Execute runs the command using the agent's logger, communicator,
	// task config, and a channel for interrupting long-running commands.
	// Execute is called after ParseParams.
	Execute(logger Logger, pluginCom PluginCommunicator,
		conf *model.TaskConfig, stopChan chan bool) error

	// A string name for the command
	Name() string

	// Plugin name
	Plugin() string
}

Command is an interface that defines a command for a plugin. A Command takes parameters as a map, and is executed after those parameters are parsed.

type ErrUnknownCommand 

type ErrUnknownCommand struct {
	CommandName string
}

ErrUnknownCommand indicates a command is referenced from a plugin that does not support it.

func (*ErrUnknownCommand) Error 

func (eup *ErrUnknownCommand) Error() string

type ErrUnknownPlugin 

type ErrUnknownPlugin struct {
	PluginName string
}

ErrUnknownPlugin indicates a plugin was requested that is not registered in the plugin manager.

func (*ErrUnknownPlugin) Error 

func (eup *ErrUnknownPlugin) Error() string

Error returns information about the non-registered plugin; satisfies the error interface

type Logger 

type Logger interface {
	// Log a message locally. Will be persisted in the log file on the builder, but
	// not appended to the log data sent to API server.
	LogLocal(level slogger.Level, messageFmt string, args ...interface{})

	// Log data about the plugin's execution.
	LogExecution(level slogger.Level, messageFmt string, args ...interface{})

	// Log data from the plugin's actual commands, e.g. shell script output or
	// stdout/stderr messages from a command
	LogTask(level slogger.Level, messageFmt string, args ...interface{})

	// Log system-level information (resource usage, ), etc.
	LogSystem(level slogger.Level, messageFmt string, args ...interface{})

	// Returns the log writer as an io.Writer, for use in io-related
	// functions, e.g. io.Copy
	GetTaskLogWriter(level slogger.Level) io.Writer

	// Trigger immediate flushing of any buffered log messages.
	Flush()
}

Logger allows any plugin to log to the appropriate place with any The agent (which provides each plugin execution with a Logger implementation) handles sending log data to the remote server

type PageScope 

type PageScope string

PageScope is a type for setting the page a panel appears on

type PanelConfig 

type PanelConfig struct {
	// StaticRoot is a filesystem path to a folder to establish
	// as the static web root for a plugin package. If this field is set,
	// the UI server will set up a file serving route for the plugin at
	//  /plugin/<plugin_name>/static
	// See StaticWebRootFromSourceFile() as a shortcut for setting this up
	StaticRoot string

	// Handler is an http.Handler which receives plugin-specific HTTP requests from the UI
	Handler http.Handler

	// Panels is an array of UIPanels to inject into task, version,
	// and build pages
	Panels []UIPanel
}

PanelConfig stores all UI-related plugin hooks

type PanelLayout 

type PanelLayout struct {
	Left   []template.HTML
	Right  []template.HTML
	Center []template.HTML
}

PanelLayout tells the view renderer what panel HTML data to inject and where on the page to inject it.

type PanelManager 

type PanelManager interface {
	RegisterPlugins([]Plugin) error
	Includes(PageScope) ([]template.HTML, error)
	Panels(PageScope) (PanelLayout, error)
	UIData(UIContext, PageScope) (map[string]interface{}, error)
}

PanelManager is the manager the UI server uses to register and load plugin UI information efficiently.

type Plugin 

type Plugin interface {
	// Returns the name to identify this plugin when registered.
	Name() string

	Configure(conf map[string]interface{}) error

	// Install any server-side handlers needed by this plugin in the API server
	GetAPIHandler() http.Handler

	// Install any server-side handlers needed by this plugin in the UI server
	GetUIHandler() http.Handler

	// GetPanelConfig returns a pointer to a plugin's UI configuration.
	// or an error, if an error occur while trying to generate the config
	// A nil pointer represents a plugin without a UI presence, and is
	// not an error.
	GetPanelConfig() (*PanelConfig, error)

	// Returns an ErrUnknownCommand if no such command exists
	NewCommand(commandName string) (Command, error)
}

Plugin defines the interface that all evergreen plugins must implement in order to register themselves with the agent and API/UI servers.

type PluginCommunicator 

type PluginCommunicator interface {

	// Make a POST request to the given endpoint by submitting 'data' as
	// the request body, marshalled as JSON.
	TaskPostJSON(endpoint string, data interface{}) (*http.Response, error)

	// Make a GET request to the given endpoint with content type "application/json"
	TaskGetJSON(endpoint string) (*http.Response, error)

	// Make a POST request against the results api endpoint
	TaskPostResults(results *model.TestResults) error

	// Make a POST request against the test_log api endpoint
	TaskPostTestLog(log *model.TestLog) (string, error)

	// Make a POST request against the files api endpoint
	PostTaskFiles(files []*artifact.File) error
}

PluginCommunicator is an interface that allows a plugin's client-side processing (running inside an agent) to communicate with the routes it has installed on the server-side via HTTP GET and POST requests. Does not handle retrying of requests. The caller must also ensure that the Body of the returned http responses are closed.

type Registry 

type Registry interface {
	// Make the given plugin available for usage with tasks.
	// Returns an error if the plugin is invalid, or conflicts with an already
	// registered plugin.
	Register(p Plugin) error

	// Parse the parameters in the given command and return a corresponding
	// Command. Returns ErrUnknownPlugin if the command refers to
	// a plugin that isn't registered, or some other error if the plugin
	// can't parse valid parameters from the command.
	GetCommands(command model.PluginCommandConf,
		funcs map[string]*model.YAMLCommandSet) ([]Command, error)

	// ParseCommandConf takes a plugin command and either returns a list of
	// command(s) defined by the function (if the plugin command is a function),
	// or a list containing the command itself otherwise.
	ParseCommandConf(command model.PluginCommandConf,
		funcs map[string]*model.YAMLCommandSet) ([]model.PluginCommandConf, error)
}

Registry manages available plugins, and produces instances of Commands from model.PluginCommandConf, a command's representation in the config.

type SimplePanelManager 

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

SimplePanelManager is a basic implementation of a plugin panel manager.

func (*SimplePanelManager) Includes 

func (self *SimplePanelManager) Includes(page PageScope) ([]template.HTML, error)

Includes returns a properly-ordered list of html tags to inject into the head of the view for the given page.

func (*SimplePanelManager) Panels 

func (self *SimplePanelManager) Panels(page PageScope) (PanelLayout, error)

Panels returns a PanelLayout for the view renderer to inject panels into the given page.

func (*SimplePanelManager) RegisterPlugins 

func (self *SimplePanelManager) RegisterPlugins(plugins []Plugin) error

RegisterPlugins takes an array of plugins and registers them with the manager. After this step is done, the other manager functions may be used.

func (*SimplePanelManager) UIData 

func (self *SimplePanelManager) UIData(context UIContext, page PageScope) (map[string]interface{}, error)

UIData returns a map of plugin name -> data for inclusion in the view's javascript.

type SimpleRegistry 

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

SimpleRegistry is a simple, local, map-based implementation of a plugin registry.

func NewSimpleRegistry 

func NewSimpleRegistry() *SimpleRegistry

NewSimpleRegistry returns an initialized SimpleRegistry

func (*SimpleRegistry) GetCommands 

func (sr *SimpleRegistry) GetCommands(cmd model.PluginCommandConf, funcs map[string]*model.YAMLCommandSet) ([]Command, error)

GetCommands finds a registered plugin for the given plugin command config Returns ErrUnknownPlugin if the cmd refers to a plugin that isn't registered, or some other error if the plugin can't parse valid parameters from the conf.

func (*SimpleRegistry) ParseCommandConf 

func (sr *SimpleRegistry) ParseCommandConf(cmd model.PluginCommandConf, funcs map[string]*model.YAMLCommandSet) ([]model.PluginCommandConf, error)

func (*SimpleRegistry) Register 

func (sr *SimpleRegistry) Register(p Plugin) error

Register makes a given plugin and its commands available to the agent code. This function returns an error if a plugin of the same name is already registered.

type UIContext 

type UIContext struct {
	Settings   evergreen.Settings
	User       *user.DBUser
	Task       *model.Task
	Build      *build.Build
	Version    *version.Version
	Patch      *patch.Patch
	Project    *model.Project
	ProjectRef *model.ProjectRef
}

UIContext stores all relevant models for a plugin page.

func MustHaveContext 

func MustHaveContext(request *http.Request) UIContext

MustHaveContext loads a UIContext from the http.Request. It panics if the context is not set.

type UIDataFunction 

type UIDataFunction func(context UIContext) (interface{}, error)

UIDataFunction is a function which is called to populate panels which are injected into Task/Build/Version pages at runtime.

type UIDataFunctionError 

type UIDataFunctionError []error

UIDataFunctionError is a special error type for data function processing which can record and aggregate multiple error messages.

func (*UIDataFunctionError) AppendError 

func (errs *UIDataFunctionError) AppendError(name string, err error)

AppendError adds an error onto the array of data function errors.

func (*UIDataFunctionError) Error 

func (errs *UIDataFunctionError) Error() string

Error returns a string aggregating the stored error messages. Implements the error interface.

func (*UIDataFunctionError) HasErrors 

func (errs *UIDataFunctionError) HasErrors() bool

HasErrors returns a boolean representing if the UIDataFunctionError contains any errors.

type UIPanel 

type UIPanel struct {
	// Page is which page the panel appears on
	Page PageScope

	// Position is the side of the page the panel appears in
	Position pagePosition

	// Includes is a list of HTML tags to inject into the head of
	// the page. These are meant to be links to css and js code hosted
	// in the plugin's static web root
	Includes []template.HTML

	// PanelHTML is the HTML definition of the panel. Best practices dictate
	// using AngularJS to load up the html as a partial hosted by the plugin
	PanelHTML template.HTML

	// DataFunc is a function to populate plugin data injected into the js
	// of the page the panel is on. The function takes the page request as
	// an argument, and returns data (must be json-serializeable!) or an error
	DataFunc UIDataFunction
}

UIPanel is a type for storing all the configuration to properly display one panel in one page of the UI.

Source Files

View all Source files

Directories

Path Synopsis
builtin
archive
attach
attach/xunit
expansions
git
gotest
helloworld
s3Plugin
s3copy
shell
The plugin/config package is used to manage which plugins are imported into MCI.
 The plugin/config package is used to manage which plugins are imported into MCI.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.