rpcserver

Documentation

Index

• Constants
• type Handler
• type MethodDef
  • func MakeMethodDef[I, O any](handler Handler[I, O], desc, respDesc string) MethodDef
• type MethodHandler
  • func InspectHandler[I, O any](fn Handler[I, O]) (reflect.Type, reflect.Type, MethodHandler)
  • func MakeMethodHandler[I, O any](fn Handler[I, O]) MethodHandler
• type Metrics
• type Opt
  • func WithCORS() Opt
  • func WithMetricsNamespace(namespace string) Opt
  • func WithPass(pass string) Opt
  • func WithReqSizeLimit(sz int) Opt
  • func WithServerInfo(specInfo *openrpc.Info) Opt
  • func WithTLS(cfg *tls.Config) Opt
  • func WithTimeout(timeout time.Duration) Opt
  • func WithTrustedProxyCount(trustedProxyCount int) Opt
• type Server
  • func NewServer(addr string, log log.Logger, opts ...Opt) (*Server, error)
  • func (s *Server) RegisterMethodHandler(method jsonrpc.Method, h MethodHandler)
  • func (s *Server) RegisterSvc(svc Svc)
  • func (s *Server) Serve(ctx context.Context) error
  • func (s *Server) ServeOn(ctx context.Context, ln net.Listener) error
• type Svc

Constants

const (
	RequestIPCtx contextRPCKey = "clientIP"
)

Types

type Handler

type Handler[I, O any] func(context.Context, *I) (*O, *jsonrpc.Error)

type MethodDef

type MethodDef struct {
	Desc       string
	ParamDescs []string
	RespDesc   string
	Handler    MethodHandler
	ReqType    reflect.Type
	RespType   reflect.Type
}

func MakeMethodDef

func MakeMethodDef[I, O any](handler Handler[I, O], desc, respDesc string) MethodDef

type MethodHandler

type MethodHandler func(ctx context.Context, s *Server) (argsPtr any, handler func() (any, *jsonrpc.Error))

MethodHandler is a type of function that returns an interface containing a pointer to a handler's input arguments, and a handler function that captures the arguments pointer. The handler function returns its result type in an interface, and a *jsonrpc.Error. A simple MethodHandler would instantiate a new concrete instance of the parameters type and define a function that uses that instance to perform some operations.

func InspectHandler

func InspectHandler[I, O any](fn Handler[I, O]) (reflect.Type, reflect.Type, MethodHandler)

func MakeMethodHandler

func MakeMethodHandler[I, O any](fn Handler[I, O]) MethodHandler

type Metrics

type Metrics interface {
	Inc()
}

type Opt

type Opt func(*serverConfig)

func WithCORS

func WithCORS() Opt

WithCORS adds CORS headers to response so browser will permit cross origin RPC requests.

func WithMetricsNamespace

func WithMetricsNamespace(namespace string) Opt

WithMetricsNamespace enables metrics with the provided namespace.

func WithPass

func WithPass(pass string) Opt

WithPass will require a password in the request header's Authorization value in "Basic" formatting. Don't use this without TLS; either terminate TLS in an upstream reverse proxy, or use WithTLS with Certificates provided.

func WithReqSizeLimit

func WithReqSizeLimit(sz int) Opt

WithReqSizeLimit sets the request size limit in bytes.

func WithServerInfo

func WithServerInfo(specInfo *openrpc.Info) Opt

WithServerInfo sets the OpenRPC "info" section to use when serving the OpenRPC JSON specification either via a spec REST endpoint or the rpc.discover JSON-RPC method.

func WithTLS

func WithTLS(cfg *tls.Config) Opt

WithTLS provides a tls.Config to use with tls.NewListener around the standard net.Listener.

func WithTimeout

func WithTimeout(timeout time.Duration) Opt

WithTimeout specifies a timeout on all RPC requests that when exceeded will cancel the request.

func WithTrustedProxyCount

func WithTrustedProxyCount(trustedProxyCount int) Opt

type Server

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

Server is a JSON-RPC server.

func NewServer

func NewServer(addr string, log log.Logger, opts ...Opt) (*Server, error)

NewServer creates a new JSON-RPC server. Use RegisterMethodHandler or RegisterSvc to add method handlers.

func (*Server) RegisterMethodHandler

func (s *Server) RegisterMethodHandler(method jsonrpc.Method, h MethodHandler)

RegisterMethodHandler registers a single MethodHandler. See also RegisterSvc.

func (*Server) RegisterSvc

func (s *Server) RegisterSvc(svc Svc)

RegisterSvc registers every MethodHandler for a service.

The Server's fixed endpoint is used.

func (*Server) Serve

func (s *Server) Serve(ctx context.Context) error

func (*Server) ServeOn

func (s *Server) ServeOn(ctx context.Context, ln net.Listener) error

type Svc

type Svc interface {
	// Name should return a unique name for the RPC service. This is intended
	// for meta endpoints provided by the RPC server, such as health checks.
	Name() string
	Methods() map[jsonrpc.Method]MethodDef
	Health(context.Context) (detail json.RawMessage, happy bool)
}

Svc is a type that enumerates its handler functions by method name. To handle a method, the Server:

1. retrieves the MethodHandler associated with the method
2. calls the MethodHandler to get the args interface and handler function
3. unmarshals the inputs from a json.RawMessage into the args interface
4. calls the handler function, returning the result and error
5. marshal either the result or the Error into a Response