jmux

Documentation

Index

• Variables
• func MethodParam(r *jsonrpc.Request, key string) string
• func MethodParamFromCtx(ctx context.Context, key string) string
• func NotFound(w jsonrpc.ResponseWriter, r *jsonrpc.Request)
• func Walk(r Routes, walkFn WalkFunc) error
• type ChainHandler
• type Context
  • func NewRouteContext() *Context
  • func RouteContext(ctx context.Context) *Context
  • func (x *Context) MethodParam(key string) string
  • func (x *Context) Reset()
  • func (x *Context) RoutePattern() string
• type Middlewares
• type Mux
  • func NewMux() *Mux
  • func NewRouter() *Mux
  • func (mx *Mux) Group(fn func(r Router)) Router
  • func (mx *Mux) Handle(pattern string, handler jsonrpc.Handler)
  • func (mx *Mux) HandleFunc(pattern string, handlerFn jsonrpc.HandlerFunc)
  • func (mx *Mux) Match(rctx *Context, path string) bool
  • func (mx *Mux) MethodNotAllowed(handlerFn jsonrpc.HandlerFunc)
  • func (mx *Mux) MethodNotAllowedHandler() jsonrpc.HandlerFunc
  • func (mx *Mux) Middlewares() Middlewares
  • func (mx *Mux) Mount(pattern string, handler jsonrpc.Handler)
  • func (mx *Mux) NotFound(handlerFn jsonrpc.HandlerFunc)
  • func (mx *Mux) NotFoundHandler() jsonrpc.HandlerFunc
  • func (m *Mux) RegisterFunc(name string, rcvr any) error
  • func (m *Mux) RegisterStruct(name string, rcvr any) error
  • func (mx *Mux) Route(pattern string, fn func(r Router)) Router
  • func (mx *Mux) Routes() []Route
  • func (mx *Mux) ServeRPC(w jsonrpc.ResponseWriter, r *jsonrpc.Request)
  • func (mx *Mux) Use(middlewares ...func(jsonrpc.Handler) jsonrpc.Handler)
  • func (mx *Mux) With(middlewares ...func(jsonrpc.Handler) jsonrpc.Handler) Router
• type Route
• type RouteParams
  • func (s *RouteParams) Add(key, value string)
• type Router
• type Routes
• type StructReflector
• type WalkFunc

Variables

var Chain = jsonrpc.Chain

Chain returns a Middlewares type from a slice of middleware handlers.

var (
	// RouteCtxKey is the context.Context key to store the request context.
	RouteCtxKey = &contextKey{"RouteContext"}
)

Functions

func MethodParam

func MethodParam(r *jsonrpc.Request, key string) string

MethodParam returns the url parameter from a Request object.

func MethodParamFromCtx

func MethodParamFromCtx(ctx context.Context, key string) string

MethodParamFromCtx returns the url parameter from a Request Context.

func NotFound

func NotFound(w jsonrpc.ResponseWriter, r *jsonrpc.Request)

func Walk

func Walk(r Routes, walkFn WalkFunc) error

Walk walks any router tree that implements Routes interface.

Types

type ChainHandler

type ChainHandler = jsonrpc.ChainHandler

ChainHandler is a Handler with support for handler composition and execution.

type Context

type Context struct {
	Routes Routes

	// Routing path/method override used during the route search.
	// See Mux#routemethod.
	RoutePath   string
	RouteMethod string

	// MethodParams are the stack of routeParams captured during the
	// routing lifecycle across a stack of sub-routers.
	MethodParams RouteParams

	// Routing pattern stack throughout the lifecycle of the request,
	// across all connected routers. It is a record of all matching
	// patterns across a stack of sub-routers.
	RoutePatterns []string
	// contains filtered or unexported fields
}

Context is the default routing context set on the root node of a request context to track route patterns, Method parameters and an optional routing path.

func NewRouteContext

func NewRouteContext() *Context

NewRouteContext returns a new routing Context object.

func RouteContext

func RouteContext(ctx context.Context) *Context

RouteContext returns chi's routing Context object from a Request Context.

func (*Context) MethodParam

