rpc

package
v0.0.0-...-5783bb9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 27, 2024 License: BSD-3-Clause Imports: 41 Imported by: 4

README

gRPC Utilities

RPC stands for Remote Procedure Call, and it's an architecture style for distributed systems in which a system causes a procedure (subroutine) to execute in a different address space (commonly on another computer on a network). This package use gRPC as its underlying high-performance framework.

Deploying a gRPC service in production involves several aspects and considerations. Things like: logging, authentication, secure communication channels, request tracing, manage server resources, support regular HTTP (REST) access, etc. This package greatly simplifies the process of properly configuring and running a production grade RPC service.

More information: https://grpc.io/

Server

For the server implementation the main component is using a Server instance. The server is configured, using functional style parameters, by providing a list of options to the NewServer and/or Setup methods.

For example, let's create and start a server using some common configuration options.

// Server configuration options.
settings := []ServerOption{
WithLogger(nil),
WithPanicRecovery(),
WithServiceProvider(yourServiceHandler),
WithResourceLimits(ResourceLimits{
  Connections: 100,
  Requests:    100,
  Rate:        1000,
}),
}

// Create new server.
server, _ := NewServer(settings...)

// Start the server instance and wait for it to be ready.
ready := make(chan bool)
go server.Start(ready)
<-ready

// Server is ready now

Services

The most important configuration setting for a server instance are the "Services" it supports. You can provide services by implementing the ServiceProvider interface in your application and passing it along using the WithServiceProvider option.

// Echo service provider (i.e., implementing the "ServiceProvider" interface.)
type echoProvider struct{}

func (ep *echoProvider) ServerSetup(server*grpc.Server) {
  sampleV1.RegisterEchoAPIServer(server, &sampleV1.EchoHandler{})
}

func (ep *echoProvider) GatewaySetup() GatewayRegister {
  return sampleV1.RegisterEchoAPIHandler
}

// Base server configuration options
serverOpts := []ServerOption{
  WithPanicRecovery(),
  WithServiceProvider(&echoProvider{}),
}

Client

In order to interact with an RPC server and access the provided functionality you need to set up and establish a client connection. A client connection should be closed when no longer needed to free the used resources. A connection can also be monitored to detect any changes in its current state.

A connection could be obtained from a client instance. The benefit of this approach is that a single client instance can be used to generate multiple connections to different servers.

// client options
options := []ClientOption{
  WaitForReady(),
  WithTimeout(5 * time.Second),
}
client, err := NewClient(options...)
if err != nil {
  panic(err)
}

// Use client to get a connection
conn, err := client.GetConnection("server.com:9090")
if err != nil {
  panic(err)
}

// Use connection

// Close it when not needed any more
defer conn.Close()

For simpler use cases a connection can be directly obtained using the NewClientConnection method.

// client options
options := []ClientOption{
  WaitForReady(),
  WithTimeout(1 * time.Second),
}

// Get connection
conn, err := NewClientConnection("server.com:9090", options...)
if err != nil {
  panic(err)
}

// Use connection

// Close it when not needed any more
defer conn.Close()

Regardless of how a connection is created, you can set up a monitor for it using the MonitorClientConnection method. The monitor instance can be properly terminated using the provided context.

// Get a monitor instance with a 5 seconds check interval
ctx, close := context.WithCancel(context.Background())
defer close()
monitor := MonitorClientConnection(ctx, conn, 5*time.Second)

// Close the monitor in the background after 15 seconds
go func() {
  <-time.After(15*time.Second)
  close()
}

// Catch changes in the connection state
for state := range monitor {
  fmt.Printf("connection state: %s", state)
}

For more information about functional style configuration options check the original article by Dave Cheney: https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis.

Documentation

Overview

Package rpc provides a utilities and components to easily deploy a robust RPC network service.

RPC stands for Remote Procedure Call, and it's an architecture style for distributed systems in which a system causes a procedure (subroutine) to execute in a different address space (commonly on another computer on a network). This package use gRPC as its underlying high-performance framework.

