grpc

Documentation

Overview

Package grpc is the grpc transport for plugins/client/orb.

Package grpc provides a gRPC entrypoint for go-orb.

Index

• Constants
• func HTTPStatusToCode(code int) codes.Code
• func Listener(listener net.Listener) server.Option
• func New(serviceName string, serviceVersion string, epName string, acfg any, ...) (server.Entrypoint, error)
• func Provide(serviceName string, serviceVersion string, epName string, ...) (server.Entrypoint, error)
• func WithAddress(addr string) server.Option
• func WithGRPCOptions(opts ...grpc.ServerOption) server.Option
• func WithHandlers(h ...server.RegistrationFunc) server.Option
• func WithHealthService(health bool) server.Option
• func WithInsecure() server.Option
• func WithLogLevel(level string) server.Option
• func WithLogPlugin(plugin string) server.Option
• func WithNetwork(network string) server.Option
• func WithReflection(reflection bool) server.Option
• func WithTLS(config *tls.Config) server.Option
• func WithTimeout(timeout time.Duration) server.Option
• type Config
  • func NewConfig(options ...server.Option) *Config
• type Server
  • func (s *Server) AddHandler(handler server.RegistrationFunc)
  • func (s *Server) Address() string
  • func (s *Server) Config() *Config
  • func (s *Server) Enabled() bool
  • func (s *Server) Name() string
  • func (s *Server) Network() string
  • func (s *Server) Register(register server.RegistrationFunc)
  • func (s *Server) Start(ctx context.Context) error
  • func (s *Server) Stop(ctx context.Context) error
  • func (s *Server) String() string
  • func (s *Server) Transport() string
  • func (s *Server) Type() string

Constants

const (
	// DefaultNetwork is set to "tcp".
	DefaultNetwork = "tcp"

	// DefaultAddress to listen on. By default a random port will be selected.
	DefaultAddress = ":0"

	// DefaultInsecure is set to false to make sure the network traffic is entrypted.
	DefaultInsecure = false

	// DefaultgRPCReflection enables reflection by default.
	DefaultgRPCReflection = false

	// DefaultHealthService enables the health service by default.
	DefaultHealthService = false

	// DefaultTimeout is set to 5s.
	DefaultTimeout = time.Second * 5
)

const Plugin = "grpc"

Plugin name.

Functions

func HTTPStatusToCode

func HTTPStatusToCode(code int) codes.Code

HTTPStatusToCode maps HTTP status codes to gRPC codes.

Falls back to codes.Internal if the code is unrecognized.

func Listener

func Listener(listener net.Listener) server.Option

Listener sets a custom listener to pass to the server.

func New

func New(
	serviceName string,
	serviceVersion string,
	epName string,
	acfg any,
	logger log.Logger,
	reg registry.Type,
) (server.Entrypoint, error)

New creates a gRPC server by options.

func Provide

func Provide(
	serviceName string,
	serviceVersion string,
	epName string,
	configData map[string]any,
	logger log.Logger,
	reg registry.Type,
	opts ...server.Option,
) (server.Entrypoint, error)

Provide provides a gRPC server by config.

func WithAddress

func WithAddress(addr string) server.Option

WithAddress sets the address to listen on.

If no IP is provided, an interface will be selected automatically. Private interfaces are preferred, if none are found a public interface will be used. To listen on all interfaces explicitly set '0.0.0.0:<port>'.

If no port is provided, a random port will be selected. To listen on a specific interface, but with a random port, you can use '<IP>:0'.

func WithGRPCOptions

func WithGRPCOptions(opts ...grpc.ServerOption) server.Option

WithGRPCOptions with grpc options.

func WithHandlers

func WithHandlers(h ...server.RegistrationFunc) server.Option

WithHandlers adds custom handlers.

func WithHealthService

func WithHealthService(health bool) server.Option

WithHealthService dictates whether the gRPC health check protocol should be implemented. This is an implementation provided by the grpc package. Defaults to false.

This is useful for healthprobes, such as in Kubernetes (>=1.24).

func WithInsecure

func WithInsecure() server.Option

WithInsecure will create the entrypoint without using TLS.

WARNING: don't use this in production, unless you really know what you are doing. this will result in unencrypted traffic. Really, it is even advised against using this in testing environments.

func WithLogLevel

func WithLogLevel(level string) server.Option

WithLogLevel changes the log level from the inherited logger.

func WithLogPlugin

func WithLogPlugin(plugin string) server.Option

WithLogPlugin changes the log level from the inherited logger.

func WithNetwork

func WithNetwork(network string) server.Option

