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 ListenAndServeGRPC(config *Config, grpcServer *grpc.Server) (netListener net.Listener, err error)
• type Config
  • func (cfg *Config) GetPort() int
• type Deps
• type ListenAndServe
• type Plugin
  • func FromExistingServer(listenAndServe ListenAndServe) *Plugin
  • func (plugin *Plugin) AfterInit() (err error)
  • func (plugin *Plugin) Close() error
  • func (plugin *Plugin) GetServer() *grpc.Server
  • func (plugin *Plugin) Init() error
  • func (plugin *Plugin) IsDisabled() (disabled bool)
  • 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 ListenAndServeGRPC

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

ListenAndServeGRPC starts a netListener.

Types

type Config

type Config struct {
	// Endpoint is an address of GRPC netListener
	Endpoint string `json:"endpoint"`

	// Three or four-digit permission setup for unix domain socket file (if used)
	Permission int `json:"permission"`

	// If set and unix type network is used, the existing socket file will be always removed and re-created
	ForceSocketRemoval bool `json:"force-socket-removal"`

	// Network defaults to "tcp" if unset, and can be set to one of the following values:
	// "tcp", "tcp4", "tcp6", "unix", "unixpacket" or any other value accepted by net.Listen
	Network string `json:"network"`

	// 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 `json:"max-msg-size"`

	// MaxConcurrentStreams returns a ServerOption that will apply a limit on the number
	// of concurrent streams to each ServerTransport.
	MaxConcurrentStreams uint32 `json:"max-concurrent-streams"`
}

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

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
	PluginName core.PluginName
	HTTP       rest.HTTPHandlers
	config.PluginConfig
}

Deps is a list of injected dependencies of the GRPC 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
	// Stored GRPC config (used in example)
	*Config
	// contains filtered or unexported fields
}

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

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

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

GetServer is a getter for accessing grpc.Server

func (*Plugin) Init

func (plugin *Plugin) Init() error

Init prepares GRPC netListener for registration of individual service

func (*Plugin) IsDisabled

func (plugin *Plugin) IsDisabled() (disabled bool)

IsDisabled returns *true* if the plugin is not in use due to missing grpc configuration.

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 ...
	//   }
	GetServer() *grpc.Server

	// Disabled informs other plugins about availability
	IsDisabled() bool
}

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