plugin

README

Adding a Plugin

To add a plugin, create a new .go file in the traffic_ops_golang/plugin directory. This file should have a unique name, to avoid conflicts. Consider prefixing it with your company name, website, or a UUID.

The filename, sans .go, is the name of your plugin, and will be the key used for configuration in the remap file. For example, if your file is f49e54fc-fd17-4e1c-92c6-67028fde8504-hello-world.go, the name of your plugin is f49e54fc-fd17-4e1c-92c6-67028fde8504-hello-world.

Plugins are registered via calls to AddPlugin inside an init function in the plugin's file. The AddPlugin function takes a priority, a set of hook functions, a description, and a version of the plugin. The priority is the order in which plugins are called, starting from 0. Note the priority of plugins included with Traffic Control use a base priority of 10000, unless priority order matters for them.

The Funcs object contains functions for each hook, as well as a load function for loading configuration from the remap file. The current hooks are load, startup, and onRequest. If your plugin does not use a hook, it may be nil.

• load is called when the application starts, is given config data, and must return the loaded configuration object.

• startup is called when the application starts.

• onRequest is called immediately when a request is received. It returns a boolean indicating whether to stop processing. Note this is called without authentication. If a plugin should be authenticated, it must do so itself. It is recommended to use api.GetUserFromReq, which will return an error if authentication fails.

The simplest example is the hello_world plugin. See plugin/hello_world.go.

import (
	"strings"
)
func init() {
	AddPlugin(10000, Funcs{onRequest: hello}, "example HTTP plugin", "1.0.0")
}
const HelloPath = "/_hello"
func hello(d OnRequestData) IsRequestHandled {
	if !strings.HasPrefix(d.R.URL.Path, HelloPath) {
		return RequestUnhandled
	}
	d.W.Header().Set("Content-Type", "text/plain")
	d.W.Write([]byte("Hello, World!"))
	return RequestHandled
}

The plugin is initialized via AddPlugin, and its hello function is set as the startup hook. The hello function has the signature of plugin.StartupFunc.

Examples

Example plugins are included in the /plugin directory

hello_world: Example of a simple HTTP endpoint. hello_config: Example of loading and using config file data. hello_shared_config: Example of loading and using config data which is shared among all plugins. hello_context: Example of passing context data between hook functions. hello_startup: Example of running a plugin function when the application starts.

Glossary

Definitions of terms used in this document.

Plugin: A self-contained component whose code is executed when certain events in the main application occur. Hook: A plugin function which is called when a certain event happens in the main application. Plugin Data: Application data given to a plugin, as a function parameter passed to a hook function, including configuration data, running state, and HTTP request state.

Documentation

Index

• Constants
• func AddPlugin(priority uint64, funcs Funcs, description, version string)
• func List() []string
• type Data
• type Funcs
• type HelloConfig
• type Info
• type IsRequestHandled
• type LoadFunc
• type OnRequestData
• type OnRequestFunc
• type Plugins
  • func Get(appCfg config.Config) Plugins
• type ProxyConfig
• type ProxyRemap
  • func (r *ProxyRemap) UnmarshalJSON(b []byte) error
• type StartupData
• type StartupFunc

Constants

const (
	RequestHandled   = IsRequestHandled(true)
	RequestUnhandled = IsRequestHandled(false)
)

const HelloMiddlewarePath = "/_hello_middleware"

const HelloPath = "/_hello"

Functions

func AddPlugin

func AddPlugin(priority uint64, funcs Funcs, description, version string)

func List

func List() []string

List returns the list of plugin names compiled into the calling executable.

Types

type Data

type Data struct {
	Cfg       interface{}
	Ctx       *interface{}
	SharedCfg map[string]interface{}
	RequestID uint64
	AppCfg    config.Config
}

Data is the common plugin data, given to most plugin hooks. This is designed to be embedded in the data structs for specific hooks.

type Funcs

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

type HelloConfig

type HelloConfig struct {
	Hello string `json:"hello"`
}

type Info

type Info struct {
	Name        string
	Description string
	Version     string
}

type IsRequestHandled

type IsRequestHandled bool

type LoadFunc

type LoadFunc func(json.RawMessage) interface{}

type OnRequestData

type OnRequestData struct {
	Data
	W http.ResponseWriter
	R *http.Request
}

type OnRequestFunc

type OnRequestFunc func(d OnRequestData) IsRequestHandled

type Plugins

type Plugins interface {
	OnStartup(d StartupData)
	OnRequest(d OnRequestData) bool
	GetInfo() []Info
}

func Get

func Get(appCfg config.Config) Plugins

type ProxyConfig

type ProxyConfig []ProxyRemap

type ProxyRemap

type ProxyRemap struct {
	Path string   `json:"path"`
	URI  *url.URL `json:"uri"`
}

func (*ProxyRemap) UnmarshalJSON

func (r *ProxyRemap) UnmarshalJSON(b []byte) error

type StartupData

type StartupData struct {
	Data
}

type StartupFunc

type StartupFunc func(d StartupData)