Deploying a gRPC service in production involves several aspects and considerations. Things like: logging, authentication, secure communication channels, request tracing, manage server resources, support regular HTTP (REST) access, etc. This package greatly simplifies the process of properly configuring and running a production grade RPC service.

More information: https://grpc.io/

Server

For the server implementation the main component is using a 'Server' instance. The server is configured, using functional style parameters, by providing a list of options to the 'NewServer' and/or 'Setup' methods.

For example, let's create and start a server using some common configuration options. 

// Server configuration options.
settings := []ServerOption{
	WithLogger(nil),
	WithPanicRecovery(),
	WithServiceProvider(yourServiceHandler),
	WithResourceLimits(ResourceLimits{
		Connections: 100,
		Requests:    100,
		Rate:        1000,
	}),
}

// Create new server.
server, _ := NewServer(settings...)

// Start the server instance and wait for it to be ready.
ready := make(chan bool)
go server.Start(ready)
<-ready

// Server is ready now

Services

The most important configuration setting for a server instance are the "Services" it supports. You can provide services by implementing the "ServiceProvider" interface in your application and passing it along using the "WithServiceProvider" option. 

// Echo service provider (i.e., implementing the "ServiceProvider" interface.)
type echoProvider struct{}

func (ep *echoProvider) ServerSetup(server *grpc.Server) {
	samplev1.RegisterEchoAPIServer(server, &samplev1.EchoHandler{})
}

func (ep *echoProvider) GatewaySetup() GatewayRegister {
	return samplev1.RegisterEchoAPIHandler
}

// Base server configuration options
serverOpts := []ServerOption{
	WithPanicRecovery(),
	WithServiceProvider(&echoProvider{}),
}

Client

In order to interact with an RPC server and access the provided functionality you need to set up and establish a client connection. A client connection should be closed when no longer needed to free the used resources. A connection can also be monitored to detect any changes in its current state.

A connection could be obtained from a client instance. The benefit of this approach is that a single client instance can be used to generate multiple connections to different servers. 

// client options
options := []ClientOption{
	WaitForReady(),
	WithTimeout(1 * time.Second),
}
client, err := NewClient(options...)
if err != nil {
	panic(err)
}

// Use client to get a connection
conn, err := client.GetConnection("server.com:9090")
if err != nil {
	panic(err)
}
defer conn.Close()

For simpler use cases a connection can be directly obtained using the 'NewClientConnection' method. 

// client options
options := []ClientOption{
	WaitForReady(),
	WithTimeout(1 * time.Second),
}

// Get connection
conn, err := NewClientConnection("server.com:9090", options...)
if err != nil {
	panic(err)
}

// Use connection

// Close it when not needed any more
defer conn.Close()

Regardless of how a connection is created you can set up a monitor for it using the 'MonitorClientConnection' method. The monitor instance can be properly terminated using the provided context. 

// Get a monitor instance with a 5 seconds check interval
ctx, close := context.WithCancel(context.Background())
defer close()
monitor := MonitorClientConnection(ctx, conn, 5*time.Second)

// Close the monitor in the background after 15 seconds
go func() {
	<-time.After(15*time.Second)
	close()
}

// Catch changes in the connection state
for state := range monitor {
	fmt.Printf("connection state: %s", state)
}

For more information about functional style configuration options check the original article by Dave Cheney: https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis.

Index

Examples

Constants

View Source 
const NetworkInterfaceAll = "all"

NetworkInterfaceAll will set up a network listener on all available `unicast` and `anycast` IP addresses of the local system.

View Source 
const NetworkInterfaceLocal = "local"

NetworkInterfaceLocal defines the local loopback interface (i.e., localhost / 127.0.0.1).

Variables

View Source 
var RecommendedCiphers = []uint16{
	tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
	tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
	tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
	tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
	tls.TLS_RSA_WITH_AES_128_GCM_SHA256,
	tls.TLS_RSA_WITH_AES_256_GCM_SHA384,
}