WithNetwork specifies the network to listen on.

func WithReflection

func WithReflection(reflection bool) server.Option

WithReflection dictates whether the server should implementent gRPC reflection. This is used by e.g. the gRPC proxy. Defaults to false.

func WithTLS

func WithTLS(config *tls.Config) server.Option

WithTLS sets the TLS config.

func WithTimeout

func WithTimeout(timeout time.Duration) server.Option

WithTimeout sets the request context timeout for requests.

The handler still needs to respect the context timeout for this to have any effect.

Types

type Config

type Config struct {
	server.EntrypointConfig `yaml:",inline"`

	// Network to listen on.
	//
	// Defaults to "tcp".
	Network string `json:"network" yaml:"network"`

	// Address to listen on.
	//
	// If no IP is provided, an interface will be selected automatically. Private
	// interfaces are preferred, if none are found a public interface will be used.
	//
	// If no port is provided, a random port will be selected. To listen on a
	// specific interface, but with a random port, you can use '<IP>:0'.
	Address string `json:"address" yaml:"address"`

	// Insecure will start the gRPC server without TLS.
	// If set to false, and no TLS certifiate is provided, a self-signed
	// certificate will be generated.
	//
	// WARNING: don't use this in production, unless you really know what you are
	// doing. this will result in unencrypted traffic. Really, it is even advised
	// against using this in testing environments.
	Insecure bool `json:"insecure,omitempty" yaml:"insecure,omitempty"`

	// TLS config, if none is provided a self-signed certificates will be generated.
	//
	// You can load a tls config from yaml/json with the following options:
	//
	// “`yaml
	// rootCAFiles:
	//    - xxx
	// clientCAFiles:
	//    - xxx
	// clientAuth: "none" | "request" | "require" |  "verify" | "require+verify"
	// certificates:
	//   - certFile: xxx
	//     keyFile: xxx
	// “`
	TLS *mtls.Config `json:"tls,omitempty" yaml:"tls,omitempty"`

	// GRPCOptions are options provided by the grpc package, and will be directly
	// passed ot the gRPC server.
	GRPCOptions []grpc.ServerOption `json:"-" yaml:"-"`

	// HealthService dictates whether the gRPC health check protocol should be
	// implemented. This is an implementation provided by the grpc package.
	// Defaults to true.
	//
	// This is useful for healthprobes, such as in Kubernetes (>=1.24).
	HealthService bool `json:"health" yaml:"health"`

	// Reflection dictates whether the server should implementent gRPC
	// reflection. This is used by e.g. the gRPC proxy. Defaults to true.
	Reflection bool `json:"reflection" yaml:"reflection"`

	// Timeout adds a timeout to the request context on the request handler.
	//
	// The handler still needs to respect the context timeout for this to have
	// any effect.
	Timeout config.Duration `json:"timeout" yaml:"timeout"`

	// Listener is a custom listener. If none provided one will be created with
	// the address and TLS config.
	Listener net.Listener `json:"-" yaml:"-"`

	// Logger allows you to dynamically change the log level and plugin for a
	// specific entrypoint.
	Logger log.Config `json:"logger" yaml:"logger"`
}

Config provides options to the gRPC entrypoint.

func NewConfig

func NewConfig(options ...server.Option) *Config

NewConfig will create a new default config for the entrypoint.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is an entrypoint with a gRPC server.

func (*Server) AddHandler

func (s *Server) AddHandler(handler server.RegistrationFunc)

AddHandler adds a handler for later registration.

func (*Server) Address

func (s *Server) Address() string

Address returns the address the entypoint listens on, for example: 127.0.0.1:8000 .

func (*Server) Config

func (s *Server) Config() *Config

Config returns the server config.

func (*Server) Enabled

func (s *Server) Enabled() bool

Enabled returns if this entrypoint has been enbaled in config.

func (*Server) Name

func (s *Server) Name() string

Name returns the entrypoint name.

func (*Server) Network

func (s *Server) Network() string

Network returns the network the entrypoint listens on.

func (*Server) Register

func (s *Server) Register(register server.RegistrationFunc)

Register executes a registration function on the entrypoint.

func (*Server) Start

func (s *Server) Start(ctx context.Context) error

Start start the gRPC server.

func (*Server) Stop

func (s *Server) Stop(ctx context.Context) error

Stop stop the gRPC server.

func (*Server) String

func (s *Server) String() string

String returns the entrypoint type; http.

func (*Server) Transport

func (s *Server) Transport() string

Transport returns the client transport to use.

func (*Server) Type

func (s *Server) Type() string

Type returns the component type.