erpc

eRPC

eRPC is an efficient, extensible and easy-to-use RPC framework.

Suitable for RPC, Microservice, Peer-to-Peer, IM, Game and other fields.

简体中文

Install

• go vesion ≥ 1.18

• install

GO111MODULE=on go get -u -v -insecure github.com/andeya/erpc/v7

• import

import "github.com/andeya/erpc/v7"

Feature

• Use peer to provide the same API package for the server and client
• Provide multi-layout abstractions such as:
  • peer
  • session/socket
  • router
  • handle/context
  • message
  • protocol
  • codec
  • transfer filter
  • plugin
• Support reboot and shutdown gracefully
• HTTP-compatible message format:
  • Composed of two parts, the Header and the Body
  • Header contains metadata in the same format as HTTP header
  • Body supports for custom codec of Content Type-Like, already implemented:
    • Protobuf
    • Thrift
    • JSON
    • XML
    • Form
    • Plain
  • Support push, call-reply and more message types
• Support custom message protocol, and provide some common implementations:
  • rawproto - Default high performance binary protocol
  • jsonproto - JSON message protocol
  • pbproto - Ptotobuf message protocol
  • thriftproto - Thrift message protocol
  • httproto - HTTP message protocol
• Optimized high performance transport layer
  • Use Non-block socket and I/O multiplexing technology
  • Support setting the size of socket I/O buffer
  • Support setting the size of the reading message (if exceed disconnect it)
  • Support controling the connection file descriptor
• Support a variety of network types:
  • tcp
  • tcp4
  • tcp6
  • unix
  • unixpacket
  • kcp
  • quic
  • other
    • websocket
    • evio
• Provide a rich plug-in point, and already implemented:
  • auth
  • binder
  • heartbeat
  • ignorecase(service method)
  • overloader
  • proxy(for unknown service method)
  • secure
• Powerful and flexible logging system:
  • Detailed log information, support print input and output details
  • Support setting slow operation alarm threshold
  • Support for custom implementation log component
• Client session support automatically redials after disconnection

Benchmark

Self Test

• A server and a client process, running on the same machine

• CPU: Intel Xeon E312xx (Sandy Bridge) 16 cores 2.53GHz

• Memory: 16G

• OS: Linux 2.6.32-696.16.1.el6.centos.plus.x86_64, CentOS 6.4

• Go: 1.9.2

• Message size: 581 bytes

• Message codec: protobuf

• Sent total 1000000 messages

• erpc

client concurrency mean(ms) median(ms) max(ms) min(ms) throughput(TPS) 100 1 0 16 0 75505 500 9 11 97 0 52192 1000 19 24 187 0 50040 2000 39 54 409 0 42551 5000 96 128 1148 0 46367

• erpc/socket

client concurrency mean(ms) median(ms) max(ms) min(ms) throughput(TPS) 100 0 0 14 0 225682 500 2 1 24 0 212630 1000 4 3 51 0 180733 2000 8 6 64 0 183351 5000 21 18 651 0 133886

Comparison Test

EnvironmentThroughputsMean LatencyP99 Latency

More Detail

• Profile torch of erpc/socket

svg file

• Heap torch of erpc/socket

svg file

Example

server.go

…

client.go

…

More Examples

Usage

NOTE:

• It is best to set the packet size when reading: SetReadLimit
• The default packet size limit when reading is 1 GB

Peer(server or client) Demo

// Start a server
var peer1 = erpc.NewPeer(erpc.PeerConfig{
ListenPort: 9090, // for server role
})
peer1.Listen()

...

// Start a client
var peer2 = erpc.NewPeer(erpc.PeerConfig{})
var sess, err = peer2.Dial("127.0.0.1:8080")

Call-Struct API template

type Aaa struct {
    erpc.CallCtx
}
func (x *Aaa) XxZz(arg *<T>) (<T>, *erpc.Status) {
    ...
    return r, nil
}

• register it to root router:

// register the call route
// HTTP mapping: /aaa/xx_zz
// RPC mapping: Aaa.XxZz
peer.RouteCall(new(Aaa))

// or register the call route
// HTTP mapping: /xx_zz
// RPC mapping: XxZz
peer.RouteCallFunc((*Aaa).XxZz)

Service method mapping

• The default mapping(HTTPServiceMethodMapper) of struct(func) name to service methods:

  • AaBb -> /aa_bb
  • ABcXYz -> /abc_xyz
  • Aa__Bb -> /aa_bb
  • aa__bb -> /aa_bb
  • ABC__XYZ -> /abc_xyz
  • Aa_Bb -> /aa/bb
  • aa_bb -> /aa/bb
  • ABC_XYZ -> /abc/xyz

  erpc.SetServiceMethodMapper(erpc.HTTPServiceMethodMapper)
  

