README
¶
jrpc2
JSON-RPC 2.0 client & server over WebSockets.
Features:
- Method calls, notifications, & errors
- Offers ServeHTTP for your net/http server
- Support for reverse RPC calls
- Can wrap existing
net.Connwith NewSession - Single dependency (coder/websocket)
- Does not hijack your logs
Not implemented (and probably never will):
- Batch requests
Basic usage
// Types
type AddRequest struct {
A, B int
}
type SqrRequest struct {
X int
}
type Result struct {
Value int
}
// Server
mux := jrpc2.NewMux()
mux.RegisterFunc("calc.add", func(ctx context.Context, p *AddRequest) (*Result, error) {
return &Result{Value: p.A + p.B}, nil
})
mux.RegisterFunc("calc.sqr", func(ctx context.Context, p *SqrRequest) (*Result, error) {
return &Result{Value: p.X * p.X}, nil
})
rpcServer := jrpc2.NewServer(&ServerConfig{
SessionConfig: &SessionConfig{
Handler: mux,
},
})
server := http.Server{
Addr: "0.0.0.0:1337",
Handler: rpcServer,
}
server.ListenAndServe()
// Client
client, err := jrpc2.DialRetry(ctx, "ws://127.0.0.1:1337", &ClientConfig{
// Client can also expose methods that may be called by server (reverse RPC calls).
// SessionConfig: &SessionConfig{
// Handler: mux,
// },
})
if err != nil {
t.Fatal(err)
}
res := &Result{}
err := client.Call(ctx, "calc.add", AddRequest{A: 3, B: 4}, &res)
// Or, with generics:
// res, err := jrpc2.Call[*Result](ctx, client, "calc.add", AddRequest{A: 3, B: 4})
fmt.Println(res.Value) // 7
Reverse RPC calls
Instance of jrpc2.Session can be retrieved from context at any time within server and client methods:
func SomeMethod(ctx context.Context, p *SomeRequest) *Result, error) {
// Obtain jrpc2 session
session := jrpc2.SessionFromContext(ctx)
// Call caller's method
session.Call(ctx, "foo.bar", Params{}, nil)
}
Documentation
¶
Index ¶
- func Call[T any](ctx context.Context, session *Session, name string, param any) (T, error)
- func MethodNameFromContext(ctx context.Context) string
- func WithTraceParent(ctx context.Context, tp TraceParent) context.Context
- type Callable
- type ClientConfig
- type Error
- type ErrorCode
- type Handler
- type HandlerFunc
- type Message
- type Mux
- type Server
- type ServerConfig
- type Session
- func Dial(ctx context.Context, url string, config *ClientConfig) (*Session, error)
- func DialRetry(ctx context.Context, url string, config *ClientConfig) (*Session, error)
- func NewSession(parentCtx context.Context, conn io.ReadWriteCloser, config *SessionConfig) *Session
- func SessionFromContext(ctx context.Context) *Session
- func (s *Session) Call(ctx context.Context, name string, param any, res any) error
- func (s *Session) Close() error
- func (s *Session) Conn() io.ReadWriteCloser
- func (s *Session) Notify(ctx context.Context, name string, param any) error
- func (s *Session) Run(parentCtx context.Context)
- func (s *Session) SetArrayParams(v bool)
- func (s *Session) Subscribe(name string, h Handler) func()
- func (s *Session) SubscribeFunc(name string, fn any) func()
- func (s *Session) Wait() error
- type SessionConfig
- type TraceParent
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Call ¶
Call remote JSON-RPC 2.0 method and return result based on type parameter instead of unmarshaling result into provided arg.
func MethodNameFromContext ¶
Obtain name of method/notification that is currently being handled.
func WithTraceParent ¶
func WithTraceParent(ctx context.Context, tp TraceParent) context.Context
Attach new TraceParent to this context. See https://www.w3.org/TR/trace-context/
Types ¶
type Callable ¶
type Callable struct {
// contains filtered or unexported fields
}
Callable holds a function along with its argument & return types. Reflection is used to infer those types.
type ClientConfig ¶
type ClientConfig struct {
Transport http.RoundTripper
Header http.Header
*SessionConfig
}
type Error ¶
type Handler ¶
type Handler interface {
ServeRPC(ctx context.Context, session *Session, req Message) (res Message)
}
Handler defines anything that can handle RPC requests within a session context. Handler is usually a Mux or a Func.
func NewMethod ¶
NewMethod creates Func from a function to be used for inbound method calls. fn must have signature func(context.Context, *reqType) (*resType, error) or I will panic.
func NewSubscription ¶
NewSubscription creates Func from a function to be used for inbound notifications. fn must have signature func(context.Context, *reqType) error or I will panic.
type HandlerFunc ¶
type Message ¶
type Message struct {
JSONRPC string `json:"jsonrpc"`
ID *json.RawMessage `json:"id,omitempty"`
Method string `json:"method,omitempty"`
Params json.RawMessage `json:"params,omitempty"`
Result json.RawMessage `json:"result,omitempty"`
Error *Error `json:"error,omitempty"`
TraceParent *TraceParent `json:"traceparent,omitempty"`
}
func NewErrorMessage ¶
type Mux ¶
type Mux struct {
// contains filtered or unexported fields
}
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
TODO: - CheckOrigin - Handle panics in ServeHTTP (close conns, etc)
func NewServer ¶
func NewServer(config *ServerConfig) *Server
NewSession creates a JSON-RPC 2.0 server and exposes methods (if provided).
type ServerConfig ¶
type ServerConfig struct {
*SessionConfig
}
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session represents active JSON-RPC 2.0 session. It is used for by both client and server.
func DialRetry ¶
DialRetry calls Dial with retries. It tries to connect indefinitely and returns error only if context is canceled.
func NewSession ¶
func NewSession(parentCtx context.Context, conn io.ReadWriteCloser, config *SessionConfig) *Session
NewSession creates a JSON-RPC 2.0 session for connection and exposes methods (if provided).
func SessionFromContext ¶
Obtain RPC session from context when used on context within RPC handler. Use to perform reverse RPC calls.
func (*Session) Call ¶
Call remote JSON-RPC 2.0 method. If res is nil, result is discarded.
If context has no TraceParent, new TraceParent is created.
func (*Session) Conn ¶
func (s *Session) Conn() io.ReadWriteCloser
Conn returns the underlying io.ReadWriteCloser (which is likely a net.Conn from http.Serve)
func (*Session) SetArrayParams ¶
SetArrayParams forces params to be sent as an array (of 1 object) instead of a single object. Default is true.
func (*Session) Subscribe ¶
Subscribe to JSON-RPC 2.0 notifications. h must have type func(context.Context, *notifType) (any, error). First return (any) from fn is ignored and is present for consistency with normal methods. Returns unsubscribe function that must be called when caller is no longer interested in notifications.
func (*Session) SubscribeFunc ¶
type SessionConfig ¶
type TraceParent ¶
func NewTraceParent ¶
func NewTraceParent() TraceParent
func TraceParentFromContext ¶
func TraceParentFromContext(ctx context.Context) (TraceParent, bool)
Retrieve TraceParent from this context.
func (TraceParent) ChildSpan ¶
func (tp TraceParent) ChildSpan() TraceParent
func (TraceParent) MarshalText ¶
func (tp TraceParent) MarshalText() ([]byte, error)
func (TraceParent) String ¶
func (tp TraceParent) String() string
func (TraceParent) TraceID ¶
func (tp TraceParent) TraceID() string
func (*TraceParent) UnmarshalText ¶
func (tp *TraceParent) UnmarshalText(text []byte) error
Source Files