grpc

README

GRPC Plugin

The GRPC Plugin is a infrastructure Plugin which allows app plugins to handle GRPC requests (see the diagram below) in this sequence:

1. GRPC Plugin starts the GRPC server + net listener in its own goroutine
2. Plugins register their handlers with GRPC Plugin. To service GRPC requests, a plugin must first implement a handler function and register it at a given URL path using the RegisterService method. GRPC Plugin uses an GRPC request multiplexer from the grpc/Server.
3. GRPC server routes GRPC requests to their respective registered handlers using the grpc/Server.

Configuration

• the server's port can be defined using commandline flag grpc-port or via the environment variable GRPC_PORT.

Example

The [grpc-server greeter example]*(../../examples/grpc-plugin/grpc-server) demonstrates the usage of the GRPC Plugin plugin API GetServer():

// Register our GRPC request handler/service using generated RegisterGreeterServer:
RegisterGreeterServer(plugin.GRPC.Server(), &GreeterService{})

Once the handler is registered with GRPC Plugin and the agent is running, you can use grpc client to call the service (see example)

Documentation

Overview

Package grpc implements the GRPC netListener through which plugins can expose their services/API to the outside world.

Index

• func DeclareGRPCPortFlag(pluginName core.PluginName)
• func FixConfig(cfg *Config)
• func ListenAndServeGRPC(config Config, grpcServer *grpc.Server) (netListener net.Listener, err error)
• func PluginConfig(pluginCfg config.PluginConfig, cfg *Config, pluginName core.PluginName) error
• type Config
  • func DefaultConfig() *Config
  • func (cfg *Config) GetPort() int
• type Deps
• type ListenAndServe
• type Plugin
  • func FromExisting(server *grpc.Server) *Plugin
  • func FromExistingServer(listenAndServe ListenAndServe) *Plugin
  • func (plugin *Plugin) AfterInit() (err error)
  • func (plugin *Plugin) Close() error
  • func (plugin *Plugin) GetPort() int
  • func (plugin *Plugin) Init() (err error)
  • func (plugin *Plugin) Server() *grpc.Server
  • func (plugin *Plugin) String() string
• type Server

Functions

func DeclareGRPCPortFlag

func DeclareGRPCPortFlag(pluginName core.PluginName)

DeclareGRPCPortFlag declares GRPC port (with usage & default value) a flag for a particular plugin name

func FixConfig

func FixConfig(cfg *Config)

FixConfig fill default values for empty fields (does nothing yet)

func ListenAndServeGRPC

func ListenAndServeGRPC(config Config, grpcServer *grpc.Server) (netListener net.Listener, err error)

ListenAndServeGRPC starts a netListener.

func PluginConfig

func PluginConfig(pluginCfg config.PluginConfig, cfg *Config, pluginName core.PluginName) error

PluginConfig tries : - to load flag <plugin-name>-port and then FixConfig() just in case - alternatively <plugin-name>-config and then FixConfig() just in case - alternatively DefaultConfig()

Types

type Config

type Config struct {
	// Endpoint is an address of GRPC netListener
	Endpoint string

	// MaxMsgSize returns a ServerOption to set the max message size in bytes for inbound mesages.
	// If this is not set, gRPC uses the default 4MB.
	MaxMsgSize int

	// MaxConcurrentStreams returns a ServerOption that will apply a limit on the number
	// of concurrent streams to each ServerTransport.
	MaxConcurrentStreams uint32
}

Config is a configuration for GRPC netListener It is meant to be extended with security (TLS...)

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns new instance of config with default endpoint

func (*Config) GetPort

func (cfg *Config) GetPort() int

GetPort parses suffix from endpoint & returns integer after last ":" (otherwise it returns 0)

type Deps

type Deps struct {
	Log                 logging.PluginLogger //inject
	PluginName          core.PluginName      //inject
	config.PluginConfig                      //inject
	HTTP                rest.HTTPHandlers    //inject optional
}

Deps lists the dependencies of the Rest plugin.

type ListenAndServe

type ListenAndServe func(config Config, grpcServer *grpc.Server) (
	netListener io.Closer, err error)

ListenAndServe is a function that uses <config> & <handler> to handle GRPC Requests. It return an instance of io.Closer to close the Server (net listener) during cleanup.

type Plugin

type Plugin struct {
	Deps
	*Config
	// contains filtered or unexported fields
}

Plugin maintains the GRPC netListener (see Init, AfterInit, Close methods)

func FromExisting

func FromExisting(server *grpc.Server) *Plugin

FromExisting is a helper for preconfigured GRPC Server

func FromExistingServer

func FromExistingServer(listenAndServe ListenAndServe) *Plugin

FromExistingServer is used mainly for testing purposes

func (*Plugin) AfterInit

func (plugin *Plugin) AfterInit() (err error)

AfterInit starts the HTTP netListener.

func (*Plugin) Close

func (plugin *Plugin) Close() error

Close stops the HTTP netListener.

func (*Plugin) GetPort

func (plugin *Plugin) GetPort() int

GetPort returns plugin configuration port

func (*Plugin) Init

func (plugin *Plugin) Init() (err error)

Init is the plugin entry point called by Agent Core - It prepares GRPC netListener for registration of individual service

func (*Plugin) Server

func (plugin *Plugin) Server() *grpc.Server

Server is a getter for accessing grpc.Server (of a GRPC plugin)

Example usage:

protocgenerated.RegisterServiceXY(plugin.Deps.GRPC.Server(), &ServiceXYImplP{})

type Deps struct {
    GRPC grps.Server // inject plugin implementing RegisterHandler
    // other dependencies ...
}

func (*Plugin) String

func (plugin *Plugin) String() string

String returns plugin name (if not set defaults to "HTTP")

type Server

type Server interface {
	// Server is a getter for accessing grpc.Server (of a GRPC plugin)
	//
	// Example usage:
	//
	//   protocgenerated.RegisterServiceXY(plugin.Deps.GRPC.Server(), &ServiceXYImplP{})
	//
	//   type Deps struct {
	//       GRPC grps.Server // inject plugin implementing RegisterHandler
	//       // other dependencies ...
	//   }
	Server() *grpc.Server

	// GetPort returns configured port number (for debugging purposes)
	GetPort() int
}

Server defines the API for getting grpc.Server instance that is useful for registering new GRPC service