RecommendedCiphers provides a default list of secure/modern ciphers.

View Source 
var RecommendedCurves = []tls.CurveID{
	tls.CurveP521,
	tls.CurveP384,
	tls.CurveP256,
}

RecommendedCurves provides a sane list of curves with assembly implementations for performance and constant time to protect against side-channel attacks.

Functions

func ContextWithMetadata 

func ContextWithMetadata(ctx context.Context, md metadata.MD) context.Context

ContextWithMetadata returns a context with the provided value set as metadata. Any existing metadata already present in the context will be preserved. Intended to be used for outgoing RPC calls.

Example

Create a context instance with custom metadata. 

data := make(map[string]string)
data["foo"] = "your-value"
ctx := ContextWithMetadata(context.Background(), metadata.New(data))

// Access the metadata in the context instance
md, _ := metadata.FromOutgoingContext(ctx)
fmt.Printf("foo: %s", md.Get("foo")[0])

Output:

func GetAddress 

func GetAddress(networkInterface string) (string, error)

GetAddress returns the IPv4 address for the specified network interface.

func GetAuthToken 

func GetAuthToken(ctx context.Context, scheme string) (string, error)

GetAuthToken is helper function for extracting the "authorization" header from the gRPC metadata of the request. It expects the "authorization" header to be of a certain scheme (e.g. `basic`, `bearer`), in a case-insensitive format (see rfc2617, sec 1.2). If no such authorization is found, or the token is of wrong scheme, an error with gRPC status `Unauthenticated` is returned.

func GetInterfaceIP 

func GetInterfaceIP(name string) (net.IP, error)

GetInterfaceIP returns the IP address for a given network interface.

func LoadCertificate 

func LoadCertificate(cert []byte, key []byte) (tls.Certificate, error)

LoadCertificate provides a helper method to conveniently parse and existing certificate and corresponding private key.

func MetadataFromContext 

func MetadataFromContext(ctx context.Context) metadata.MD

MetadataFromContext extracts and return the metadata values available in the provided context.

func MonitorClientConnection 

func MonitorClientConnection(ctx context.Context, conn *grpc.ClientConn, ti time.Duration) <-chan connectivity.State

MonitorClientConnection enable notifications on connection state change. If no interval `ti` is provided (i.e. 0) a default value of 2 seconds will be used.

func NewClientConnection 

func NewClientConnection(endpoint string, options ...ClientOption) (*grpc.ClientConn, error)

NewClientConnection creates a new RPC connection with the provided options.

Example

Get a connection without a client instance. 

// client options
options := []ClientOption{WithTimeout(1 * time.Second)}

// Get connection
conn, err := NewClientConnection("server.com:9090", options...)
if err != nil {
	panic(err)
}

// Use connection

// Close it when not needed anymore
defer func() {
	_ = conn.Close()
}()

Output:

func Retry 

func Retry(config *RetryOptions) []grpc.CallOption

Retry specific failed RPC operations automatically.

Types

type Client 

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

Client provides an RPC client wrapper with several utilities.

func NewClient 

func NewClient(options ...ClientOption) (*Client, error)

NewClient set up a new client instance.

Example

Use a client instance to generate a connection. 

// client options
options := []ClientOption{WithTimeout(1 * time.Second)}
client, err := NewClient(options...)
if err != nil {
	panic(err)
}

// Use client to get a connection
conn, err := client.GetConnection("server.com:9090")
if err != nil {
	panic(err)
}

// Use connection

// Close it when not needed anymore
defer func() {
	_ = conn.Close()
}()

Output:

func (*Client) GetConnection 

func (c *Client) GetConnection(endpoint string) (conn *grpc.ClientConn, err error)

GetConnection returns a RPC client connection for the client instance.

type ClientOption 

type ClientOption func(*Client) error

ClientOption allows adjusting client settings following a functional pattern.

func WithAuthCertificate 

func WithAuthCertificate(cert, key []byte) ClientOption

