jaguar

README

jaguar

jaguar 是一个可扩展、高效的tcp网络库。

Overview

• Tcp Server
• Tcp Connect
• Request Handle
• Push Handle
• Middleware
• Inversion of Control
• Examples

安装

$ go get -u github.com/8treenet/jaguar

Tcp Server

type TcpServer interface {
    Listen(*Opt)
    Accept(func(*TcpConn, *Middleware))
}

//创建 server
server := jaguar.NewServer()

//创建配置
opt := &jaguar.Opt{
    Addr: "0.0.0.0:9000",       //绑定地址和端口
    PacketMaxLength: 6000,       //收发最大包体字节，超过该字节主动断开连接。
    PacketHeaderLength: 2,       //包头占位长度 1,2,4,8
    IdleCheckFrequency: time.Second * 120, //心跳检测
    ByteOrder: binary.BigEndian //网络字节序
}

// 新连接回调
// conn : 新连接
// middleware : 中间件
server.Accept(func(conn *jaguar.TcpConn, middleware *jaguar.Middleware) {
    //session 是一个自定义的插件
    session := plugins.NewSession()
    //conn 附加插件
    conn.Attach(session)
    //使用自定义的 session.CloseEvent 注册连接关闭事件
    middleware.Closed(session.CloseEvent)
})

//开启监听
server.Listen(opt)

Tcp Connect

type TcpConn interface {
    //附加插件对象，可以通过依赖注入获取 type Test struct {obj object `inject:""`}
    Attach(object interface{})
    //附加插件对象接口形式，可以通过依赖注入获取 type Test struct {obj inteface `inject:"impl"`}
    AttachImpl(impl string, object interface{})
    //关闭连接
    Close()
    //获取远程地址
    RemoteAddr() net.Addr
    //推送 推送处理器
    Push(pushHandle Encode) error
}

Request Handle

// 请求处理器，读写io数据和返回响应，继承该接口可使用。
type ReqHandle interface {
    //读取流数据
    ReadStream(...interface{}) error
    //读取流数据中的字符串
    ReadStreamByString(int, *string) error
    //写入流数据
    WriteStream(...interface{})
    //回执响应
    Respone() error
}

func init() {
    // 注册请求处理器 对应请求数据包的协议id 101
    // 请求处理器chat必须实现 Execute 方法
    jaguar.AddRequest(101, new(chat))
}

//定义一个聊天请求处理器
type chat struct {
    //继承 ReqHandle
    jaguar.ReqHandle `inject:"req_handle"`
    //通过依赖注入获取插件-实体方式
    Session *plugins.Session `inject:""`
    //使用 jaguar.TcpConn 插件, 该插件负责连接相关
    Conn jaguar.TcpConn `inject:"tcp_conn"`
}

// Execute - 必须实现
func (c *chat) Execute() {
    //c.ReadStream()
    //c.WriteStream()
    //c.Respone()
}

Push Handle

// 推送处理器，写io数据，继承该接口可使用。
type PushHandle interface {
    //Write byte stream data
    WriteStream(values ...interface{})
}

// 定义个推送处理器
type chat struct {
    jaguar.PushHandle `inject:"push_handle"`
    //要推送的数据列 三项
    sender            string
    content           string
    row               uint32
}

// ProtocolId - 必须实现
func (c *chat) ProtocolId() uint16 {
    //推送数据包的协议id
    //jaguar.TcpConn 插件会调用 chat.ProtocolId()
    return 300
}

// Encode() - 必须实现
func (c *chat) Encode() {
    //jaguar.TcpConn 插件会调用 chat.Encode()
    c.WriteStream(c.row)
    c.WriteStream(uint8(len(c.sender)), c.sender)
    c.WriteStream(uint16(len(c.content)), c.content)
}

TcpConn.Push(&chat{sender:"lucifer", content:"fuck"})

Middleware

// 拦截器
server.Accept(func(conn jaguar.TcpConn, middleware *jaguar.Middleware) {
    middleware.Closed(f func(){
        // Closed - Close registration for callbacks
    })

    middleware.Recover(f func(e error,s string){
        // Recover - Request a panic in the code
    })

    middleware.Reader(func(id uint16, b *bytes.Buffer) *bytes.Buffer {
        // Reader - Read data
        return b
    })

    middleware.Writer(func(id uint16, b *bytes.Buffer) *bytes.Buffer {
        // Writer - Write data
        return b
    })

    middleware.Request(func(id uint16, reqHandle interface{}) {
        //Request - Callback at request
    })

    middleware.Respone(func(id uint16, reqHandle interface{}) {
        //Respone - Callback when requesting a reply
    })

    middleware.Push(func(uint16, interface{}){
        //Push - Callbacks on push
    })
})

Examples

一个聊天室示例

# 启动示例程序
$ cd jaguar/chat_examples
# 启动server
$ go run server/main.go 

# 开启新窗口启动客户端 1
$ command + t
$ go run mock_client/main.go 

# 开启新窗口启动客户端 2
$ command + t
$ go run mock_client/main.go 

报文格式, 可变长数据需要指明 [长度, 数据]
+-------------------+--------------+---------------------------------------------------+
|               2 Bytes            |  2 Bytes  |       N Bytes                         |
+-------------------+--------------+---------------------------------------------------+
|<=         length of body       =>|     id    | <======= data =======================>|
|<============= header ===========>|<==================== body =======================>|

协议 ：请求登录
id : 100 (2 Bytes)
token :[] (1 Bytes, N Bytes)

协议 ：请求登录回执
id : 100 (2 Bytes)
ok : 1 (1 Bytes)
uid : [](4 Bytes)
uname : [](1 Bytes, N Bytes)