• The mapping(RPCServiceMethodMapper) of struct(func) name to service methods:

  • AaBb -> AaBb
  • ABcXYz -> ABcXYz
  • Aa__Bb -> Aa_Bb
  • aa__bb -> aa_bb
  • ABC__XYZ -> ABC_XYZ
  • Aa_Bb -> Aa.Bb
  • aa_bb -> aa.bb
  • ABC_XYZ -> ABC.XYZ

  erpc.SetServiceMethodMapper(erpc.RPCServiceMethodMapper)
  

Call-Function API template

func XxZz(ctx erpc.CallCtx, arg *<T>) (<T>, *erpc.Status) {
    ...
    return r, nil
}

• register it to root router:

// register the call route
// HTTP mapping: /xx_zz
// RPC mapping: XxZz
peer.RouteCallFunc(XxZz)

Push-Struct API template

type Bbb struct {
    erpc.PushCtx
}
func (b *Bbb) YyZz(arg *<T>) *erpc.Status {
    ...
    return nil
}

• register it to root router:

// register the push handler
// HTTP mapping: /bbb/yy_zz
// RPC mapping: Bbb.YyZz
peer.RoutePush(new(Bbb))

// or register the push handler
// HTTP mapping: /yy_zz
// RPC mapping: YyZz
peer.RoutePushFunc((*Bbb).YyZz)

Push-Function API template

// YyZz register the handler
func YyZz(ctx erpc.PushCtx, arg *<T>) *erpc.Status {
    ...
    return nil
}

• register it to root router:

// register the push handler
// HTTP mapping: /yy_zz
// RPC mapping: YyZz
peer.RoutePushFunc(YyZz)

Unknown-Call-Function API template

func XxxUnknownCall (ctx erpc.UnknownCallCtx) (interface{}, *erpc.Status) {
    ...
    return r, nil
}

• register it to root router:

// register the unknown call route: /*
peer.SetUnknownCall(XxxUnknownCall)

Unknown-Push-Function API template

func XxxUnknownPush(ctx erpc.UnknownPushCtx) *erpc.Status {
    ...
    return nil
}

• register it to root router:

// register the unknown push route: /*
peer.SetUnknownPush(XxxUnknownPush)

Plugin Demo

…

Register above handler and plugin

// add router group
group := peer.SubRoute("test")
// register to test group
group.RouteCall(new(Aaa), NewIgnoreCase())
peer.RouteCallFunc(XxZz, NewIgnoreCase())
group.RoutePush(new(Bbb))
peer.RoutePushFunc(YyZz)
peer.SetUnknownCall(XxxUnknownCall)
peer.SetUnknownPush(XxxUnknownPush)

Config

…

Optimize

• SetMessageSizeLimit sets max message size. If maxSize<=0, set it to max uint32.

  func SetMessageSizeLimit(maxMessageSize uint32)
  

• SetSocketKeepAlive sets whether the operating system should send keepalive messages on the connection.

  func SetSocketKeepAlive(keepalive bool)
  

• SetSocketKeepAlivePeriod sets period between keep alives.

  func SetSocketKeepAlivePeriod(d time.Duration)
  

• SetSocketNoDelay controls whether the operating system should delay message transmission in hopes of sending fewer messages (Nagle's algorithm). The default is true (no delay), meaning that data is sent as soon as possible after a Write.

  func SetSocketNoDelay(_noDelay bool)
  

• SetSocketReadBuffer sets the size of the operating system's receive buffer associated with the connection.

  func SetSocketReadBuffer(bytes int)
  

• SetSocketWriteBuffer sets the size of the operating system's transmit buffer associated with the connection.

  func SetSocketWriteBuffer(bytes int)
  

Extensions

Codec

package import description json "github.com/andeya/erpc/v7/codec" JSON codec(erpc own) protobuf "github.com/andeya/erpc/v7/codec" Protobuf codec(erpc own) thrift "github.com/andeya/erpc/v7/codec" Form(url encode) codec(erpc own) xml "github.com/andeya/erpc/v7/codec" Form(url encode) codec(erpc own) plain "github.com/andeya/erpc/v7/codec" Plain text codec(erpc own) form "github.com/andeya/erpc/v7/codec" Form(url encode) codec(erpc own)

Plugin

package import description auth "github.com/andeya/erpc/v7/plugin/auth" An auth plugin for verifying peer at the first time binder "github.com/andeya/erpc/v7/plugin/binder" Parameter Binding Verification for Struct Handler heartbeat "github.com/andeya/erpc/v7/plugin/heartbeat" A generic timing heartbeat plugin proxy "github.com/andeya/erpc/v7/plugin/proxy" A proxy plugin for handling unknown calling or pushing secure "github.com/andeya/erpc/v7/plugin/secure" Encrypting/decrypting the message body overloader "github.com/andeya/erpc/v7/plugin/overloader" A plugin to protect erpc from overload

Protocol

package import description rawproto "github.com/andeya/erpc/v7/proto/rawproto A fast socket communication protocol(erpc default protocol) [jsonproto](https://github.com/andeya/erpc/tree/master/prot