WithAuthCertificate enabled certificate-based client authentication with the provided credentials.

func WithAuthToken 

func WithAuthToken(token string) ClientOption

WithAuthToken use the provided token string as bearer authentication credential.

func WithClientTLS 

func WithClientTLS(opts ClientTLSConfig) ClientOption

WithClientTLS set parameters to establish a secure connection channel with the server.

func WithCompression 

func WithCompression() ClientOption

WithCompression will enable standard GZIP compression on all client requests.

func WithDialOptions 

func WithDialOptions(opts ...grpc.DialOption) ClientOption

WithDialOptions will set additional gRPC dial options to be used by the client instance.

func WithInsecureSkipVerify 

func WithInsecureSkipVerify() ClientOption

WithInsecureSkipVerify controls whether a client verifies the server's certificate chain and host name. If set to `true`, TLS accepts any certificate presented by the server and any host name in that certificate. In this mode, connections are susceptible to MITM attacks. This should be used only for testing.

func WithKeepalive 

func WithKeepalive(t int) ClientOption

WithKeepalive will configure the client to send a ping message when a certain time (in seconds) has passed without activity in the connection. The minimum valid interval is 10 seconds.

func WithLoadBalancer 

func WithLoadBalancer() ClientOption

WithLoadBalancer configures the client connection to enable load balancing, by default the "round-robin" strategy is used to choose a backend for RPC requests. When enabling this option the provided endpoint is expected to be a DNS record that returns a set of reachable IP addresses. When deploying with Kubernetes this is done by using a Headless Service.

func WithRetry 

func WithRetry(config *RetryOptions) ClientOption

WithRetry will enable automatic error retries on all client requests.

func WithServerNameOverride 

func WithServerNameOverride(name string) ClientOption

WithServerNameOverride adjust the identifier expected to be present on the upstream RPC server's certificate, when using TLS. This option is meant for testing only. If set to a non-empty string, it will override the virtual host name of authority (e.g. :authority header field) in requests.

func WithTimeout 

func WithTimeout(timeout time.Duration) ClientOption

WithTimeout establish a time limit when dialing a connection with the server.

func WithUserAgent 

func WithUserAgent(val string) ClientOption

WithUserAgent sets the "user-agent" value use by the client instance.

type ClientTLSConfig 

type ClientTLSConfig struct {
	// Whether to include system CAs.
	IncludeSystemCAs bool

	// Custom certificate authorities to include when accepting TLS connections.
	CustomCAs [][]byte
}

ClientTLSConfig defines the configuration options available when establishing a secure communication channel with a server.

type Gateway 

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

Gateway permits to consume an HTTP2 RPC-based service through a flexible HTTP1.1 REST interface.

func NewGateway 

func NewGateway(options ...GatewayOption) (*Gateway, error)

NewGateway setups an HTTP interface for an RPC server.

type GatewayInterceptor 

type GatewayInterceptor func(http.ResponseWriter, *http.Request) error

GatewayInterceptor allows to further customize the processing of requests. If an interceptor function returns a non-nil error, any further processing of the request will be skipped.

type GatewayOption 

type GatewayOption func(*Gateway) error

GatewayOption allows adjusting gateway settings following a functional pattern.

func WithClientOptions 

func WithClientOptions(options ...ClientOption) GatewayOption

WithClientOptions configuration options for the gateway's internal client connection to the upstream RPC server.

func WithCustomHandlerFunc 

func WithCustomHandlerFunc(method string, path string, hf http.HandlerFunc) GatewayOption

WithCustomHandlerFunc add a new handler function for a path on the gateway's internal mux.

func WithEncoder 

func WithEncoder(mime string, marshaller gwRuntime.Marshaler) GatewayOption

WithEncoder registers a marshaller instance for a specific mime type.

func WithGatewayMiddleware 

func WithGatewayMiddleware(md func(http.Handler) http.Handler) GatewayOption

