server

Documentation

Overview

Commons for HTTP handling

Index

• func Listen(addr string, maxOpenConnections int) (listener net.Listener, err error)
• func OnDisconnect(onDisconnect func(remoteAddr string)) func(*wsConnection)
• func PingPeriod(pingPeriod time.Duration) func(*wsConnection)
• func PreChecksHandler(next http.Handler, config *Config) http.Handler
• func ReadLimit(readLimit int64) func(*wsConnection)
• func ReadWait(readWait time.Duration) func(*wsConnection)
• func RecoverAndLogHandler(handler http.Handler, logger log.Logger) http.Handler
• func RegisterRPCFuncs(mux *http.ServeMux, funcMap map[string]*RPCFunc, logger log.Logger)
• func Serve(listener net.Listener, handler http.Handler, logger log.Logger, config *Config) error
• func ServeTLS(listener net.Listener, handler http.Handler, certFile, keyFile string, ...) error
• func WriteCacheableRPCResponseHTTP(w http.ResponseWriter, res ...types.RPCResponse) error
• func WriteChanCapacity(cap int) func(*wsConnection)
• func WriteRPCResponseHTTP(w http.ResponseWriter, res ...types.RPCResponse) error
• func WriteRPCResponseHTTPError(w http.ResponseWriter, httpCode int, res types.RPCResponse) error
• func WriteWait(writeWait time.Duration) func(*wsConnection)
• type Config
  • func DefaultConfig() *Config
• type Option
  • func Cacheable(noCacheDefArgs ...string) Option
  • func Ws() Option
• type RPCFunc
  • func NewRPCFunc(f any, args string, options ...Option) *RPCFunc
  • func NewWSRPCFunc(f any, args string, options ...Option) *RPCFunc
• type WebsocketManager
  • func NewWebsocketManager(funcMap map[string]*RPCFunc, wsConnOptions ...func(*wsConnection)) *WebsocketManager
  • func (wm *WebsocketManager) SetLogger(l log.Logger)
  • func (wm *WebsocketManager) WebsocketHandler(w http.ResponseWriter, r *http.Request)

Functions

func Listen

func Listen(addr string, maxOpenConnections int) (listener net.Listener, err error)

Listen starts a new net.Listener on the given address. It returns an error if the address is invalid or the call to Listen() fails.

func OnDisconnect

func OnDisconnect(onDisconnect func(remoteAddr string)) func(*wsConnection)

OnDisconnect sets a callback which is used upon disconnect - not Goroutine-safe. Nop by default.

func PingPeriod

func PingPeriod(pingPeriod time.Duration) func(*wsConnection)

PingPeriod sets the duration for sending websocket pings. It should only be used in the constructor - not Goroutine-safe.

func PreChecksHandler

func PreChecksHandler(next http.Handler, config *Config) http.Handler

PreChecksHandler is a middleware function that checks the size of batch requests and returns an error if it exceeds the maximum configured size. It also checks if the request body is not greater than the configured maximum request body bytes limit.

func ReadLimit

func ReadLimit(readLimit int64) func(*wsConnection)

ReadLimit sets the maximum size for reading message. It should only be used in the constructor - not Goroutine-safe.

func ReadWait

func ReadWait(readWait time.Duration) func(*wsConnection)

ReadWait sets the amount of time to wait before a websocket read times out. It should only be used in the constructor - not Goroutine-safe.

func RecoverAndLogHandler

func RecoverAndLogHandler(handler http.Handler, logger log.Logger) http.Handler

RecoverAndLogHandler wraps an HTTP handler, adding error logging. If the inner function panics, the outer function recovers, logs, sends an HTTP 500 error response.

func RegisterRPCFuncs

func RegisterRPCFuncs(mux *http.ServeMux, funcMap map[string]*RPCFunc, logger log.Logger)

RegisterRPCFuncs adds a route for each function in the funcMap, as well as general jsonrpc and websocket handlers for all functions. "result" is the interface on which the result objects are registered, and is popualted with every RPCResponse.

func Serve

func Serve(listener net.Listener, handler http.Handler, logger log.Logger, config *Config) error

Serve creates a http.Server and calls Serve with the given listener. It wraps handler with RecoverAndLogHandler and a handler, which limits the max body size to config.MaxBodyBytes.

