Documentation
¶
Index ¶
- func IsolateRequestPanicStreamInterceptor(logger *zap.Logger) grpc.StreamServerInterceptor
- func IsolateRequestPanicUnaryInterceptor(logger *zap.Logger) grpc.UnaryServerInterceptor
- type HTTPHandlerGetter
- type HealthCheck
- type HealthCheckOver
- type HealthGRPCHandler
- type Option
- func OverrideTraceID() Option
- func WithCORS(c *cors.Cors) Optiondeprecated
- func WithConnectCORS(c *cors.Cors) Option
- func WithConnectInterceptor(interceptor connect.Interceptor) Option
- func WithConnectPermissiveCORS() Option
- func WithConnectReflection(location string) Option
- func WithConnectStrictContentType(allowJSON bool) Option
- func WithConnectWebHTTPHandlers(handlerGetters []HTTPHandlerGetter) Option
- func WithEnforceCompression() Option
- func WithGRPCServerOptions(opts ...grpc.ServerOption) Option
- func WithHealthCheck(over HealthCheckOver, check HealthCheck) Option
- func WithInsecureServer() Option
- func WithLogger(logger *zap.Logger) Option
- func WithPermissiveCORS() Optiondeprecated
- func WithPlainTextServer() Option
- func WithPostStreamInterceptor(interceptor grpc.StreamServerInterceptor) Option
- func WithPostUnaryInterceptor(interceptor grpc.UnaryServerInterceptor) Option
- func WithPreStreamInterceptor(interceptor grpc.StreamServerInterceptor) Option
- func WithPreUnaryInterceptor(interceptor grpc.UnaryServerInterceptor) Option
- func WithReflection(location string) Optiondeprecated
- func WithRegisterService(registrator func(gs *grpc.Server)) Option
- func WithSecureServer(config SecureTLSConfig) Option
- func WithServiceDiscoveryURL(u *url.URL) Option
- type Options
- type SecureTLSConfig
- type Server
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsolateRequestPanicStreamInterceptor ¶
func IsolateRequestPanicStreamInterceptor(logger *zap.Logger) grpc.StreamServerInterceptor
IsolateRequestPanicStreamInterceptor returns a new stream server interceptor that isolates panics to individual streaming requests, preventing them from crashing the entire server process and affecting other concurrent requests. When a panic occurs, it is recovered, logged with full stack trace, and converted to a proper gRPC Internal error response.
func IsolateRequestPanicUnaryInterceptor ¶
func IsolateRequestPanicUnaryInterceptor(logger *zap.Logger) grpc.UnaryServerInterceptor
IsolateRequestPanicUnaryInterceptor returns a new unary server interceptor that isolates panics to individual requests, preventing them from crashing the entire server process and affecting other concurrent requests. When a panic occurs, it is recovered, logged with full stack trace, and converted to a proper gRPC Internal error response.
Types ¶
type HTTPHandlerGetter ¶
type HealthCheck ¶
type HealthCheckOver ¶
type HealthCheckOver uint8
HealthCheckOver is a bit field used by the `StandardServer` to decide on what to serve the health check when it's defined.
const ( // HealthCheckOverHTTP tells the `StandardServer` to serve the health check over an HTTP endpoint (`/healthz` by default) HealthCheckOverHTTP HealthCheckOver = 1 << 0 // HealthCheckOverGRPC tells the `StandardServer` to serve the health check over the `grpc.health.v1.HealthServer` GRPC service. HealthCheckOverGRPC HealthCheckOver = 1 << 1 )
func (HealthCheckOver) IsActive ¶
func (v HealthCheckOver) IsActive(on uint8) bool
type HealthGRPCHandler ¶
type HealthGRPCHandler struct {
pbhealth.UnimplementedHealthServer
// contains filtered or unexported fields
}
func NewHealthGRPCHandler ¶
func NewHealthGRPCHandler(check HealthCheck) *HealthGRPCHandler
func (HealthGRPCHandler) Check ¶
func (c HealthGRPCHandler) Check(ctx context.Context, _ *pbhealth.HealthCheckRequest) (*pbhealth.HealthCheckResponse, error)
func (HealthGRPCHandler) Watch ¶
func (c HealthGRPCHandler) Watch(req *pbhealth.HealthCheckRequest, stream pbhealth.Health_WatchServer) error
type Option ¶
type Option func(*Options)
Option represents option that can be used when constructing a gRPC server to customize its behavior.
func OverrideTraceID ¶
func OverrideTraceID() Option
OverrideTraceID option can be used to force the generation of a new fresh trace ID for every gRPC request entering the middleware
func WithConnectCORS ¶
WithConnectCORS Will apply the CORS policy to your server.
**Important** Only taken into consideration by'dgrpc/server/connectrpc#Server' server, ignored by all other server implementations.
func WithConnectInterceptor ¶
func WithConnectInterceptor(interceptor connect.Interceptor) Option
WithConnectInterceptor option can be used to add your own `connectWeb interceptor` after all others defined automatically by the package.
**Important** Only taken into consideration by'dgrpc/server/connectrpc#Server' server, ignored by all other server implementations.
func WithConnectPermissiveCORS ¶
func WithConnectPermissiveCORS() Option
WithConnectPermissiveCORS is for development environments, as it disables any CORS validation.
**Important** Only taken into consideration by'dgrpc/server/connectrpc#Server' server, ignored by all other server implementations.
func WithConnectReflection ¶
WithConnectReflection enables gRPC reflection for the given location string. Can be provided multipe times to enable provide reflection for multiple services.
**Important** Only taken into consideration by'dgrpc/server/connectrpc#Server' server, ignored by all other server implementations.
func WithConnectStrictContentType ¶
WithConnectStrictContentType option can be used to enforce valid content-type
**Important** Only taken into consideration by'dgrpc/server/connectrpc#Server' server, ignored by all other server implementations.
func WithConnectWebHTTPHandlers ¶
func WithConnectWebHTTPHandlers(handlerGetters []HTTPHandlerGetter) Option
WithConnectStrictContentType option can be used to add http hanlders to the connect web server these handlers will be added to the router AFTER the 'connectrpc' handlers, and thus have a lower priority than the 'connectrpc' handlers
**Important** Only taken into consideration by'dgrpc/server/connectrpc#Server' server, ignored by all other server implementations.
func WithEnforceCompression ¶
func WithEnforceCompression() Option
func WithGRPCServerOptions ¶
func WithGRPCServerOptions(opts ...grpc.ServerOption) Option
WithGRPCServerOptions let you configure (or re-configure) the set of gRPC option passed to grpc.NewServer call. The options are appended at the end of gRPC server options computed by `dgrpc`. Using WithGRPCServerOptions you can for example control the grpc.MaxRecvMsgSize, grpc.MaxSendMsgSize, grpc.KeepaliveEnforcementPolicy, grpc.KeepaliveParams and more.
It's important to note that if you pass [grpc_middleware.WithStreamServerChain] or [grpc_middleware.WithUnaryServerChain], you are going to override WithPreUnaryInterceptor, WithPreStreamInterceptor, WithPostUnaryInterceptor and WithPostStreamInterceptor since those are configured via grpc.NewServer.
func WithHealthCheck ¶
func WithHealthCheck(over HealthCheckOver, check HealthCheck) Option
WithHealthCheck option can be used to automatically register an health check function that will be used to determine the health of the server.
If HealthCheckOverHTTP is used, the `Launch` method starts an HTTP endpoint '/healthz' to query the `HealthCheck` method provided information. The endpoint returns an `OK 200` if `HealthCheck` returned `isReady == true`, an `Service Unavailable 503` if `isReady == false`.
The HTTP response body returned depends on the combination of `out` and and `err` from `HealthCheck` call:
- Returns `out` as JSON if `out != nil && err == nil` - Returns `{"error": err.Error()}` JSON if `out == nil && err != nil` - Returns `{"ok": true}` JSON if `out == nil && err == nil`
If HealthCheckOverGRPC is used, the `Launch` method registers within the gRPC server a `grpc.health.v1.HealthServer` that uses the `HealthCheck` `isReady` field to returning either `HealthCheckResponse_SERVING` or `HealthCheckResponse_NOT_SERVING`.
Both option can be provided at a time with `HealthCheckOverHTTP | HealthCheckOverGRPC`
func WithInsecureServer ¶
func WithInsecureServer() Option
WithInsecureServer option can be used to flag to use a TSL config using a built-in self-signed certificate when starting the server which making it exchange in encrypted format but cannot be considered a secure setup.
This is a useful tool for development, **never** use it in a production environment. This is equivalent of using the `Secure(SecuredByBuiltInSelfSignedCertificate)` option.
Important: providing this option erases the settings of the counter-part **SecureServer** option and **PlainTextServer** option, it's mutually exclusive with them.
func WithLogger ¶
WithLogger option can be used to pass the logger that should be used to log stuff within the various middlewares
func WithPermissiveCORS
deprecated
func WithPermissiveCORS() Option
Deprecated: Use WithConnectPermissiveCORS instead
func WithPlainTextServer ¶
func WithPlainTextServer() Option
WithPlainTextServer option can be used to flag to not use a TSL config when starting the server which making it exchanges it's data in **plain-text** format (plain binary is more accurate here).
Important: providing this option erases the settings of the counter-part **InsecureServer** option and **SecureServer** option, it's mutually exclusive with them.
func WithPostStreamInterceptor ¶
func WithPostStreamInterceptor(interceptor grpc.StreamServerInterceptor) Option
WithPostStreamInterceptor option can be used to add your own `grpc.StreamServerInterceptor` after all others defined automatically by the package.
func WithPostUnaryInterceptor ¶
func WithPostUnaryInterceptor(interceptor grpc.UnaryServerInterceptor) Option
WithPostUnaryInterceptor option can be used to add your own `grpc.UnaryServerInterceptor` after all others defined automatically by the package.
func WithPreStreamInterceptor ¶
func WithPreStreamInterceptor(interceptor grpc.StreamServerInterceptor) Option
WithPreStreamInterceptor option can be used to add your own `grpc.StreamServerInterceptor` before all others defined automatically by the package.
func WithPreUnaryInterceptor ¶
func WithPreUnaryInterceptor(interceptor grpc.UnaryServerInterceptor) Option
WithPreUnaryInterceptor option can be used to add your own `grpc.UnaryServerInterceptor` before all others defined automatically by the package.
func WithReflection
deprecated
func WithRegisterService ¶
WithRegisterService option can be used to register the different gRPC services that this server is going to support.
func WithSecureServer ¶
func WithSecureServer(config SecureTLSConfig) Option
WithSecureServer option can be used to flag to use a secured TSL config when starting the server.
The config object can be created by one of the various `SecuredBy...` method on this package like `SecuredByX509KeyPair(certFile, keyFile)`.
Important: providing this option erases the settings of the counter-part **InsecureServer** option and **PlainTextServer** option, it's mutually exclusive with them.
func WithServiceDiscoveryURL ¶
type Options ¶
type Options struct {
HealthCheck HealthCheck
HealthCheckOver HealthCheckOver
Logger *zap.Logger
IsPlainText bool
OverrideTraceID bool
EnforceCompression bool
// GRPC-only options
ServerOptions []grpc.ServerOption
PreUnaryInterceptors []grpc.UnaryServerInterceptor
PreStreamInterceptors []grpc.StreamServerInterceptor
PostUnaryInterceptors []grpc.UnaryServerInterceptor
PostStreamInterceptors []grpc.StreamServerInterceptor
ConnectExtraInterceptors []connect.Interceptor
Registrator func(gs *grpc.Server)
SecureTLSConfig *tls.Config
// ConnectWeb-only options
ConnectWebReflectionServices []string
ConnectWebAllowJSON bool
ConnectWebStrictContentType bool
ConnectWebHTTPHandlers []HTTPHandlerGetter
ConnectWebCORS *cors.Cors
// discovery-service-only options
ServiceDiscoveryURL *url.URL
}
func NewOptions ¶
func NewOptions() *Options
type SecureTLSConfig ¶
func SecuredByBuiltInSelfSignedCertificate ¶
func SecuredByBuiltInSelfSignedCertificate() SecureTLSConfig
SecuredByBuiltInSelfSignedCertificate creates a SecureTLSConfig that uses the built-in hard-coded certificate found in package `insecure` (path `github.com/streamingfast/dgrpc/insecure`).
This certificate is self-signed and distributed publicly over the internet, so it's not a safe certificate, can be seen as compromised.
**Never** uses that in a production environment.
func SecuredByX509KeyPair ¶
func SecuredByX509KeyPair(publicCertFile, privateKeyFile string) (SecureTLSConfig, error)
SecuredByX509KeyPair creates a SecureTLSConfig by loading the provided public/private X509 pair (`.pem` files format).
type Server ¶
type Server interface {
// RegisterService registers one or more gRPC service to the server. The service must be
// registered **before** the `Launch()` method has been called otherwise this is a no-op.
//
// This is a convenience method that calls `f(ServiceRegistrar())`.
RegisterService(f func(gs grpc.ServiceRegistrar))
// ServiceRegistrar returns the `grpc.ServiceRegistrar` that can be used to register
// more services to the server. The returned `grpc.ServiceRegistrar` is only effective
// **before** the `Launch()` method has been called otherwise this is a no-op.
ServiceRegistrar() grpc.ServiceRegistrar
// Launch the server and listen on the given address, this is a blocking call and
// will block the current goroutine until the server is terminated by a call to
// Shutdown() or an error occurs (e.g. the server fails to start).
Launch(serverListenerAddress string)
OnTerminated(f func(err error))
// Shutdown the server, this is a blocking call and will block the current goroutine
// until the server is fully shutdown. The shutdown is performed gracefully, meaning
// that the server will wait for all active connections to be closed before terminating.
//
// If not all connection are closed within the given timeout, the server will force
// shutdown.
//
// Best practices for best functionality is to trap the SIGINT/SIGTERM signals and
// set the process as unready right away and then initiate the shutdown once the
// delay has passed. By doing this, you are going to give the load balancer some
// time to stop sending traffic to this server before it is terminated.
Shutdown(timeout time.Duration)
}
Source Files
Directories