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

• Variables
• func DeclareGRPCPortFlag(pluginName infra.PluginName)
• func ListenAndServe(cfg *Config, srv *grpc.Server) (netListener net.Listener, err error)
• type Config
  • func (cfg *Config) GetPort() int
• type Deps
• type Option
  • func UseConf(conf Config) Option
  • func UseDeps(cb func(*Deps)) Option
  • func UseHTTP(h rest.HTTPHandlers) Option
• type Plugin
  • func NewPlugin(opts ...Option) *Plugin
  • func (p *Plugin) AfterInit() (err error)
  • func (p *Plugin) Close() error
  • func (p *Plugin) GetServer() *grpc.Server
  • func (p *Plugin) Init() (err error)
  • func (p *Plugin) IsDisabled() bool
• type Server

Variables

var DefaultPlugin = *NewPlugin()

DefaultPlugin is a default instance of Plugin.

Functions

func DeclareGRPCPortFlag

func DeclareGRPCPortFlag(pluginName infra.PluginName)

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

func ListenAndServe

func ListenAndServe(cfg *Config, srv *grpc.Server) (netListener net.Listener, err error)

ListenAndServe starts configured listener and serving for clients

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 {
	infra.PluginDeps
	HTTP rest.HTTPHandlers
}

Deps is a list of injected dependencies of the GRPC plugin.

type Option

type Option func(*Plugin)

Option is a function that can be used in NewPlugin to customize Plugin.

func UseConf

func UseConf(conf Config) Option

UseConf returns Option which injects a particular configuration.

func UseDeps

func UseDeps(cb func(*Deps)) Option

UseDeps returns Option that can inject custom dependencies.

func UseHTTP

func UseHTTP(h rest.HTTPHandlers) Option

UseHTTP returns Option that sets HTTP handlers.

type Plugin

type Plugin struct {
	Deps

	*Config
	// contains filtered or unexported fields
}

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

func NewPlugin

func NewPlugin(opts ...Option) *Plugin

NewPlugin creates a new Plugin with the provided Options.

func (*Plugin) AfterInit

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

AfterInit starts the HTTP netListener.

func (*Plugin) Close

func (p *Plugin) Close() error

Close stops the HTTP netListener.

func (*Plugin) GetServer

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

GetServer is a getter for accessing grpc.Server

func (*Plugin) Init

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

Init prepares GRPC netListener for registration of individual service

func (*Plugin) IsDisabled

func (p *Plugin) IsDisabled() bool

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

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