readme.md

## 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

```