Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Gateway ¶
type Gateway struct {
// contains filtered or unexported fields
}
Gateway encapsulates all of the HTTP(S) server and routing components that enable your service to accept incoming requests over RPC/HTTP.
DO NOT CREATE THIS DIRECTLY. Use the NewGateway() constructor to properly set up an API gateway in your main() function.
func NewGateway ¶
func NewGateway(address string, options ...GatewayOption) *Gateway
NewGateway creates a new API Gateway that allows your service to accept incoming requests using RPC over HTTP. This encapsulates a standard net/http server while providing options so that you can customize various aspects of the server, TLS, and middleware as desired.
func (*Gateway) Listen ¶
Listen fires up the underlying HTTP web server and blocks just like the net/http web server code already does. The only difference is that when the gateway shuts down gracefully, this will return nil instead of http.ErrServerClosed. All other errors are propagated back.
func (*Gateway) Register ¶
func (gw *Gateway) Register(endpoint services.Endpoint, route services.EndpointRoute)
Register the operation with the gateway so that it can be exposed for invoking remotely.
func (*Gateway) Shutdown ¶
Shutdown attempts to gracefully shut down the HTTP server. It will wait for any in-progress requests to finish and then shut down (unblocking Listen()). You can provide a context with a deadline to limit how long you want to wait before giving up and shutting down anyway.
func (*Gateway) Type ¶
func (gw *Gateway) Type() services.GatewayType
Type returns "API" to properly tag this type of gateway.
type GatewayOption ¶
type GatewayOption func(*Gateway)
GatewayOption defines a setting you can apply when creating an RPC gateway via 'NewGateway'.
func WithCORS ¶ added in v0.1.4
func WithCORS(options PreflightOptions) GatewayOption
WithCORS lets you customize what happens during the CORS preflight OPTIONS request. The default behavior simply returns a 404, but you can enable this to support CORS preflight requests.
func WithMiddleware ¶
func WithMiddleware(funcs ...HTTPMiddlewareFunc) GatewayOption
WithMiddleware inserts the following chain of HTTP handlers so that they fire before the actual HTTP handler we generate for your service endpoint. The middleware functions use continuation passing style, so you should be able to plug in any off-the-shelf handlers like negroni.
Ideally, you would NOT do any business logic in these middleware functions. It's purely for things like CORS which are very HTTP-specific. Anything like authorization or entity caching should really be done using standard services.MiddlewareFunc handlers - this way they fire regardless of the gateway.
func WithNotFound ¶ added in v0.1.2
func WithNotFound(handler http.HandlerFunc) GatewayOption
WithNotFound lets you customize what happens when an incoming request doesn't match any of your service's routes. By default, the server will respond w/ a 404 and the body {"status":404, "message":"not found"}, but this allows you to handle that situation however you like.
func WithTLSConfig ¶
func WithTLSConfig(config *tls.Config) GatewayOption
WithTLSConfig allows the gateway's underlying HTTP server to handle HTTPS requests using the configuration you provide. If you are using the Let's Encrypt auto-cert manager certificate configurations, this is how you can make your gateway adhere to that cert.
func WithTLSFiles ¶
func WithTLSFiles(certFile string, keyFile string) GatewayOption
WithTLSFiles allows the gateway's underlying HTTP server to handle HTTPS requests using the cert/key files provided.
type HTTPMiddlewareFunc ¶
type HTTPMiddlewareFunc func(w http.ResponseWriter, req *http.Request, next http.HandlerFunc)
HTTPMiddlewareFunc is a function that can intercept HTTP requests going through your API gateway, allowing you to directly manipulate the HTTP request/response as needed.
type HTTPMiddlewareFuncs ¶
type HTTPMiddlewareFuncs []HTTPMiddlewareFunc
HTTPMiddlewareFuncs defines an ordered pipeline of middleware functions you want an endpoint in your API gateway to perform.
func (HTTPMiddlewareFuncs) Append ¶
func (funcs HTTPMiddlewareFuncs) Append(functions ...HTTPMiddlewareFunc) HTTPMiddlewareFuncs
Append adds the given function(s) to the END of the receiver's current pipeline.
middlewareFuncs := HTTPMiddlewareFuncs{A, B, C}
middlewareFuncs = middlewareFuncs.Append(D, E, F)
middlewareFuncs ==> {A, B, C, D, E, F}
func (HTTPMiddlewareFuncs) Then ¶
func (funcs HTTPMiddlewareFuncs) Then(handler http.HandlerFunc) http.HandlerFunc
Then converts an entire middleware chain/pipeline into a single handler function that can be registered with a server/router. The 'handler' parameter goes at the very end of the chain; the idea being that you perform all of your middleware tasks and 'handler' is the "real work" you wanted to accomplish all along.
type PreflightOptions ¶ added in v0.1.4
PreflightOptions manages the knobs you can turn to control how CORS behaves in your API gateway. Yes, this really is just an alias to the https://github.com/rs/cors options. It's the gold standard for CORS in the Go ecosystem, so we're just providing a convenient way to plug it in.
Source Files