Documentation
¶
Index ¶
- func WalkWebsockets(ctx context.Context, socketPrefix string, ...) error
- type Gateway
- func (gw *Gateway) Listen(_ context.Context) error
- func (gw *Gateway) Middleware() services.MiddlewareFuncs
- func (gw *Gateway) Register(endpoint services.Endpoint, route services.EndpointRoute)
- func (gw *Gateway) Shutdown(ctx context.Context) error
- func (gw *Gateway) Type() services.GatewayType
- func (gw *Gateway) UseTLS() bool
- type GatewayOption
- type HTTPMiddlewareFunc
- type HTTPMiddlewareFuncs
- type PreflightOptions
- type Websocket
- type WebsocketOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WalkWebsockets ¶
func WalkWebsockets(ctx context.Context, socketPrefix string, handler func(ctx context.Context, websocket *Websocket) error) error
WalkWebsockets invokes your callback/handler on all registered websockets that match the given connection ID prefix. For instance, if you want to push a notification to all of a user's active browser sessions, you could walk w/ the connection prefix "user.123" and that would push the notification to the connections named "user.123.A", "user.123.B", and "user.123.C".
All callbacks are executed in separate goroutines, so expect these to run in parallel for all matching sockets.
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) Middleware ¶
func (gw *Gateway) Middleware() services.MiddlewareFuncs
Middleware adds the API-level features that need to be accessible even when you are handling a call that came through the event gateway.
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 ¶
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 ¶
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 ¶
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.
type Websocket ¶
type Websocket struct {
// ID is the unique identifier for this socket. Frodo provides a way for you to look up individual connections,
// so you can push messages as needed, so this id/key helps you locate the websocket later.
ID string
// Conn is the actual TCP connection we're keeping open to handle the communication.
Conn net.Conn
// Options contains our callbacks for handling all manner of reads and the close event.
Options WebsocketOptions
// contains filtered or unexported fields
}
Websocket wraps the connection and other necessary information to provide everything you need to communicate with the client over a recently opened websocket.
func ConnectWebsocket ¶
func ConnectWebsocket(ctx context.Context, connectionID string, opts WebsocketOptions) (*Websocket, error)
ConnectWebsocket hijacks the HTTP connection and makes it so that the user can have duplex communication with a connected client browser/device.
func (*Websocket) Active ¶
Active returns true if the underlying connection has NOT been closed yet.
func (*Websocket) Close ¶
Close kills the current connection. This will also trigger your OnClose handler.
func (*Websocket) Write ¶
WriteText writes a frame of binary data to the client on the other end of the socket.
func (*Websocket) WriteClose ¶
WriteClose pushes a "close" frame to the client, letting them know that we want to close up shop.
type WebsocketOptions ¶
type WebsocketOptions struct {
// Logger lets you customize how you want this debug/trace logging to work.
Logger *slog.Logger
// OnReadText provides a handler for incoming text data.
OnReadText func(ctx context.Context, socket *Websocket, data []byte)
// OnReadBinary provides a handler for incoming binary data.
OnReadBinary func(ctx context.Context, socket *Websocket, data []byte)
// OnReadContinuation provides a handler for incoming continuation frames.
OnReadContinuation func(ctx context.Context, socket *Websocket, data []byte)
// OnClose provides a custom handler that fires when this websocket is closed for any reason.
OnClose func()
}
WebsocketOptions provides the necessary callbacks for handling incoming data read from client connections.