plugin

package
v0.0.0-...-eeee692 Latest Latest
Warning

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

 Go to latest Published: May 25, 2017 License: Apache-2.0 Imports: 23 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 (
	// These are slices of all plugins that have made themselves
	// visible to the Evergreen system. A Plugin can add itself by appending an instance
	// of itself to these slices 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.
	CommandPlugins []CommandPlugin
	APIPlugins     []APIPlugin
	UIPlugins      []UIPlugin
)

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) *task.Task

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

func GetUser 

func GetUser(r *http.Request) *user.DBUser

GetUser fetches the user, if it exists, from the request context.

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. A plugin must also implement one of CommandPlugin, APIPlugin, or UIPlugin in order to be useable.

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

func SetTask 

func SetTask(request *http.Request, task *task.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 SetUser 

func SetUser(u *user.DBUser, r *http.Request)

SetUser sets the user for the request context. This is a helper for UI middleware.

func TemplateRoot 

func TemplateRoot(name string) string

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 APIPlugin 

type APIPlugin interface {
	Plugin

	// Configure reads in a settings map from the Evergreen config file.
	Configure(conf map[string]interface{}) error

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

APIPlugin is implemented by plugins that need to add new API hooks for new task commands. TODO: should this also require PluginCommand be implemented?

type AppUIPlugin 

type AppUIPlugin interface {
	UIPlugin

	// GetAppPluginInfo returns all the information
	// needed for the UI server to render a page from the navigation bar.
	GetAppPluginInfo() *UIPage
}

AppUIPlugin represents a UIPlugin that also has a page route.

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 CommandPlugin 

type CommandPlugin interface {
	Plugin

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

CommandPlugin is implemented by plugins that add new task commands that are run by the agent.

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 task log writer as an io.Writer, for use in io-related
	// functions, e.g. io.Copy
	GetTaskLogWriter(level slogger.Level) io.Writer

	// Returns the system log writer as an io.Writer, for use in io-related
	// functions, e.g. io.Copy
	GetSystemLogWriter(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 {
	// 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([]UIPlugin) error
	Includes(PageScope) ([]template.HTML, error)
	Panels(PageScope) (PanelLayout, error)
	UIData(UIContext, PageScope) (map[string]interface{}, error)
	GetAppPlugins() []AppUIPlugin
}

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
}

Plugin defines the interface that all evergreen plugins must implement in order to register themselves with Evergreen. A plugin must also implement one of the PluginCommand, APIPlugin, or UIPlugin interfaces in order to do useful work.

type PluginCommunicator 

type PluginCommunicator interface {

	// Make a POST request to the given endpoint by submitting 'data' as
	// the request body, marshaled 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 *task.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 CommandPlugin) 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) GetAppPlugins 

func (self *SimplePanelManager) GetAppPlugins() []AppUIPlugin

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 []UIPlugin) 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 CommandPlugin) 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       *task.Task
	Build      *build.Build
	Version    *version.Version
	Patch      *patch.Patch
	Project    *model.Project
	ProjectRef *model.ProjectRef
	Request    *http.Request
}

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 UIPage 

type UIPage struct {
	TemplatePath string
	DataFunc     UIDataFunction
}

UIPage represents the information to be sent over to the ui server in order to render a page for an app level plugin. TemplatePath is the relative path to the template from the template root of the plugin. Data represents the data to send over.

type UIPanel 

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

	// 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
	// Position is the side of the page the panel appears in
	Position pagePosition
}

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

type UIPlugin 

type UIPlugin interface {
	Plugin

	// 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)

	// Configure reads in a settings map from the Evergreen config file.
	Configure(conf map[string]interface{}) error
}

Source Files

View all Source files

Directories

Path Synopsis
builtin
archive
attach
attach/xunit
expansions
git
gotest
helloworld
manifest
s3
s3copy
shell
taskdata
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.