kit

README

This is an experimental package in Gizmo!

• The rationale behind this package:

  • A more opinionated server with fewer choices.
  • go-kit is used for serving HTTP/JSON & gRPC is used for serving HTTP2/RPC
  • Monitoring and metrics are handled by a sidecar (ie. Cloud Endpoints)
  • Logs always go to stdout/stderr
  • Using Go's 1.8 graceful HTTP shutdown
  • Services using this package are meant for deploy to GCP with GKE and Cloud Endpoints.

• If you experience any issues please create an issue and/or reach out on the #gizmo channel with what you've found

Documentation

Index

• func AddLogKeyVals(ctx context.Context, l log.Logger) log.Logger
• func Log(ctx context.Context, keyvals ...interface{}) error
• func LogErrorMsg(ctx context.Context, err error, msg string) error
• func LogMsg(ctx context.Context, msg string) error
• func Logger(ctx context.Context) log.Logger
• func Run(service Service) error
• func SetRouteVars(r *http.Request, val interface{}) *http.Request
• func Vars(r *http.Request) map[string]string
• type Config
• type HTTPEndpoint
• type JSONStatusResponse
  • func NewJSONStatusResponse(res interface{}, code int) *JSONStatusResponse
  • func (c *JSONStatusResponse) Error() string
  • func (c *JSONStatusResponse) MarshalJSON() ([]byte, error)
  • func (c *JSONStatusResponse) StatusCode() int
• type Router
• type RouterOption
  • func CustomRouter(r Router) RouterOption
  • func RouterNotFound(h http.Handler) RouterOption
  • func RouterSelect(name string) RouterOption
• type Server
  • func NewServer(svc Service) *Server
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Service
• type Shutdowner

Functions

func AddLogKeyVals

func AddLogKeyVals(ctx context.Context, l log.Logger) log.Logger

AddLogKeyVals will add any common HTTP headers or gRPC metadata from the given context to the given logger as fields. This is used by the server to initialize the request scopes logger.

func Log

func Log(ctx context.Context, keyvals ...interface{}) error

Log will pull a request scoped log.Logger from the context and log the given keyvals with it.

func LogErrorMsg

func LogErrorMsg(ctx context.Context, err error, msg string) error

LogErrorMsg will log the given error under the key "error", the given message under the key "msg" along with all the common request headers or gRPC metadata.

func LogMsg

func LogMsg(ctx context.Context, msg string) error

LogMsg will log the given message to the server logger with the key "msg" along with all the common request headers or gRPC metadata.

func Logger

func Logger(ctx context.Context) log.Logger

Logger will return a kit/log.Logger that has been injected into the context by the kit server. This logger has had request headers and metadata added as key values. This function will only work within the scope of a request initiated by the server.

func Run

func Run(service Service) error

Run will use environment variables to configure the server then register the given Service and start up the server(s). This will block until the server shuts down.

func SetRouteVars

func SetRouteVars(r *http.Request, val interface{}) *http.Request

SetRouteVars will set the given value into into the request context with the shared 'vars' storage key.

func Vars

func Vars(r *http.Request) map[string]string

Vars is a helper function for accessing route parameters from any server.Router implementation. This is the equivalent of using `mux.Vars(r)` with the Gorilla mux.Router.

Types

type Config

type Config struct {
	// HealthCheckPath is used by server to init the proper HealthCheckHandler.
	// If empty, this will default to '/healthz'.
	HealthCheckPath string `envconfig:"GIZMO_HEALTH_CHECK_PATH"`

	// MaxHeaderBytes can be used to override the default of 1<<20.
	MaxHeaderBytes int `envconfig:"GIZMO_MAX_HEADER_BYTES"`

	// ReadTimeout can be used to override the default http server timeout of 10s.
	// The string should be formatted like a time.Duration string.
	ReadTimeout time.Duration `envconfig:"GIZMO_READ_TIMEOUT"`

	// WriteTimeout can be used to override the default http server timeout of 10s.
	// The string should be formatted like a time.Duration string.
	WriteTimeout time.Duration `envconfig:"GIZMO_WRITE_TIMEOUT"`

	// IdleTimeout can be used to override the default http server timeout of 120s.
	// The string should be formatted like a time.Duration string.
	IdleTimeout time.Duration `envconfig:"GIZMO_IDLE_TIMEOUT"`

	// ShutdownTimeout can be used to override the default http server shutdown timeout
	// of 5m.
	ShutdownTimeout time.Duration `envconfig:"GIZMO_SHUTDOWN_TIMEOUT"`

	// GOMAXPROCS can be used to override the default GOMAXPROCS.
	GOMAXPROCS int `envconfig:"GIZMO_GOMAXPROCS"`

	// HTTPPort is the port the server implementation will serve HTTP over.
	// The default is 8080
	HTTPPort int `envconfig:"HTTP_PORT"`
	// RPCPort is the port the server implementation will serve RPC over.
	// The default is 8081.
	RPCPort int `envconfig:"RPC_PORT"`

	// Enable pprof Profiling. Off by default.
	EnablePProf bool `envconfig:"ENABLE_PPROF"`
}

Config holds info required to configure a gizmo kit.Server.

This struct is loaded from the environment at Run and only made public to expose for documentation.

type HTTPEndpoint

type HTTPEndpoint struct {
	Endpoint endpoint.Endpoint
	Decoder  httptransport.DecodeRequestFunc
	Encoder  httptransport.EncodeResponseFunc
	Options  []httptransport.ServerOption
}