WithGatewayMiddleware allows extending and adjusting the behavior of the HTTP gateway with standard middleware providers.

func WithGatewayPort 

func WithGatewayPort(port int) GatewayOption

WithGatewayPort adjust the gateway to handle requests on a different port. If not set the gateway will use the same port as the RPC server by default. If a custom and different port is provided, the gateway will manage its own network interface. If the RPC endpoint is a UNIX socket and no port is provided for the gateway, a free port number will be randomly assigned.

func WithHandlerName 

func WithHandlerName(name string) GatewayOption

WithHandlerName will adjust the OpenTelemetry name used to report spans generated by the HTTP gateway instance. If not provided the default name `grpc-gateway` will be used.

func WithInterceptor 

func WithInterceptor(f ...GatewayInterceptor) GatewayOption

WithInterceptor allows to customize the processing of requests. Interceptors are executed BEFORE the standard processing operations and could impact performance or prevent standard processing handled by the gateway instance. Should be used with care. If an interceptor returns a non-nil error, any further processing of the request will be skipped.

func WithPrettyJSON 

func WithPrettyJSON(mime string) GatewayOption

WithPrettyJSON provides a convenient mechanism to enable pretty printed JSON responses for requests with a specific content-type header. A usual value to use is `application/json+pretty`.

func WithResponseMutator 

func WithResponseMutator(rm GatewayResponseMutator) GatewayOption

WithResponseMutator allows the user to completely control/adjust the response returned by the gateway. Some common uses cases include:

  • Return a subset of response fields as HTTP response headers
  • Set an application-specific token in a header
  • Mutate the response messages to be returned

func WithSpanFormatter 

func WithSpanFormatter(sf otelHttp.SpanNameFormatter) GatewayOption

WithSpanFormatter allows to adjust how a given transaction is reported on the server side when observability is enabled.

func WithUnaryErrorHandler 

func WithUnaryErrorHandler(eh GatewayUnaryErrorHandler) GatewayOption

WithUnaryErrorHandler allows the user to completely control/adjust all unary error responses returned by the gateway.

type GatewayRegisterFunc 

type GatewayRegisterFunc = func(context.Context, *runtime.ServeMux, *grpc.ClientConn) error

GatewayRegisterFunc provides a mechanism to set up an HTTP mux for a gRPC server.

type GatewayResponseMutator 

type GatewayResponseMutator func(context.Context, http.ResponseWriter, proto.Message) error

GatewayResponseMutator allows the user to completely control/adjust the response returned by the gateway. Some common uses cases include:

  • Return a subset of response fields as HTTP response headers
  • Set an application-specific token in a header
  • Mutate the response messages to be returned

type GatewayUnaryErrorHandler 

type GatewayUnaryErrorHandler func(
	context.Context,
	*gwRuntime.ServeMux,
	gwRuntime.Marshaler,
	http.ResponseWriter,
	*http.Request,
	error)

GatewayUnaryErrorHandler allows the user to completely control/adjust all unary error responses returned by the gateway.

type HTTPServiceProvider 

type HTTPServiceProvider interface {
	ServiceProvider

	// GatewaySetup return the HTTP Gateway setup method.
	GatewaySetup() GatewayRegisterFunc
}

HTTPServiceProvider is an entity that provides functionality to be exposed through an RPC server and an HTTP gateway.

type HealthCheck 

type HealthCheck func(ctx context.Context, service string) error

HealthCheck is a function that can be used to report whether a service is able to handle incoming client requests or not. If an error is returned the service will be marked as unavailable and respond with a status code of `NOT_SERVING`.

type ResourceLimits 

type ResourceLimits struct {
	// Maximum number of simultaneous RPC connections (clients).
	Connections uint32 `json:"connections" yaml:"connections" mapstructure:"connections"`

	// Maximum number of simultaneous RPC calls per-client.
	Requests uint32 `json:"requests" yaml:"requests" mapstructure:"requests"`

	// Maximum number of RPC calls per-second (total).
	Rate uint32 `json:"rate" yaml:"rate" mapstructure:"rate"`
}

