plugin

README

Plugins

Plugins are a way of extending the functionality of Micro

Overview

Plugins enable Micro to be extending and intercepted to provide additional functionality and features. This may include logging, metrics, tracing, authentication, etc. The Plugin model requires registering a struct that matches a plugin interface. It's then registered and setup when Micro starts.

Design

Here's the interface design

// Plugin is the interface for plugins to micro. It differs from go-micro in that it's for
// the micro API, Web, Sidecar, CLI. It's a method of building middleware for the HTTP side.
type Plugin interface {
	// Global Flags
	Flags() []cli.Flag
	// Sub-commands
	Commands() []cli.Command
	// Handle is the middleware handler for HTTP requests. We pass in
	// the existing handler so it can be wrapped to create a call chain.
	Handler() Handler
	// Init called when command line args are parsed.
	// The initialized cli.Context is passed in.
	Init(*cli.Context) error
	// Name of the plugin
	String() string
}

// Manager is the plugin manager which stores plugins and allows them to be retrieved.
// This is used by all the components of micro.
type Manager interface {
        Plugins() map[string]Plugin
        Register(name string, plugin Plugin) error
}

// Handler is the plugin middleware handler which wraps an existing http.Handler passed in.
// Its the responsibility of the Handler to call the next http.Handler in the chain.
type Handler func(http.Handler) http.Handler

How to use it

Here's a simple example of a plugin that adds a flag and then prints the value

The plugin

Create a plugin.go file in the top level dir

package main

import (
	"log"
	"github.com/urfave/cli/v2"
	"github.com/micro-community/micro/plugin"
)

func init() {
	plugin.Register(plugin.NewPlugin(
		plugin.WithName("example"),
		plugin.WithFlag(&cli.StringFlag{
			Name:   "example_flag",
			Usage:  "This is an example plugin flag",
			EnvVars: []string{"EXAMPLE_FLAG"},
			Value: "avalue",
		}),
		plugin.WithInit(func(ctx *cli.Context) error {
			log.Println("Got value for example_flag", ctx.String("example_flag"))
			return nil
		}),
	))
}

Building the code

Simply build micro with the plugin

go build -o micro ./main.go ./plugin.go

Documentation

Index

• func IsRegistered(plugin Plugin, opts ...PluginOption) bool
• func Register(plugin Plugin, opts ...PluginOption) error
• type Handler
• type Manager
  • func NewManager() Manager
• type Option
  • func WithCommand(cmd ...*cli.Command) Option
  • func WithFlag(flag ...cli.Flag) Option
  • func WithHandler(h ...Handler) Option
  • func WithInit(fn func(*cli.Context) error) Option
  • func WithName(n string) Option
• type Options
• type Plugin
  • func NewPlugin(opts ...Option) Plugin
  • func Plugins(opts ...PluginOption) []Plugin
• type PluginOption
  • func Module(m string) PluginOption
• type PluginOptions

Functions

func IsRegistered

func IsRegistered(plugin Plugin, opts ...PluginOption) bool

IsRegistered check plugin whether registered global. Notice plugin is not check whether is nil

func Register

func Register(plugin Plugin, opts ...PluginOption) error

Register registers a global plugins

Types

type Handler

type Handler func(http.Handler) http.Handler

Handler is the plugin middleware handler which wraps an existing http.Handler passed in. Its the responsibility of the Handler to call the next http.Handler in the chain.

type Manager

type Manager interface {
	Plugins(...PluginOption) []Plugin
	Register(Plugin, ...PluginOption) error
}

Manager is the plugin manager which stores plugins and allows them to be retrieved. This is used by all the components of micro.

func NewManager

func NewManager() Manager

NewManager creates a new plugin manager

type Option

type Option func(o *Options)

func WithCommand

func WithCommand(cmd ...*cli.Command) Option

WithCommand adds commands to a plugin

func WithFlag

func WithFlag(flag ...cli.Flag) Option

WithFlag adds flags to a plugin

func WithHandler

func WithHandler(h ...Handler) Option

WithHandler adds middleware handlers to

func WithInit

func WithInit(fn func(*cli.Context) error) Option

WithInit sets the init function

func WithName

func WithName(n string) Option

WithName defines the name of the plugin

type Options

type Options struct {
	Name     string
	Flags    []cli.Flag
	Commands []*cli.Command
	Handlers []Handler
	Init     func(*cli.Context) error
}

Options are used as part of a new plugin

type Plugin

type Plugin interface {
	// Global Flags
	Flags() []cli.Flag
	// Sub-commands
	Commands() []*cli.Command
	// Handle is the middleware handler for HTTP requests. We pass in
	// the existing handler so it can be wrapped to create a call chain.
	Handler() Handler
	// Init called when command line args are parsed.
	// The initialized cli.Context is passed in.
	Init(*cli.Context) error
	// Name of the plugin
	String() string
}

Plugin is the interface for plugins to micro. It differs from go-micro in that it's for the micro API, Web, Sidecar, CLI. It's a method of building middleware for the HTTP side.

func NewPlugin

func NewPlugin(opts ...Option) Plugin

NewPlugin makes it easy to create a new plugin

func Plugins

func Plugins(opts ...PluginOption) []Plugin

Plugins lists the global plugins

type PluginOption

type PluginOption func(o *PluginOptions)

func Module

func Module(m string) PluginOption

Module will scope the plugin to a specific module, e.g. the "api"

type PluginOptions

type PluginOptions struct {
	Module string
}