server

Documentation

Overview

Package server initializes an RPC server app, providing gRPC, HTTP, and debug HTTP servers, Jaeger tracing, Zap logging, and Prometheus monitoring.

Index

• Variables
• func AddDrainHandler(f func())
• func AddFlagGroup(name string, data interface{})
• func AddService(cb func(s *grpc.Server))
• func AddStreamInterceptor(i grpc.StreamServerInterceptor)
• func AddStreamInterceptorFn(f func(ic *InterceptorContext) grpc.StreamServerInterceptor)
• func AddUnaryInterceptor(i grpc.UnaryServerInterceptor)
• func AddUnaryInterceptorFn(f func(ic *InterceptorContext) grpc.UnaryServerInterceptor)
• func ListenAndServe()
• func Proto(key string, value interface{}) zap.Field
• func SetHTTPHandler(h http.Handler)
• func SetStartupCallback(cb func(Info))
• func Setup()
• type Info
• type InterceptorContext

Variables

var (
	AppName    = "server"
	AppVersion = "unversioned"
)

Functions

func AddDrainHandler

func AddDrainHandler(f func())

AddDrainHandler registers a function to be called when the server begins draining. It is not safe to add a drain handler while ListenAndServe is running.

The provided drain handler will be called while your server is still serving, allowing you to cleanly interrupt long-lived requests. If your drain handler blocks, it will interfere with a clean shutdown, so don't block. Your handlers will have the configured grace period to react to the drain event.

To cancel select statements, share a channel between the drain handler and your event loop:

drainCh := make(chan struct{})
server.AddDrainHandler(func() { close(drainCh) })
...
server.ListenAndServe()

Then in some long-lived handler:

	for {
		select {
		case <-drainCh:
             	return errors.New("draining")
		case <-ctx.Done():
             	return ctx.Err()
		case <-whatever:
			// whatever
		}
	}

func AddFlagGroup

func AddFlagGroup(name string, data interface{})

AddFlagGroup lets you add your own flags to be parsed with the server-level flags.

func AddService

func AddService(cb func(s *grpc.Server))

AddService registers a gRPC server to be run by the RPC server. It is intended to be used like:

server.AddService(func (s *grpc.Server) { my_proto.RegisterMyService(s, myImplementation) })

func AddStreamInterceptor

func AddStreamInterceptor(i grpc.StreamServerInterceptor)

AddStreamInterceptor adds a grpc stream interceptor to the server.

func AddStreamInterceptorFn

func AddStreamInterceptorFn(f func(ic *InterceptorContext) grpc.StreamServerInterceptor)

AddStreamInterceptorFn adds a stream interceptor, computed by f at server startup time, to the server.

func AddUnaryInterceptor

func AddUnaryInterceptor(i grpc.UnaryServerInterceptor)

AddUnaryInterceptor adds a grpc unary interceptor to the server.

func AddUnaryInterceptorFn

func AddUnaryInterceptorFn(f func(ic *InterceptorContext) grpc.UnaryServerInterceptor)

AddUnaryInterceptorFn adds a unary interceptor, computed by f at server startup time, to the server.

func ListenAndServe

func ListenAndServe()

ListenAndServe starts all servers. SIGTERM or SIGINT will gracefully drain connections. When all servers have exited, this returns. It is not safe to call ListenAndServe again.

func Proto

func Proto(key string, value interface{}) zap.Field

func SetHTTPHandler

func SetHTTPHandler(h http.Handler)

SetHTTPHandler registers an HTTP handler to serve all non-debug HTTP requests. You may only register a single handler; to serve multiple URLs, use an http.ServeMux.

func SetStartupCallback

func SetStartupCallback(cb func(Info))

SetStartupCallback registers a function to be called when the server starts.

func Setup

func Setup()

Setup sets up the necessary global configuration for your server app. It parses flags/environment variables, and initializes logging, tracing, etc.

If there is a problem, we kill the program.

Types

type Info

type Info struct {
	HTTPAddress, DebugAddress, GRPCAddress string
}

Info is provided to an (optional) callback after the server has started. It is mostly useful for tests, but is exposed in case you want to do something after the server has started serving.

type InterceptorContext

type InterceptorContext struct {
	Tracer opentracing.Tracer // The opentracing tracer to be used to trace requests.
	Logger *zap.Logger        // The Zap logger to be used for trace information.  It will never be nil.
}

InterceptorContext is some state passed to interceptor creation functions registered with AddUnaryInterceptorFn and AddStreamInterceptorFn.