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 (goccy/go-json and 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
• openrpc schema parser and code generator

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
  codec/           - codec 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/    - WIP: 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 BatchElem
• type Conn
• type Handler
• type HandlerFunc
• type Middleware
• type Request
• type ResponseWriter
• type Server
• type StreamingConn

Variables

var (

	// NewServer creates a jrpc server
	NewServer = server.NewServer

	// 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 = codec.ContextWithConn
	// ContextWithPeerInfo will attach a peerinfo to the context
	ContextWithPeerInfo = server.ContextWithPeerInfo

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

var CallInto = codec.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 BatchElem

type BatchElem = codec.BatchElem

BatchElem is an element of a batch request

type Conn

type Conn = codec.Conn

Conn is used to make requests to jsonrpc2 servers

type Handler

type Handler = codec.Handler

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

type HandlerFunc

type HandlerFunc = codec.HandlerFunc

HandlerFunc is a Handler that exists as a function

type Middleware

type Middleware = func(Handler) Handler

Middleware is a middleware

type Request

type Request = codec.Request

Request is the request object

type ResponseWriter

type ResponseWriter = codec.ResponseWriter

ResponseWriter is used to write responses to the request

type Server

type Server = server.Server

Server is a jrpc server

type StreamingConn

type StreamingConn = codec.StreamingConn

StreamingConn is a conn that supports streaming methods