NOTE: This function blocks - you may want to call it in a go-routine.

func ServeTLS

func ServeTLS(
	listener net.Listener,
	handler http.Handler,
	certFile, keyFile string,
	logger log.Logger,
	config *Config,
) error

ServeTLS creates a http.Server and calls ServeTLS with the given listener, certFile and keyFile. It wraps handler with RecoverAndLogHandler and a handler, which limits the max body size to config.MaxBodyBytes.

NOTE: This function blocks - you may want to call it in a go-routine.

func WriteCacheableRPCResponseHTTP

func WriteCacheableRPCResponseHTTP(w http.ResponseWriter, res ...types.RPCResponse) error

WriteCacheableRPCResponseHTTP marshals res as JSON (with indent) and writes it to w. Adds Cache-Control to the response header and sets the expiry to one day.

func WriteChanCapacity

func WriteChanCapacity(cap int) func(*wsConnection)

WriteChanCapacity sets the capacity of the websocket write channel. It should only be used in the constructor - not Goroutine-safe.

func WriteRPCResponseHTTP

func WriteRPCResponseHTTP(w http.ResponseWriter, res ...types.RPCResponse) error

WriteRPCResponseHTTP marshals res as JSON (with indent) and writes it to w.

func WriteRPCResponseHTTPError

func WriteRPCResponseHTTPError(
	w http.ResponseWriter,
	httpCode int,
	res types.RPCResponse,
) error

WriteRPCResponseHTTPError marshals res as JSON (with indent) and writes it to w.

source: https://www.jsonrpc.org/historical/json-rpc-over-http.html

func WriteWait

func WriteWait(writeWait time.Duration) func(*wsConnection)

WriteWait sets the amount of time to wait before a websocket write times out. It should only be used in the constructor - not Goroutine-safe.

Types

type Config

type Config struct {
	// see netutil.LimitListener
	MaxOpenConnections int
	// mirrors http.Server#ReadTimeout
	ReadTimeout time.Duration
	// mirrors http.Server#WriteTimeout
	WriteTimeout time.Duration
	// MaxBodyBytes controls the maximum number of bytes the
	// server will read parsing the request body.
	MaxBodyBytes int64
	// mirrors http.Server#MaxHeaderBytes
	MaxHeaderBytes int
	// maximum number of requests in a batch request
	MaxRequestBatchSize int
}

Config is a RPC server configuration.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns a default configuration.

type Option

type Option func(*RPCFunc)

func Cacheable

func Cacheable(noCacheDefArgs ...string) Option

Cacheable enables returning a cache control header from RPC functions to which it is applied.

`noCacheDefArgs` is a list of argument names that, if omitted or set to their defaults when calling the RPC function, will skip the response caching.

func Ws

func Ws() Option

Ws enables WebSocket communication.

type RPCFunc

type RPCFunc struct {
	// contains filtered or unexported fields
}

RPCFunc contains the introspected type information for a function.

func NewRPCFunc

func NewRPCFunc(f any, args string, options ...Option) *RPCFunc

NewRPCFunc wraps a function for introspection. f is the function, args are comma separated argument names.

func NewWSRPCFunc

func NewWSRPCFunc(f any, args string, options ...Option) *RPCFunc

NewWSRPCFunc wraps a function for introspection and use in the websockets.

type WebsocketManager

type WebsocketManager struct {
	websocket.Upgrader
	// contains filtered or unexported fields
}

WebsocketManager provides a WS handler for incoming connections and passes a map of functions along with any additional params to new connections. NOTE: The websocket path is defined externally, e.g. in node/node.go.

func NewWebsocketManager

func NewWebsocketManager(
	funcMap map[string]*RPCFunc,
	wsConnOptions ...func(*wsConnection),
) *WebsocketManager

NewWebsocketManager returns a new WebsocketManager that passes a map of functions, connection options and logger to new WS connections.

func (*WebsocketManager) SetLogger

func (wm *WebsocketManager) SetLogger(l log.Logger)

SetLogger sets the logger.

func (*WebsocketManager) WebsocketHandler

func (wm *WebsocketManager) WebsocketHandler(w http.ResponseWriter, r *http.Request)

WebsocketHandler upgrades the request/response (via http.Hijack) and starts the wsConnection.