README
¶
Marvin is a go-kit server for Google App Engine
Marvin + GAE -> let's get it oooonnnn!
Marvin provides common tools and structure for services being built on Google App Engine by leaning heavily on the go-kit/kit/transport/http package. The service interface here is very similar to the service interface in NYT's gizmo/server/kit package so teams can build very similar looking software but use vasty different styles of infrastructure.
Marvin has been built to work with Go 1.8, which is available on App Engine Standard.
The Marvin logo is based on the Go mascot designed by Renée French and copyrighted under the Creative Commons Attribution 3.0 license.
Documentation
¶
Index ¶
- Constants
- func AllowIPNets(ipnets []*net.IPNet, denial interface{}) endpoint.Middleware
- func CORSHandler(f http.Handler, originSuffix string) http.Handler
- func EncodeProtoRequest(_ context.Context, r *http.Request, preq interface{}) error
- func EncodeProtoResponse(ctx context.Context, w http.ResponseWriter, pres interface{}) error
- func Init(service Service)
- func Internal(ep endpoint.Endpoint, denial error) endpoint.Endpoint
- func ParseIPNets(ipStr string) ([]*net.IPNet, error)
- func ScalingHandler(ctx context.Context, _ interface{}) (interface{}, error)
- func SetRouteVars(r *http.Request, val map[string]string) *http.Request
- func Vars(r *http.Request) map[string]string
- type GorillaRouter
- func (g *GorillaRouter) Handle(method, path string, h http.Handler)
- func (g *GorillaRouter) HandleFunc(method, path string, h func(http.ResponseWriter, *http.Request))
- func (g *GorillaRouter) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (g *GorillaRouter) SetNotFoundHandler(h http.Handler)
- type HTTPEndpoint
- type JSONEndpointer
- type JSONService
- type JSONStatusResponse
- type MixedService
- type ProtoEndpointer
- type ProtoService
- type ProtoStatusResponse
- func (c *ProtoStatusResponse) Error() string
- func (c *ProtoStatusResponse) Marshal() ([]byte, error)
- func (c *ProtoStatusResponse) MarshalJSON() ([]byte, error)
- func (c *ProtoStatusResponse) ProtoMessage()
- func (c *ProtoStatusResponse) Reset()
- func (c *ProtoStatusResponse) StatusCode() int
- func (c *ProtoStatusResponse) String() string
- type Router
- type RouterOption
- type Server
- type Service
- type StdlibRouter
Constants ¶
const ( // ContextKeyInboundAppID is populated in the context by default. // It contains the value of the 'X-Appengine-Inbound-Appid' header. ContextKeyInboundAppID contextKey = iota )
Variables ¶
This section is empty.
Functions ¶
func AllowIPNets ¶
func AllowIPNets(ipnets []*net.IPNet, denial interface{}) endpoint.Middleware
AllowIPNets is a middleware to only allow access to requests that exist in one of the given IPNets. If no IPNets are provided, all requests are allowed to pass through. If the request is denied access, the given response will be returned.
func CORSHandler ¶
CORSHandler is a middleware func for setting all headers that enable CORS. If an originSuffix is provided, a strings.HasSuffix check will be performed before adding any CORS header. If an empty string is provided, any Origin header found will be placed into the CORS header. If no Origin header is found, no headers will be added.
func EncodeProtoRequest ¶
EncodeProtoRequest is an httptransport.EncodeRequestFunc that serializes the request as Protobuf. If the request implements Headerer, the provided headers will be applied to the request.
func EncodeProtoResponse ¶
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 Init ¶
func Init(service Service)
Init will register the Service with a Server and register the server with App Engine. Call this in an `init()` or `main()` function.
func Internal ¶
Internal is a middleware handler meant to mark an endpoint or service for service-to-service use only. If the incoming request does not contain an 'X-Appengine-Inbound-Appid' header that matches the AppID of the current service, this handler will return with with the given denial response.
If no denial is given, the server will respond with a 401 status code and a simple JSON response. If you supply your own denial, we recommend you use the Proto/JSONStatusResponse structs to respond with a specific status code and the appropriate serialization.
More info on the 'X-Appengine-Inbound-Appid' header here: https://cloud.google.com/appengine/docs/standard/go/appidentity/#asserting_identity_to_other_app_engine_apps
func ParseIPNets ¶
ParseIPNets will accept a comma delimited list of CIDR blocks, parse them and return a slice of net.IPNets.
func ScalingHandler ¶
ScalingHandler is a utility endpoint for adjusting the 'min_idle_instances' of the current service on the fly. While App Engine's automatic scaling is sufficient for most uses cases, we've found that some very large bursts of traffic (i.e. the spike just after the new NYT crossword is published) cannot keep up without a large number of idle instances at the ready. To avoid the high cost of always having large amounts of idle instances, this endpoint can be used to preemptively scale your service up before a spike and then back down to normal levels post spike.
This handler expects to be registered at `/_ah/push-handlers/scale/{dir:(up|down}` as a JSON Endpoint and it expects the environment to be provisioned with `IDLE_INSTANCES_UP` and `IDLE_INSTANCES_DOWN` environment variables to set the number of min_idle_instances before and after scaling events.
This endpoint can be hit using App Engine cron for regularly recurring spikes but to make this endpoint capable of sucurely accepting pushes from PubSub, it has the `/_ah/push-handlers/` prefix.
func SetRouteVars ¶
SetRouteVars will set the given value into into the request context with the shared 'vars' storage key.
Types ¶
type GorillaRouter ¶
type GorillaRouter struct {
// contains filtered or unexported fields
}
GorillaRouter is a Router implementation for the Gorilla web toolkit's `mux.Router`.
func (*GorillaRouter) Handle ¶
func (g *GorillaRouter) Handle(method, path string, h http.Handler)
Handle will call the Gorilla web toolkit's Handle().Method() methods.
func (*GorillaRouter) HandleFunc ¶
func (g *GorillaRouter) HandleFunc(method, path string, h func(http.ResponseWriter, *http.Request))
HandleFunc will call the Gorilla web toolkit's HandleFunc().Method() methods.
func (*GorillaRouter) ServeHTTP ¶
func (g *GorillaRouter) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP will call Gorilla mux.Router.ServerHTTP directly.
func (*GorillaRouter) SetNotFoundHandler ¶
func (g *GorillaRouter) SetNotFoundHandler(h http.Handler)
SetNotFoundHandler will set the Gorilla mux.Router.NotFoundHandler.
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 an HTTP server.
type JSONEndpointer ¶
type JSONEndpointer interface {
JSONEndpoints() map[string]map[string]HTTPEndpoint
}
JSONEndpointer is for HTTP endpoints with JSON serialization The first map's string is for the HTTP path, the second is for the http method. For example:
return map[string]map[string]marvin.HTTPEndpoint{
"/cat/{id}.json": {
"GET": {
Endpoint: s.GetCatByID,
Decoder: decodeGetCatRequest,
},
},
"/cats.json": {
"PUT": {
Endpoint: s.PutCats,
Decoder: decodePutCatsProtoRequest,
},
"GET": {
Endpoint: s.GetCats,
Decoder: decodeGetCatsRequest,
},
},
}
type JSONService ¶
type JSONService interface {
Service
JSONEndpointer
}
JSONService endpoints are for HTTP endpoints with JSON serialization. This service will add default decoder/encoders if none provided.
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 MixedService ¶
type MixedService interface {
Service
JSONEndpointer
ProtoEndpointer
}
MixedService combines the Proto and JSON services to allow users to expose endpoints on both JSON and Protobuf.
type ProtoEndpointer ¶
type ProtoEndpointer interface {
ProtoEndpoints() map[string]map[string]HTTPEndpoint
}
ProtoEndpointer is for HTTP endpoints with protobuf serialization. The first map's string is for the HTTP path, the second is for the http method. For example:
return map[string]map[string]marvin.HTTPEndpoint{
"/cat/{id}.proto": {
"GET": {
Endpoint: s.GetCatByID,
Decoder: decodeGetCatRequest,
},
},
"/cats.proto": {
"PUT": {
Endpoint: s.PutCats,
Decoder: decodePutCatsRequest,
},
"GET": {
Endpoint: s.GetCats,
Decoder: decodeGetCatsRequest,
},
},
}
type ProtoService ¶
type ProtoService interface {
Service
ProtoEndpointer
}
ProtoService endpoints are for HTTP endpoints with Protobuf serialization. This service will add default decoder/encoders if none provided.
type ProtoStatusResponse ¶
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 ¶
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) Marshal ¶
func (c *ProtoStatusResponse) Marshal() ([]byte, error)
to implement proto.Marshaler
func (*ProtoStatusResponse) MarshalJSON ¶
func (c *ProtoStatusResponse) MarshalJSON() ([]byte, error)
to implement json.Marshaler
func (*ProtoStatusResponse) ProtoMessage ¶
func (c *ProtoStatusResponse) ProtoMessage()
func (*ProtoStatusResponse) Reset ¶
func (c *ProtoStatusResponse) Reset()
to implement proto.Message
func (*ProtoStatusResponse) StatusCode ¶
func (c *ProtoStatusResponse) StatusCode() int
to implement httptransport.StatusCoder
func (*ProtoStatusResponse) String ¶
func (c *ProtoStatusResponse) String() string
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 ¶
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 GorillaRouter with one of the other implementations.
The following router names are accepted: * `gorilla` which uses github.com/gorilla/mux (on by default) * `stdlib` to utilize the standard library's http.ServeMux
If the supplied name does not match any known router, `gorilla` will be used. If a user wishes to supply their own router implementation, the `CustomRouter` option is available.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server manages routing and initiating the request context. Users should only need to interact with this struct in testing.
See examples/reading-list/api/service_test.go for example usage.
type Service ¶
type Service interface {
// HTTPMiddleware is for service-wide http specific middlewares
// for easy integration with 3rd party http.Handlers.
HTTPMiddleware(http.Handler) http.Handler
// Middleware is for any service-wide go-kit middlewares
Middleware(endpoint.Endpoint) endpoint.Endpoint
// Options are service-wide go-kit options
Options() []httptransport.ServerOption
// RouterOptions allows users to override the default
// behavior and use of the GorillaRouter.
RouterOptions() []RouterOption
}
Service is the most basic interface of a service that can be received and hosted by Google App Engine. By default, if no warmup request is provided, marvin will add a basic handler to the /_ah/warmup route for you.
type StdlibRouter ¶
type StdlibRouter struct {
// contains filtered or unexported fields
}
StdlibRouter is a Router implementation for the Stdlib's `http.ServeMux`.
func (*StdlibRouter) Handle ¶
func (g *StdlibRouter) Handle(method, path string, h http.Handler)
Handle will call the Stdlib's HandleFunc() methods with a check for the incoming HTTP method. To allow for multiple methods on a single route, use 'ANY'.
func (*StdlibRouter) HandleFunc ¶
func (g *StdlibRouter) HandleFunc(method, path string, h func(http.ResponseWriter, *http.Request))
HandleFunc will call the Stdlib's HandleFunc() methods with a check for the incoming HTTP method. To allow for multiple methods on a single route, use 'ANY'.
func (*StdlibRouter) ServeHTTP ¶
func (g *StdlibRouter) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP will call Stdlib's ServeMux.ServerHTTP directly.
func (*StdlibRouter) SetNotFoundHandler ¶
func (g *StdlibRouter) SetNotFoundHandler(h http.Handler)
SetNotFoundHandler will do nothing as we cannot override the stdlib not found.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
reading-list
Package readinglist is a generated protocol buffer package.
|
Package readinglist is a generated protocol buffer package. |