gizmo: github.com/NYTimes/gizmo/server/kit Index | Files

package kit

import "github.com/NYTimes/gizmo/server/kit"

Package kit implements an opinionated server based on go-kit primitives.

Index

Package Files

config.go kitserver.go log.go response.go router.go sd_log.go server.go service.go

Constants

const (

    // ContextKeyCloudTraceContext is a context key for storing and retrieving the
    // inbound 'x-cloud-trace-context' header. This server will automatically look for
    // and inject the value into the request context. If in the App Engine environment
    // this will be used to enable combined access and application logs.
    ContextKeyCloudTraceContext contextKey
)

func AddLogKeyVals Uses

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 EncodeProtoResponse Uses

func EncodeProtoResponse(ctx context.Context, w http.ResponseWriter, pres interface{}) error

EncodeProtoResponse is an httptransport.EncodeResponseFunc that serializes the response as Protobuf. Many Proto-over-HTTP services can use it as a sensible default. If the response implements Headerer, the provided headers will be applied to the response. If the response implements StatusCoder, the provided StatusCode will be used instead of 200.

func Log Uses

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 Uses

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

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

func LogMsg Uses

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

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

func Logger Uses

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 NewLogger Uses

func NewLogger(ctx context.Context, logID string) (log.Logger, func() error, error)

NewLogger will inspect the environment and, if running in the Google App Engine, Google Kubernetes Engine, Google Compute Engine or AWS EC2 environment, it will return a new Stackdriver logger annotated with the current server's project ID, service ID and version and other environment specific values. If not in App Engine, GKE, GCE or AWS EC2 - a normal JSON logger pointing to stdout will be returned. This function can be used for services that need to log information outside the context of an inbound request. When using the Stackdriver logger, any go-kit/log/levels will be translated to Stackdriver severity levels. The logID field is used when the server is deployed in a Stackdriver enabled environment. If an empty string is provided, "gae_log" will be used in App Engine and "stdout" elsewhere. For more information about to use of logID see the documentation here: https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.log_name

func Run Uses

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 SetLogger Uses

func SetLogger(ctx context.Context, logger log.Logger) context.Context

SetLogger sets log.Logger to the context and returns new context with logger.

func SetRouteVars Uses

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 Uses

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.

type Config Uses

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 Uses

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 Uses

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 Uses

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 Uses

func (c *JSONStatusResponse) Error() string

Error is to implement error

func (*JSONStatusResponse) MarshalJSON Uses

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

MarshalJSON is to implement json.Marshaler

func (*JSONStatusResponse) StatusCode Uses

func (c *JSONStatusResponse) StatusCode() int

StatusCode is to implement httptransport.StatusCoder

type ProtoStatusResponse Uses

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

ProtoStatusResponse implements: `httptransport.StatusCoder` to allow users to respond with the given response with a non-200 status code. `proto.Marshaler` and proto.Message so it can wrap a proto Endpoint responses. `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 NewProtoStatusResponse Uses

func NewProtoStatusResponse(res proto.Message, code int) *ProtoStatusResponse

NewProtoStatusResponse allows users to respond with a specific HTTP status code and a Protobuf or JSON serialized response.

func (*ProtoStatusResponse) Error Uses

func (c *ProtoStatusResponse) Error() string

to implement error

func (*ProtoStatusResponse) Marshal Uses

func (c *ProtoStatusResponse) Marshal() ([]byte, error)

Marshal is to implement proto.Marshaler. It will marshal the given message, not this struct.

func (*ProtoStatusResponse) MarshalJSON Uses

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

MarshalJSON is to implement json.Marshaler. It will marshal the given message, not this struct.

func (*ProtoStatusResponse) ProtoMessage Uses

func (c *ProtoStatusResponse) ProtoMessage()

ProtoMessage is to implement proto.Message. It uses the given message's ProtoMessage method.

func (*ProtoStatusResponse) Reset Uses

func (c *ProtoStatusResponse) Reset()

Reset is to implement proto.Message. It uses the given message's Reset method.

func (*ProtoStatusResponse) StatusCode Uses

func (c *ProtoStatusResponse) StatusCode() int

StatusCode implements httptransport.StatusCoder and will return the given HTTP code.

func (*ProtoStatusResponse) String Uses

func (c *ProtoStatusResponse) String() string

String is to implement proto.Message. It uses the given message's String method.

type Router Uses

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 Uses

type RouterOption func(Router) Router

RouterOption sets optional Router overrides.

func CustomRouter Uses

func CustomRouter(r Router) RouterOption

CustomRouter allows users to inject an alternate Router implementation.

func RouterNotFound Uses

func RouterNotFound(h http.Handler) RouterOption

RouterNotFound will set the not found handler of the router.

func RouterSelect Uses

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 Uses

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

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

func NewServer Uses

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 Uses

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

type Service Uses

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 dependencies (business services, repositories, etc.) into each request handler.

type Shutdowner Uses

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.

Package kit imports 42 packages (graph) and is imported by 6 packages. Updated 2019-04-16. Refresh now. Tools for package owners.