apis

package
v0.1.6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 26, 2024 License: MIT Imports: 23 Imported by: 0

Documentation

Index

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

func (gw *Gateway) Listen(_ context.Context) error

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

func (gw *Gateway) Shutdown(ctx context.Context) error

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.

func (*Gateway) UseTLS

func (gw *Gateway) UseTLS() bool

UseTLS returns false (default) when Listen() will fire up in normal HTTP mode. If this returns true then Listen() will fire up the underlying server in HTTPS mode using the TLS cert/config you provided when creating the 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

type PreflightOptions cors.Options

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

func (socket *Websocket) Active() bool

Active returns true if the underlying connection has NOT been closed yet.

func (*Websocket) Close

func (socket *Websocket) Close() error

Close kills the current connection. This will also trigger your OnClose handler.

func (*Websocket) Write

func (socket *Websocket) Write(data []byte) error

WriteText writes a frame of binary data to the client on the other end of the socket.

func (*Websocket) WriteClose

func (socket *Websocket) WriteClose(data []byte) error

WriteClose pushes a "close" frame to the client, letting them know that we want to close up shop.

func (*Websocket) WriteJSON

func (socket *Websocket) WriteJSON(value any) error

WriteJSON marshals the given object into a JSON string and then writes a text frame to the client.

func (*Websocket) WriteText

func (socket *Websocket) WriteText(data string) error

WriteText writes a frame of text data to the client on the other end of the socket.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址