ResourceLimits allows setting constrains for the RPC server.

type RetryOptions 

type RetryOptions struct {
	// Max number of tries for the call before returning an error
	Attempts uint

	// Sets the RPC timeout per call (including initial call)
	PerRetryTimeout *time.Duration

	// Produces increasing intervals for each attempt
	BackoffExponential *time.Duration
}

RetryOptions define the required parameters to execute an RPC call with a retry strategy.

type Server 

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

Server provides an easy-to-setup RPC server handler with several utilities.

func NewServer 

func NewServer(options ...ServerOption) (*Server, error)

NewServer is a constructor method that returns a ready-to-use new server instance.

Example

Start a sample server instance. 

// Server configuration options
settings := []ServerOption{
	WithPanicRecovery(),
	WithResourceLimits(ResourceLimits{
		Connections: 100,
		Requests:    100,
		Rate:        1000,
	}),
}

// Create new server
server, _ := NewServer(settings...)

// Start the server instance and wait for it to be ready
ready := make(chan bool)
go func() {
	if err := server.Start(ready); err != nil {
		panic(err)
	}
}()
<-ready

// Server is ready now

Output:

func (*Server) Endpoint 

func (srv *Server) Endpoint() string

Endpoint returns the server's main entry point.

func (*Server) Start 

func (srv *Server) Start(ready chan<- bool) (err error)

Start the server and wait for incoming requests. You can provide an optional notification handler to catch an event when the server is ready for use. If a handler is provided but poorly managed, the start process will continue after a timeout of 20 milliseconds to prevent blocking the process indefinitely.

func (*Server) Stop 

func (srv *Server) Stop(graceful bool) error

Stop will terminate the server processing. When graceful is true, the server stops accepting new connections and requests and blocks until all the pending RPCs are finished. Otherwise, it cancels all active RPCs on the server side and the corresponding pending RPCs on the client side will get notified by connection errors.

type ServerOption 

type ServerOption func(*Server) error

ServerOption allows adjusting server settings following a functional pattern.

func WithAuthByCertificate 

func WithAuthByCertificate(clientCA []byte) ServerOption

WithAuthByCertificate enables certificate-based authentication on the server. It can be used multiple times to allow for several certificate authorities. This option is only applicable when operating the server through a TLS channel, otherwise will simply be ignored.

func WithAuthByToken 

func WithAuthByToken(tv TokenValidator) ServerOption

WithAuthByToken allows to use an external authentication mechanism for the server using bearer tokens as credentials. Setting this option will enable automatic authentication for all methods enabled on the server. When a server requires to support both authenticated and unauthenticated methods, the verification process can be performed manually per-method. 

token, err := GetAuthToken(ctx, "bearer")
... validate token ...

func WithHTTPGateway 

func WithHTTPGateway(gw *Gateway) ServerOption

WithHTTPGateway registers a gateway interface to allow for HTTP access to the server.

func WithHTTPGatewayOptions 

func WithHTTPGatewayOptions(opts ...GatewayOption) ServerOption

WithHTTPGatewayOptions adjust the behavior of the HTTP gateway.

func WithHealthCheck 

func WithHealthCheck(check HealthCheck) ServerOption

WithHealthCheck enables the server to provide health check information to clients. If an error is returned by the provided health check function the service will be marked as unavailable and respond with a status code of `NOT_SERVING`.

More information about the health check protocol: 

https://github.com/grpc/grpc/blob/master/doc/health-checking.md

func WithInputValidation 

func WithInputValidation() ServerOption

WithInputValidation will automatically detect any errors on received messages by detecting if a `Validate` method is available and returning any produced errors with an `InvalidArgument` status code.

To further automate input validation use: 

https://github.com/envoyproxy/protoc-gen-validate

func WithNetworkInterface 

func WithNetworkInterface(name string) ServerOption

WithNetworkInterface specifies which network interface to use to listen for incoming requests.

