zenrpc: JSON-RPC 2.0 Server with OpenRPC support

zenrpc is a JSON-RPC 2.0 server library with Service Mapping Description or OpenRPC support. It's built on top of go generate instead of reflection.

Zenrpc Ecosystem

• SMDBox – Swagger-like JSON RPC API browser, compatible with smd scheme, generated by zenrpc.
• zenrpc middlewares collection
• brokersrv for using NATS as transport
• rpcgen – library for generating Go/TypeScript/PHP RPC clients and OpenRPC schema support
• rpcdiff – diff generator between old and new OpenRPC schemas.

How to Use

Service is struct with RPC methods, service represents RPC namespace.

1. Install zenrpc generator: go install github.com/vmkteam/zenrpc/v2/zenrpc@latest
2. Import github.com/vmkteam/zenrpc/v2 into our code with rpc service.
3. Add trailing comment //zenrpc to your service or embed zenrpc.Service into your service struct.
4. Write your funcs almost as usual.
5. Do not forget run go generate or zenrpc for magic

Accepted Method Signatures

func(Service) Method([args]) (<value>, <error>)
func(Service) Method([args]) <value>
func(Service) Method([args]) <error>
func(Service) Method([args])

• Value could be a pointer
• Error is error or *zenrpc.Error

Example

package main
import (
"context""errors""flag""log""math""net/http""os""github.com/vmkteam/zenrpc/v2""github.com/vmkteam/zenrpc/v2/testdata"
)
typeArithServicestruct{ zenrpc.Service }
// Sum sums two digits and returns error with error code as result and IP from context.func (asArithService) Sum(ctx context.Context, a, bint) (bool, *zenrpc.Error) {
r, _:=zenrpc.RequestFromContext(ctx)
returntrue, zenrpc.NewStringError(a+b, r.Host)
}
// Multiply multiples two digits and returns result.func (asArithService) Multiply(a, bint) int {
returna*b
}
typeQuotientstruct {
Quo, Remint
}
func (asArithService) Divide(a, bint) (quo*Quotient, errerror) {
ifb==0 {
returnnil, errors.New("divide by zero")
} elseifb==1 {
returnnil, zenrpc.NewError(401, errors.New("we do not serve 1"))
}
return&Quotient{
Quo: a/b,
Rem: a%b,
}, nil
}
// Pow returns x**y, the base-x exponential of y. If Exp is not set then default value is 2.////zenrpc:exp=2func (asArithService) Pow(basefloat64, expfloat64) float64 {
returnmath.Pow(base, exp)
}
//go:generate zenrpcfuncmain() {
addr:=flag.String("addr", "localhost:9999", "listen address")
flag.Parse()
rpc:=zenrpc.NewServer(zenrpc.Options{ExposeSMD: true})
rpc.Register("arith", testdata.ArithService{})
rpc.Register("", testdata.ArithService{}) // publicrpc.Use(zenrpc.Logger(log.New(os.Stderr, "", log.LstdFlags)))
http.Handle("/", rpc)
log.Printf("starting arithsrv on %s", *addr)
log.Fatal(http.ListenAndServe(*addr, nil))
}

Magic comments

All comments are optional.

// Method comments
//
//zenrpc:<method parameter>[=<default value>][whitespaces<description>]
//zenrpc:<error code>[whitespaces<description>]
//zenrpc:return[whitespaces<description>]
Struct comments
type MyService struct {} //zenrpc

JSON-RPC 2.0 Supported Features

• Requests
  • Single requests
  • Batch requests
  • Notifications
• Parameters
  • Named
  • Position
  • Default values
• SMD Schema
  • Input
  • Output
  • Codes
  • Scopes for OAuth

Server Library Features

• go generate
• Transports
  • HTTP
  • WebSocket
  • NATS via brokersrv
• Server middleware
  • Basic support
  • Metrics
  • Logging