HTTPEndpoint encapsulates everything required to build an endpoint hosted on a kit server.

type JSONStatusResponse

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

JSONStatusResponse implements: `httptransport.StatusCoder` to allow users to respond with the given response with a non-200 status code. `json.Marshaler` so it can wrap JSON Endpoint responses. `error` so it can be used to respond as an error within the go-kit stack.

func NewJSONStatusResponse

func NewJSONStatusResponse(res interface{}, code int) *JSONStatusResponse

NewJSONStatusResponse allows users to respond with a specific HTTP status code and a JSON serialized response.

func (*JSONStatusResponse) Error

func (c *JSONStatusResponse) Error() string

Error is to implement error

func (*JSONStatusResponse) MarshalJSON

func (c *JSONStatusResponse) MarshalJSON() ([]byte, error)

MarshalJSON is to implement json.Marshaler

func (*JSONStatusResponse) StatusCode

func (c *JSONStatusResponse) StatusCode() int

StatusCode is to implement httptransport.StatusCoder

type Router

type Router interface {
	Handle(method string, path string, handler http.Handler)
	HandleFunc(method string, path string, handlerFunc func(http.ResponseWriter, *http.Request))
	ServeHTTP(w http.ResponseWriter, r *http.Request)
	SetNotFoundHandler(handler http.Handler)
}

Router is an interface to wrap different router implementations.

type RouterOption

type RouterOption func(Router) Router

RouterOption sets optional Router overrides.

func CustomRouter

func CustomRouter(r Router) RouterOption

CustomRouter allows users to inject an alternate Router implementation.

func RouterNotFound

func RouterNotFound(h http.Handler) RouterOption

RouterNotFound will set the not found handler of the router.

func RouterSelect

func RouterSelect(name string) RouterOption

RouterSelect allows users to override the default use of the Gorilla Router. TODO add type and constants for names + docs

type Server

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

Server encapsulates all logic for registering and running a gizmo kit server.

func NewServer

func NewServer(svc Service) *Server

NewServer will create a new kit server for the given Service.

Generally, users should only use the 'Run' function to start a server and use this function within tests so they may call ServeHTTP.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Service

type Service interface {
	// Middleware is for any service-wide go-kit middlewares. This middleware
	// is applied to both HTTP and gRPC services.
	Middleware(endpoint.Endpoint) endpoint.Endpoint

	// HTTPMiddleware is for service-wide http specific middleware
	// for easy integration with 3rd party http.Handlers like nytimes/gziphandler.
	HTTPMiddleware(http.Handler) http.Handler

	// HTTPOptions are service-wide go-kit HTTP server options
	HTTPOptions() []httptransport.ServerOption

	// HTTPRouterOptions allows users to override the default
	// behavior and use of the GorillaRouter.
	HTTPRouterOptions() []RouterOption

	// HTTPEndpoints default to using a JSON serializer if no encoder is provided.
	// For example:
	//
	//    return map[string]map[string]kit.HTTPEndpoint{
	//        "/cat/{id}": {
	//            "GET": {
	//                Endpoint: s.GetCatByID,
	//                Decoder:  decodeGetCatRequest,
	//            },
	//        },
	//        "/cats": {
	//            "PUT": {
	//                Endpoint: s.PutCats,
	//                HTTPDecoder:  decodePutCatsProtoRequest,
	//            },
	//            "GET": {
	//                Endpoint: s.GetCats,
	//                HTTPDecoder:  decodeGetCatsRequest,
	//            },
	//        },
	//  }
	HTTPEndpoints() map[string]map[string]HTTPEndpoint

	// RPCMiddleware is for any service-wide gRPC specific middleware
	// for easy integration with 3rd party grpc.UnaryServerInterceptors like
	// http://godoc.org/cloud.google.com/go/trace#Client.GRPCServerInterceptor
	//
	// The underlying kit server already uses the one available grpc.UnaryInterceptor
	// grpc.ServerOption so attempting to pass your own in this Service's RPCOptions()
	// will cause a panic at startup.
	//
	// If you want to apply multiple RPC middlewares,
	// we recommend using:
	// http://godoc.org/github.com/grpc-ecosystem/go-grpc-middleware#ChainUnaryServer
	RPCMiddleware() grpc.UnaryServerInterceptor

	// RPCServiceDesc allows services to declare an alternate gRPC
	// representation of themselves to be hosted on the RPC_PORT (8081 by default).
	RPCServiceDesc() *grpc.ServiceDesc

	// RPCOptions are for service-wide gRPC server options.
	//
	// The underlying kit server already uses the one available grpc.UnaryInterceptor
	// grpc.ServerOption so attempting to pass your own in this method will cause a panic
	// at startup. We recommend using RPCMiddleware() to fill this need.
	RPCOptions() []grpc.ServerOption
}

Service is the interface of mixed HTTP/gRPC that can be registered and hosted by a gizmo/server/kit server. Services provide hooks for service-wide options and middlewares and can be used as a means of dependency injection. In general, a Service should just contain the logic for deserializing and authorizing requests, passing the request to a business logic interface abstraction, handling errors and serializing the apprioriate response.

In other words, each Endpoint is similar to a 'controller' and the Service a container for injecting depedencies (business services, repositories, etc.) into each request handler.

type Shutdowner

type Shutdowner interface {
	Shutdown()
}

Shutdowner allows your service to shutdown gracefully when http server stops. This may used when service has any background task which needs to be completed gracefully.