func WithPanicRecovery 

func WithPanicRecovery() ServerOption

WithPanicRecovery allows the server to convert panic events into a gRPC error with status 'Internal'.

func WithPort 

func WithPort(port int) ServerOption

WithPort specifies which TCP port the server use.

func WithPrometheus 

func WithPrometheus(prometheus otelProm.Operator) ServerOption

WithPrometheus allows generating and consuming metrics from the server instance using the Prometheus standards and tooling.

func WithProtoValidate 

func WithProtoValidate() ServerOption

WithProtoValidate enables automatic input validation using the `protovalidate` package. Any validation errors will be returned with status code `InvalidArgument`. https://github.com/bufbuild/protovalidate

func WithReflection 

func WithReflection() ServerOption

WithReflection enables the server to provide information about publicly-accessible services and assists clients at runtime to construct RPC requests and responses without precompiled service information. It is used by gRPC CLI, which can be used to introspect server protos and send/receive test RPCs.

More information about the reflection protocol: 

https://github.com/grpc/grpc/blob/master/doc/server-reflection.md

More information about the gRPC CLI tool: 

https://github.com/grpc/grpc/blob/master/doc/command_line_tool.md

func WithResourceLimits 

func WithResourceLimits(limits ResourceLimits) ServerOption

WithResourceLimits applies constraints to the resources the server instance can consume.

func WithServiceProvider 

func WithServiceProvider(sp ServiceProvider) ServerOption

WithServiceProvider adds an RPC service handler to the server instance, at least one service provider is required when starting the server.

func WithStreamMiddleware 

func WithStreamMiddleware(entry ...grpc.StreamServerInterceptor) ServerOption

WithStreamMiddleware allows including custom middleware functions when processing stream RPC operations. Order is important when chaining multiple middleware.

func WithTLS 

func WithTLS(opts ServerTLSConfig) ServerOption

WithTLS enables the server to use secure communication channels with the provided credentials and settings. If a certificate is provided the server name MUST match the identifier included in the certificate.

func WithUnaryMiddleware 

func WithUnaryMiddleware(entry ...grpc.UnaryServerInterceptor) ServerOption

WithUnaryMiddleware allows including custom middleware functions when processing incoming unary RPC requests. Order is important when chaining multiple middleware.

func WithUnixSocket 

func WithUnixSocket(socket string) ServerOption

WithUnixSocket specifies the server should use a UNIX socket as main access point.

func WithWebSocketProxy 

func WithWebSocketProxy(opts ...ws.ProxyOption) ServerOption

WithWebSocketProxy configure the server to support bidirectional streaming over HTTP utilizing web sockets.

type ServerTLSConfig 

type ServerTLSConfig struct {
	// Server certificate, PEM-encoded.
	Cert []byte

	// Server private key, PEM-encoded.
	PrivateKey []byte

	// List of ciphers to allow.
	SupportedCiphers []uint16

	// Server preferred curves configuration.
	PreferredCurves []tls.CurveID

	// Whether to include system CAs.
	IncludeSystemCAs bool

	// Custom certificate authorities to include when accepting TLS connections.
	CustomCAs [][]byte
}

ServerTLSConfig provides available settings to enable secure TLS communications.

type ServiceProvider 

type ServiceProvider interface {
	// ServerSetup should perform any initialization requirements for the
	// particular service and register it with the provided server instance.
	ServerSetup(server *grpc.Server)
}

ServiceProvider is an entity that provides functionality to be exposed through an RPC server.

type TokenValidator 

type TokenValidator func(token string) (codes.Code, string)

TokenValidator represents an external authentication mechanism used to validate bearer credentials. In case of success return codes.OK; for any error return a proper status code (like codes.Unauthenticated or codes.PermissionDenied) and, optionally, a custom message.

Source Files

View all Source files

Directories

Path Synopsis
Package ws provides a WebSocket proxy with support for bidirectional streaming.
 Package ws provides a WebSocket proxy with support for bidirectional streaming.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.