grpc

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 Authenticator
  • func (a Authenticator) Authenticate(ctx context.Context) (newCtx context.Context, err error)
• type Config
  • func (cfg *Config) GetPort() int
• type Deps
• type Option
  • func UseAuth(a *Authenticator) Option
  • func UseConf(conf Config) Option
  • func UseDeps(cb func(*Deps)) Option
  • func UseHTTP(h rest.HTTPHandlers) Option
  • func UseTLS(c *tls.Config) 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
• type UserMetadata
  • func GetUserMetadata(ctx context.Context) (*UserMetadata, bool)

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 Authenticator

type Authenticator struct {
	Username string
	Password string
	Token    string
}

Authenticator exposes a function for authenticating requests.

func (Authenticator) Authenticate

func (a Authenticator) Authenticate(ctx context.Context) (newCtx context.Context, err error)

Authenticate checks that a token exists and is valid. It stores the user metadata in the returned context and removes the token from the context.

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"`

	// TLS info:
	InsecureTransport bool     `json:"insecure-transport"`
	Certfile          string   `json:"cert-file"`
	Keyfile           string   `json:"key-file"`
	CAfiles           []string `json:"ca-files"`

	// ExtendedLogging enables detailed GRPC logging
	ExtendedLogging bool `json:"extended-logging"`
}

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 UseAuth

func UseAuth(a *Authenticator) Option

UseAuth return Option that sets Authenticator.

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.

func UseTLS

func UseTLS(c *tls.Config) Option

UseTLS return Option that sets TLS config.

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

type UserMetadata

type UserMetadata struct {
	ID string
}

UserMetadata contains metadata about a user.

func GetUserMetadata

func GetUserMetadata(ctx context.Context) (*UserMetadata, bool)

GetUserMetadata can be used to extract user metadata stored in a context.