func (x *Context) MethodParam(key string) string

MethodParam returns the corresponding Method parameter value from the request routing context.

func (*Context) Reset

func (x *Context) Reset()

Reset a routing context to its initial state.

func (*Context) RoutePattern

func (x *Context) RoutePattern() string

RoutePattern builds the routing pattern string for the particular request, at the particular point during routing. This means, the value will change throughout the execution of a request in a router. That is why its advised to only use this value after calling the next handler.

For example,

func Instrument(next Handler) Handler {
  return HandlerFunc(func(w ResponseWriter, r *Request) {
    next.Servew, r)
    routePattern := chi.RouteContext(r.Context()).RoutePattern()
    measure(w, r, routePattern)
	 })
}

type Middlewares

type Middlewares = jsonrpc.Middlewares

Middlewares type is a slice of standard middleware handlers with methods to compose middleware chains and Handler's.

type Mux

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

Mux is a simple JRPC route multiplexer that parses a request path, records any URL params, and executes an end handler. It implements the Handler interface and is friendly with the standard library.

Mux is designed to be fast, minimal and offer a powerful API for building modular and composable JRPC services with a large set of handlers. It's particularly useful for writing large REST API services that break a handler into many smaller parts composed of middlewares and end handlers.

func NewMux

func NewMux() *Mux

NewMux returns a newly initialized Mux object that implements the Router interface.

func NewRouter

func NewRouter() *Mux

NewRouter returns a new Mux object that implements the Router interface.

func (*Mux) Group

func (mx *Mux) Group(fn func(r Router)) Router

Group creates a new inline-Mux with a fresh middleware stack. It's useful for a group of handlers along the same routing path that use an additional set of middlewares. See _examples/.

func (*Mux) Handle

func (mx *Mux) Handle(pattern string, handler jsonrpc.Handler)

Handle adds the route `pattern` that matches any jrpc method to execute the `handler` Handler.

func (*Mux) HandleFunc

func (mx *Mux) HandleFunc(pattern string, handlerFn jsonrpc.HandlerFunc)

HandleFunc adds the route `pattern` that matches any jrpc method to execute the `handlerFn` HandlerFunc.

func (*Mux) Match

func (mx *Mux) Match(rctx *Context, path string) bool

Match searches the routing tree for a handler that matches the method/path. It's similar to routing a jrpc request, but without executing the handler thereafter.

Note: the *Context state is updated during execution, so manage the state carefully or make a NewRouteContext().

func (*Mux) MethodNotAllowed

func (mx *Mux) MethodNotAllowed(handlerFn jsonrpc.HandlerFunc)

MethodNotAllowed sets a custom HandlerFunc for routing paths where the method is unresolved. The default handler returns a 405 with an empty body.

func (*Mux) MethodNotAllowedHandler

func (mx *Mux) MethodNotAllowedHandler() jsonrpc.HandlerFunc

MethodNotAllowedHandler returns the default Mux 405 responder whenever a method cannot be resolved for a route.

func (*Mux) Middlewares

func (mx *Mux) Middlewares() Middlewares

Middlewares returns a slice of middleware handler functions.

func (*Mux) Mount

func (mx *Mux) Mount(pattern string, handler jsonrpc.Handler)

Mount attaches another Handler or chi Router as a subrouter along a routing path. It's very useful to split up a large API as many independent routers and compose them as a single service using Mount. See _examples/.

Note that Mount() simply sets a wildcard along the `pattern` that will continue routing at the `handler`, which in most cases is another chi.Router. As a result, if you define two Mount() routes on the exact same pattern the mount will panic.

func (*Mux) NotFound

func (mx *Mux) NotFound(handlerFn jsonrpc.HandlerFunc)

NotFound sets a custom HandlerFunc for routing paths that could not be found. The default 404 handler is `NotFound`.

func (*Mux) NotFoundHandler

func (mx *Mux) NotFoundHandler() jsonrpc.HandlerFunc

NotFoundHandler returns the default Mux 404 responder whenever a route cannot be found.

func (*Mux) RegisterFunc

func (m *Mux) RegisterFunc(name string, rcvr any) error

