fastjsonrpc

README

fastjsonrpc

Fast JSON-RPC 2.0 implementation for fasthttp server.

$ GOMAXPROCS=1 go test -bench=. -benchmem -benchtime 10s
BenchmarkEchoHandler            20473168               584 ns/op               0 B/op          0 allocs/op
BenchmarkSumHandler             16297743               729 ns/op               0 B/op          0 allocs/op
BenchmarkBatchSumHandler         7587087              1569 ns/op               0 B/op          0 allocs/op
BenchmarkErrorHandler           17734203               671 ns/op               0 B/op          0 allocs/op

Install

go get -u github.com/serjvanilla/fastjsonrpc

Example

package main

import (
	"github.com/serjvanilla/fastjsonrpc"
	"github.com/valyala/fasthttp"
)

func main() {
	repo := fastjsonrpc.NewRepository()

	repo.Register("sum", func(ctx *fastjsonrpc.RequestCtx) {
		params := ctx.Params()

		a := params.GetInt("a")
		b := params.GetInt("b")

		ctx.SetResult(ctx.Arena().NewNumberInt(a + b))
	})
	repo.Register("sum_struct", func(ctx *fastjsonrpc.RequestCtx) {
		type (
			sumRequest struct {
				A int `json:"a"`
				B int `json:"b"`
			}
			sumResponse int
		)

		var req sumRequest
		if err := ctx.ParamsUnmarshal(&req); err != nil {
			ctx.SetError(err)
			return
		}

		ctx.SetResult(sumResponse(req.A + req.B))
	})

	_ = fasthttp.ListenAndServe(":8080", repo.RequestHandler())
}

TODO

• Parallel batch processing
• End-to-end benchmarks

Documentation

Overview

Package fastjsonrpc provides fast JSON-RPC 2.0 server for use with fasthttp server.

Example

package main

import (
	"github.com/serjvanilla/fastjsonrpc"
	"github.com/valyala/fasthttp"
)

func main() {
	repo := fastjsonrpc.NewRepository()

	repo.Register("sum", func(ctx *fastjsonrpc.RequestCtx) {
		params := ctx.Params()

		a := params.GetInt("a")
		b := params.GetInt("b")

		ctx.SetResult(ctx.Arena().NewNumberInt(a + b))
	})
	repo.Register("sum_struct", func(ctx *fastjsonrpc.RequestCtx) {
		type (
			sumRequest struct {
				A int `json:"a"`
				B int `json:"b"`
			}
			sumResponse int
		)

		var req sumRequest
		if err := ctx.ParamsUnmarshal(&req); err != nil {
			ctx.SetError(err)
			return
		}

		ctx.SetResult(sumResponse(req.A + req.B))
	})

	_ = fasthttp.ListenAndServe(":8080", repo.RequestHandler())
}

Index

• type Error
  • func ErrInternalError() *Error
  • func ErrInvalidParams() *Error
  • func ErrServerError(code ErrorCode) *Error
  • func (e *Error) Error() string
  • func (e *Error) WithData(data interface{}) *Error
• type ErrorCode
• type Repository
  • func NewRepository() *Repository
  • func (r *Repository) Register(method string, handler RequestHandler)
  • func (r *Repository) RequestHandler() fasthttp.RequestHandler
• type RequestCtx
  • func (ctx *RequestCtx) Arena() *fastjson.Arena
  • func (ctx *RequestCtx) Context() context.Context
  • func (ctx *RequestCtx) ID() []byte
  • func (ctx *RequestCtx) Method() []byte
  • func (ctx *RequestCtx) Params() *fastjson.Value
  • func (ctx *RequestCtx) ParamsBytes() []byte
  • func (ctx *RequestCtx) ParamsUnmarshal(v interface{}) *Error
  • func (ctx *RequestCtx) SetError(err *Error)
  • func (ctx *RequestCtx) SetResult(result interface{})
• type RequestHandler

Examples

• Package
• ErrServerError

Types

type Error

type Error struct {
	Code    ErrorCode
	Message string
	Data    interface{}
}

Error is wrapper for JSON-RPC 2.0 Error Object.

func ErrInternalError

func ErrInternalError() *Error

ErrInternalError returns pre-built JSON-RPC error with code -32603 and message "Internal error".

func ErrInvalidParams

func ErrInvalidParams() *Error

ErrInvalidParams returns pre-built JSON-RPC error with code -32602 and message "Invalid params".

func ErrServerError

func ErrServerError(code ErrorCode) *Error

ErrServerError returns pre-built JSON-RPC error with provided code and message "Server error".

Example

package main

import (
	"github.com/serjvanilla/fastjsonrpc"
)

func main() {
	_ = fastjsonrpc.
		ErrServerError(fastjsonrpc.ErrorCode(-32042)).
		WithData("something went wrong")
}

func (*Error) Error

func (e *Error) Error() string

Error implements standard error interface.

func (*Error) WithData

func (e *Error) WithData(data interface{}) *Error

WithData sets error's data value.

Useful with ErrServerError.

type ErrorCode

type ErrorCode int

ErrorCode is JSON-RPC 2.0 spec defined error code.

For user defined errors it should be in range from -32099 to -32000.

type Repository

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

Repository is a JSON-RPC 2.0 methods repository.

func NewRepository

func NewRepository() *Repository

NewRepository returns empty repository.

It's safe to use Repository default value.

func (*Repository) Register

func (r *Repository) Register(method string, handler RequestHandler)

Register registers new method handler.

func (*Repository) RequestHandler

func (r *Repository) RequestHandler() fasthttp.RequestHandler

RequestHandler is suitable for using with fasthttp.

type RequestCtx

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

RequestCtx contains incoming request and manages outgoing response.

func (*RequestCtx) Arena

func (ctx *RequestCtx) Arena() *fastjson.Arena

Arena returns fastjson.Arena for current request.

RequestHandler should avoid holding references to Arena and/or constructed Values after the return.

func (*RequestCtx) Context

func (ctx *RequestCtx) Context() context.Context

func (*RequestCtx) ID

func (ctx *RequestCtx) ID() []byte

ID returns "id" field of JSON-RPC 2.0 request.

func (*RequestCtx) Method

func (ctx *RequestCtx) Method() []byte

Method returns matched method.

func (*RequestCtx) Params

func (ctx *RequestCtx) Params() *fastjson.Value

Params returns request parameters already unmarshalled with valyala/fastjson.

func (*RequestCtx) ParamsBytes

func (ctx *RequestCtx) ParamsBytes() []byte

ParamsBytes returns raw bytes of request's "params" field.

func (*RequestCtx) ParamsUnmarshal

func (ctx *RequestCtx) ParamsUnmarshal(v interface{}) *Error

ParamsUnmarshal parses request param and stores the result in the value pointed to by v.

func (*RequestCtx) SetError

func (ctx *RequestCtx) SetError(err *Error)

SetError writes JSON-RPC response with error.

It overwrites previous calls of SetResult and SetError.

func (*RequestCtx) SetResult

func (ctx *RequestCtx) SetResult(result interface{})

SetResult writes JSON-RPC response with result.

It overwrites previous calls of SetResult and SetError.

result may be *fastjson.Value, []byte, or interface{} (slower).

type RequestHandler

type RequestHandler func(ctx *RequestCtx)

RequestHandler must process incoming requests.