协议 ：请求聊天消息
id : 101 (2 Bytes)
row : [] (4 Bytes)
content : [](2 Bytes, N Bytes)

协议 ：请求聊天消息回执
id : 101 (2 Bytes)
ok : 1 (1 Bytes)

协议 ：聊天信息推送
id : 300 (2 Bytes)
sender : [] (1 Bytes, N Bytes)
content : [](2 Bytes, N Bytes)

Documentation

Index

• func AddRequest(protocolId uint16, req ReqHandle)
• func ConvertAssign(dest, src interface{}) error
• func InSlice(array interface{}, item interface{}) bool
• type Encode
• type JMap
  • func NewJMap(openLock ...bool) *JMap
  • func (jm *JMap) AllKey() []interface{}
  • func (jm *JMap) DelAll()
  • func (jm *JMap) Exist(key interface{}) bool
  • func (jm *JMap) Get(key interface{}, value interface{}) error
  • func (jm *JMap) Interface(key interface{}) interface{}
  • func (jm *JMap) Remove(key interface{})
  • func (jm *JMap) Set(key interface{}, value interface{})
  • func (jm *JMap) SetOrStore(key interface{}, value interface{}) (v interface{}, set bool)
• type Middleware
  • func (mw *Middleware) Closed(f func())
  • func (mw *Middleware) Push(f func(uint16, interface{}))
  • func (mw *Middleware) Reader(f func(uint16, *bytes.Buffer) *bytes.Buffer)
  • func (mw *Middleware) Recover(f func(error, string))
  • func (mw *Middleware) Request(f func(uint16, interface{}))
  • func (mw *Middleware) Respone(f func(uint16, interface{}))
  • func (mw *Middleware) Writer(f func(uint16, *bytes.Buffer) *bytes.Buffer)
• type Opt
• type PushHandle
• type ReqHandle
• type Scanner
• type TcpConn
• type TcpServer
  • func NewServer() TcpServer

Functions

func AddRequest

func AddRequest(protocolId uint16, req ReqHandle)

AddRequest - Join the request processor

func ConvertAssign

func ConvertAssign(dest, src interface{}) error

func InSlice

func InSlice(array interface{}, item interface{}) bool

InSlice 是否在数组内

Types

type Encode

type Encode interface {
	Encode()
	ProtocolId() uint16
}

type JMap

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

func NewJMap

func NewJMap(openLock ...bool) *JMap

func (*JMap) AllKey

func (jm *JMap) AllKey() []interface{}

func (*JMap) DelAll

func (jm *JMap) DelAll()

func (*JMap) Exist

func (jm *JMap) Exist(key interface{}) bool

func (*JMap) Get

func (jm *JMap) Get(key interface{}, value interface{}) error

func (*JMap) Interface

func (jm *JMap) Interface(key interface{}) interface{}

func (*JMap) Remove

func (jm *JMap) Remove(key interface{})

func (*JMap) Set

func (jm *JMap) Set(key interface{}, value interface{})

func (*JMap) SetOrStore

func (jm *JMap) SetOrStore(key interface{}, value interface{}) (v interface{}, set bool)

type Middleware

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

func (*Middleware) Closed

func (mw *Middleware) Closed(f func())

Closed - Close registration for callbacks

func (*Middleware) Push

func (mw *Middleware) Push(f func(uint16, interface{}))

Push - Callbacks on push

func (*Middleware) Reader

func (mw *Middleware) Reader(f func(uint16, *bytes.Buffer) *bytes.Buffer)

Reader - Read data

func (*Middleware) Recover

func (mw *Middleware) Recover(f func(error, string))

Recover - Request a panic in the code

func (*Middleware) Request

func (mw *Middleware) Request(f func(uint16, interface{}))

Request - Callback at request

func (*Middleware) Respone

func (mw *Middleware) Respone(f func(uint16, interface{}))

Respone - Callback when requesting a reply

func (*Middleware) Writer

func (mw *Middleware) Writer(f func(uint16, *bytes.Buffer) *bytes.Buffer)

Writer - Write data

type Opt

type Opt struct {
	Addr               string           // The listen network address
	PacketMaxLength    int              // The maximum byte of a network packet, default 6000
	PacketHeaderLength int8             // Header length of network packet, In 1, 2, 4, 8 byte, default 2
	IdleCheckFrequency time.Duration    // Check for idle connection times, during which no data access will be closed, defailt 120 sec.
	ByteOrder          binary.ByteOrder // The default is binary.BigEndian
}

type PushHandle

type PushHandle interface {
	//Data to push
	Writer() *bytes.Buffer
	//Write byte stream data
	WriteStream(values ...interface{})
}

type ReqHandle

type ReqHandle interface {
	//Read byte stream data
	ReadStream(...interface{}) error
	//Read string data, need to specify length
	ReadStreamByString(int, *string) error
	//Write byte stream data
	WriteStream(...interface{})
	//Reply to a request
	Respone() error
	//Read byte stream
	ReadStreamBytes() []byte
	//Requested data
	Reader() *bytes.Buffer
	//Data to reply to
	Writer() *bytes.Buffer
}

type Scanner

type Scanner interface {
	Scan(src interface{}) error
}

type TcpConn

type TcpConn interface {
	//Additional plug-in objects, available by relying on injection
	Attach(plugin interface{})
	//Additional plug-in objects, interface sits, which can be obtained by relying on injection
	AttachImpl(impl string, plugin interface{})
	//Actively close the connection
	Close()
	//Remote address connected
	RemoteAddr() net.Addr
	//Push
	Push(pushHandle Encode) error
}

type TcpServer

type TcpServer interface {
	//Listening address
	Listen(*Opt)
	//New connection entry
	Accept(func(TcpConn, *Middleware))
}

func NewServer

func NewServer() TcpServer