func (*Mux) RegisterStruct

func (m *Mux) RegisterStruct(name string, rcvr any) error

func (*Mux) Route

func (mx *Mux) Route(pattern string, fn func(r Router)) Router

Route creates a new Mux with a fresh middleware stack and mounts it along the `pattern` as a subrouter. Effectively, this is a short-hand call to Mount. See _examples/.

func (*Mux) Routes

func (mx *Mux) Routes() []Route

Routes returns a slice of routing information from the tree, useful for traversing available routes of a router.

func (*Mux) ServeRPC

func (mx *Mux) ServeRPC(w jsonrpc.ResponseWriter, r *jsonrpc.Request)

ServeRPC is the single method of the Handler interface that makes Mux interoperable with the standard library. It uses a sync.Pool to get and reuse routing contexts for each request.

func (*Mux) Use

func (mx *Mux) Use(middlewares ...func(jsonrpc.Handler) jsonrpc.Handler)

Use appends a middleware handler to the Mux middleware stack.

The middleware stack for any Mux will execute before searching for a matching route to a specific handler, which provides opportunity to respond early, change the course of the request execution, or set request-scoped values for the next Handler.

func (*Mux) With

func (mx *Mux) With(middlewares ...func(jsonrpc.Handler) jsonrpc.Handler) Router

With adds inline middlewares for an endpoint handler.

type Route

type Route struct {
	SubRoutes Routes
	Handler   jsonrpc.Handler
	Pattern   string
}

Route describes the details of a routing handler.

type RouteParams

type RouteParams struct {
	Keys, Values []string
}

RouteParams is a structure to track Method routing parameters efficiently.

func (*RouteParams) Add

func (s *RouteParams) Add(key, value string)

Add will append a Method parameter to the end of the route param

type Router

type Router interface {
	jsonrpc.Handler
	Routes
	StructReflector

	// Use appends one or more middlewares onto the Router stack.
	Use(middlewares ...func(jsonrpc.Handler) jsonrpc.Handler)

	// With adds inline middlewares for an endpoint handler.
	With(middlewares ...func(jsonrpc.Handler) jsonrpc.Handler) Router

	// Group adds a new inline-Router along the current routing
	// path, with a fresh middleware stack for the inline-Router.
	Group(fn func(r Router)) Router

	// Route mounts a sub-Router along a `pattern“ string.
	Route(pattern string, fn func(r Router)) Router

	// Mount attaches another Handler along ./pattern/*
	Mount(pattern string, h jsonrpc.Handler)

	// Handle and HandleFunc adds routes for `pattern` that matches
	// all HTTP methods.
	Handle(pattern string, h jsonrpc.Handler)
	HandleFunc(pattern string, h jsonrpc.HandlerFunc)

	// NotFound defines a handler to respond whenever a route could
	// not be found.
	NotFound(h jsonrpc.HandlerFunc)
}

Router consisting of the core routing methods used by chi's Mux, adapted to fit json-rpc.

type Routes

type Routes interface {
	// Routes returns the routing tree in an easily traversable structure.
	Routes() []Route

	// Middlewares returns the list of middlewares in use by the router.
	Middlewares() Middlewares

	// Match searches the routing tree for a handler that matches
	// the method/path - similar to routing a http request, but without
	// executing the handler thereafter.
	Match(rctx *Context, path string) bool
}

Routes interface adds two methods for router traversal, which is also used by the `docgen` subpackage to generation documentation for Routers.

type StructReflector

type StructReflector interface {
	// mimics the behavior of the handlers in the go-ethereum rpc package
	// if you don't know how to use this, just use the chi-like interface instead.
	RegisterStruct(pattern string, rcvr any) error
	// mimics the behavior of the handlers in the go-ethereum rpc package
	// if you don't know how to use this, just use the chi-like interface instead.
	RegisterFunc(pattern string, rcvr any) error
}

type WalkFunc

type WalkFunc func(route string, handler jsonrpc.Handler, middlewares ...func(jsonrpc.Handler) jsonrpc.Handler) error

WalkFunc is the type of the function called for each method and route visited by Walk.