# README
Welcome to the 2nd generation of Gizmo servers 🚀!
Gizmo's intentions from the beginning were to eventually join forces with the wonders of the go-kit toolkit. This package is meant to embody that goal.
The kit server is composed of multiple kit/transport/http.Servers that are tied together with a common HTTP mux, HTTP options and middlewares. By default all HTTP endpoints will be encoded as JSON, but developers may override each HTTPEndpoint to use whatever encoding they need. If users need to use gRPC, they can can register the same endpoints to serve both HTTP and gRPC requests on two different ports.
This server expects to be configured via environment variables. The available variables can be found by inspecting the Config struct within this package. If no health check or warm up endpoints are defined, this server will automatically register basic endpoints there to return a simple "200 OK" response.
Since NYT uses Google Cloud, deploying this server to that environment provides additional perks:
- If running in the App Engine 2nd Generation runtime (Go >=1.11), servers will:
- Automatically catch any panics and send them to Stackdriver Error reporting
- Automatically use Stackdriver logging and, if
kit.LogXXXfunctions are used, logs will be trace enabled and will be combined with their parent access log in the Stackdriver logging console. - Automatically register Stackdriver exporters for Open Census trace and monitoring. Most Google Cloud clients (like Cloud Spanner) will detect this and emit the traces. Users can also add their own trace and monitoring spans via the Open Census clients.
- Monitoring, traces and metrics are automatically registered if running within App Engine, Kubernetes Engine, Compute Engine or AWS EC2 Instances. To change the name and version for Error reporting and Traces use
SERVICE_NAMEandSERVICE_VERSIONenvironment variables.
For an example of how to build a server that utilizes this package, see the Reading List example.
# Functions
AddLogKeyVals will add any common HTTP headers or gRPC metadata from the given context to the given logger as fields.
CustomRouter allows users to inject an alternate Router implementation.
EncodeProtoResponse is an httptransport.EncodeResponseFunc that serializes the response as Protobuf.
Log will pull a request scoped log.Logger from the context and log the given keyvals with it.
LogDebug will log the given message to the server logger with the key "message" along with all the common request headers or gRPC metadata.
LogDebugf will format the given string with the arguments then log to the server logger with the key "message" along with all the common request headers or gRPC metadata.
LogErrorf will format the given string with the arguments then log to the server logger with the key "message" along with all the common request headers or gRPC metadata.
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.
Logf will format the given string with the arguments then log to the server logger with the key "message" along with all the common request headers or gRPC metadata.
Logger will return a kit/log.Logger that has been injected into the context by the kit server.
LogMsg will log the given message to the server logger with the key "message" along with all the common request headers or gRPC metadata.
LogWarning will log the given message to the server logger with the key "message" along with all the common request headers or gRPC metadata.
LogWarningf will the format given string with the arguments then log to the server logger with the key "message" along with all the common request headers or gRPC metadata.
NewJSONStatusResponse allows users to respond with a specific HTTP status code and a JSON serialized response.
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.
NewProtoStatusResponse allows users to respond with a specific HTTP status code and a Protobuf or JSON serialized response.
NewServer will create a new kit server for the given Service.
RouterNotFound will set the not found handler of the router.
RouterSelect allows users to override the default use of the Gorilla Router.
Run will use environment variables to configure the server then register the given Service and start up the server(s).
SetLogger sets log.Logger to the context and returns new context with logger.
SetRouteVars will set the given value into into the request context with the shared 'vars' storage key.
Vars is a helper function for accessing route parameters from any server.Router implementation.
# Constants
ContextKeyCloudTraceContext is a context key for storing and retrieving the inbound 'x-cloud-trace-context' header.
# Structs
Config holds info required to configure a gizmo kit.Server.
HTTPEndpoint encapsulates everything required to build an endpoint hosted on a kit server.
JSONStatusResponse implements: `httptransport.StatusCoder` to allow users to respond with the given response with a non-200 status code.
ProtoStatusResponse implements: `httptransport.StatusCoder` to allow users to respond with the given response with a non-200 status code.
Server encapsulates all logic for registering and running a gizmo kit server.
# Interfaces
Router is an interface to wrap different router implementations.
Service is the interface of mixed HTTP/gRPC that can be registered and hosted by a gizmo/server/kit server.
Shutdowner allows your service to shutdown gracefully when http server stops.
# Type aliases
RouterOption sets optional Router overrides.