jrpc

README

jrpc

go get gfx.cafe/open/jrpc

this is a bottom up implementation of jsonrpc2, primarily made for hosting eth-like jsonrpc requests.

we extend the eth-rpc reflect based handler with go-http style request/response.

we also make things like subscriptions additional extensions, so they are no longer baked into the rpc package.

most users should mostly access the jrpc packages, along with a variety of things in contrib

see examples in examples folder for usage

it is currently being used in the oku.trade api in proxy, client, and server applications.

features

• full jsonrpc2 protocol
• batch requests + notifications
• http.Request/http.ResponseWriter style semantics
• simple but powerful middleware framework
• subscription framework used by go-ethereum/rpc is implemented as middleware.
• http (with rest-like access via RPC verb), websocket, io.Reader/io.Writer (tcp, any net.Conn, etc), inproc codecs.
• using faster json packages (jsoniter, jx)
• extensions, which allow setting arbitrary fields on the parent object, like in sourcegraph jsonrpc2
• jmux, which allows for http-like routing, implemented like go-chi/v5, except for jsonrpc2 paths
• argreflect, which allows mounting methods on structs to the rpc engine, like go-ethereum/rpc
• allows for streaming over eventsource - means subscriptions without websockets

batch requests

batch requests are very weird. the jsonrpc spec indicates that all batch responses must be returned at the same time, this means for maximum throughput, the user should never use batch requests.

browsers should prefer to use websocket, as it is far more performance than HTTP with batching. websocket frame sizes can also make things such as latency just as good as batching

batch requests are evaulated in a single threaded manner, the next request in the batch blocking until "Send" has been called on the handler.

as a result, batch requests are not very useful.

so to jrpc, we added a new "feature", which is that batch requests are executed sequentially (however in different goroutines).

this is a feature that jsonrpc2 does not have, for jsonrpc2 allows any amount of concurrency and evaluation order for batch requests.

maybe outdated but somewhat useful contribution info

basic structure

exports.go       - export things in subpackages to jrpc namespace, cleaning up the public use package.
pkg/             - packages for implementing jrpc
  clientutil/      - common utilities for client implementations to use
    idreply.go       - generalizes making a request with an incrementing id, then waiting on it
    helper.go        - helpers for decoding messages, etc
  jsonrpc/           - jsonrpc related things. to implement new codecs, use this package
    errors.go        - jsonrpc2 error codes and marshaling
    json.go          - jsonrpc2 json rules, encoding, decoding
    peer.go          - peerinfo
    transport.go     - define ReaderWriter interface
    wire.go          - jsonrpc2 wire protocol marshaling, like ID and Version
    jrpc.go          - define the Handler, HandlerFunc, and ResponseWriter
    reqresp.go       - define Request, Response, along with json marshaling for the request
  server/            - server implementation
    server.go        - a simple server implementation that uses a codec.ReaderWriter
  jrpctest/        - utilities for testing client and server.
    suite.go         - implementors of client and server should pass this
contrib/         - packages that add to jrpc
  codecs/          - client and server transport implementations
    codecs.go        - dialers for all finished codecs
    http/              - http based codec
      codec_test.go      - general tests that all must pass
      client.go          - codec.Conn implementation
      codec.go           - codec.ReaderWriter implementaiton
      const.go           - constants
      handler.go         - http handler
      http_test.go       - http specific tests
    websocket/         - websocket basec codec
      codec_test.go      - general tests that all must pass
      client.go          - codec.Conn implementation
      codec.go           - codec.ReadWriter implementation
      const.go           - constants
      dial.go            - websocket dialer
      handler.go         - http handler
      websocket_test.go  - websocket specific tests
    rdwr/              - rdwr based codec. can be used to implement other codecs
    inproc/            - inproc based codec
  openrpc/         - openapi specification implementation
  jmux/            - a chi based router which satisfies the jrpc.Handler interface
  handlers/        - special jrpc handlers
    argreflect/      - go-ethereum style struct reflection
  middleware/      - pre implemented middleware
  extension/       - extensions to the protocol
    subscription/    - subscription engine for go-ethereum style subs

Documentation

Overview

Package jrpc implements a jsonrpc2 server

Index

• Variables
• func Call[T any](ctx context.Context, c Conn, method string, args ...any) (*T, error)
• func Do[T any](ctx context.Context, c Conn, method string, args any) (*T, error)
• type Conn
• type Handler
• type HandlerFunc
• type Middleware
• type Request
• type ResponseWriter

Variables

var (

	// DialContext is to dial a conn with context
	DialContext = codecs.DialContext
	// Dial is to dial a conn with context.Background()
	Dial = codecs.Dial

	// ContextWithConn will attach a conn to the context
	ContextWithConn = jsonrpc.ContextWithConn
	// ContextWithPeerInfo will attach a peerinfo to the context
	ContextWithPeerInfo = server.ContextWithPeerInfo

	// ConnFromContext will retrieve a conn from context
	ConnFromContext = jsonrpc.ConnFromContext
	// PeerInfoFromContext will retrieve a peerinfo from context
	PeerInfoFromContext = server.PeerInfoFromContext
)

var CallInto = jsonrpc.CallInto

CallInto is the same as Call, except instead of returning, you provide a pointer to the result

Functions

func Call

func Call[T any](ctx context.Context, c Conn, method string, args ...any) (*T, error)

Call will use the conn to perform a jsonrpc2 call, except the args will be encoded as an array of arguments.

func Do

func Do[T any](ctx context.Context, c Conn, method string, args any) (*T, error)

Do will use the conn to perform a jsonrpc2 call.

Types

type Conn

type Conn = jsonrpc.Conn

Conn is used to make requests to jsonrpc2 servers

type Handler

type Handler = jsonrpc.Handler

Handler is the equivalent of http.Handler, but for jsonrpc.

type HandlerFunc

type HandlerFunc = jsonrpc.HandlerFunc

HandlerFunc is a Handler that exists as a function

type Middleware

type Middleware = func(Handler) Handler

Server is a jrpc server Middleware is a middleware

type Request

type Request = jsonrpc.Request

Request is the request object

type ResponseWriter

type ResponseWriter = jsonrpc.ResponseWriter

ResponseWriter is used to write responses to the request