EASY FRAMEWORK

Summary

A light net framework writen with golang. You can use it to write games,web,or chat and so on.

Easy framework biggest advantage is light, flexibility and customeize. you can change some component of Easy to adapt to your needs.

It includes various Network Transport Protocol such as TCP,websocket,HTTP. The TCP transmission rule can be customed too. so,in addition to using default rules, you can also choose your own rules, but you need to implement the interface of Rule.

Directory

• Installation
• Quick Start
• Router for keepalive
• ListenServers
• Customize
• Open Packages
• NETS
• RPC and discovery
• Examples
• Building With Docker
• Contribution
• License

Installation

go get github.com/slclub/easy

If you want the more detaild tutorial. Please refer to the sample testing project in the examples directory .

Quick Start

Start Listen Servers

• import

import (
    "github.com/slclub/easy/nets/agent"
    "github.com/slclub/easy/servers"
    "github.com/slclub/easy/typehandle"
)

• Set

Registe server with your configruation.Here we use the websocket server(servers.WSServer) as an example.

server1 = servers.NewWSServer()

server1.Init(&agent.Gate{
    Addr:            ":18080",
    Protocol:        typehandle.ENCRIPT_DATA_JSON,
    PendingWriteNum: 2000,
    LittleEndian:    true,
    MaxConnNum:      2000,
})

• Start

Please use the easy.Serv to start all of your listening servers. you can start more than one listening server.Each server has its owned network protocol.

func Start() {
    easy.Serv(
        lservers.Server1(), // websocket 监听服务 可以有多个
        //lservers.Server2(), // tcp 服务
    )
}

registe

Registe message id and message struct and handle to the router of servers

Each server has a corresponding router.

// "github.com/slclub/easy/typehandle"
r1 := lservers.Server1().Router()
r1.Register(ID.LOGIN_RES, &json.LoginRes{}, nil)
r1.Register(ID.LOGIN_REQ, &json.LoginReq{}, typehandle.HandleMessage(login.HandleLogin))

handle

Handle is a listening service and processing function. In the other word it's a controller(The C of MVC).

It is an entry function of logical business.

• First Argument

It is a Agent object. You just need to understand like a link.

• Second Argument

It is a message that you defined.

Please used the Pointer type of Golang.

• example

import (
    "github.com/slclub/easy/nets/agent"
    "reflect"
    "simple/vendors/log8q"
)

func HandleLogin(agent1 agent.Agent, arg any) {
    log8q.Log().Info("WS controller.Handle.Login info: ", reflect.TypeOf(arg).Elem().Name())
    // agent1.WriteMsg(nil)
}

func HandleLoginTcp(agent2 agent.Agent, arg any) {
    log8q.Log().Info("TCP controller.Handle.Login info: ", reflect.TypeOf(arg).Elem().Name())
}

Router for keepalive

Router is the link between servers and handle. All parts of the router are implemented using interfaces. so,you can custome it by your self. especially for Binder and Encoder that they are related to rules and data tranmited .

Router

• definition

type Router interface {
    element.Distributer
    Register(ID element.MID, msg any, handle typehandle.HandleMessage)
    Route(msg any, ag any) error
    PathMap() *element.PathMap
}

// 为route 绑定插件
type Distributer interface {
    DistributePlug
    // 绑定 解码器=typehandle.Encoder ; 绑定器 = element.Binder
    // Binding(encoder typehandle.Encoder, binder Binder)
    Binding(plugins ...any)
}

type DistributePlug interface {
    Binder() Binder
    Encoder() encode.Encoder
}

• Binding method

The Binding(plugins ...any) method can bind binder and encoder to Router. So use this method to replace Binder and Encoder if you want to custom yourself.

example:

r := Server1().Router()
r.Binding(bind.NewBindJson(r.PathMap()), encode.NewJson(r.PathMap()))

• PathMap

This method return the storage for routing. Binder and Encoder should use it together.

Encoder

Encode/Decode transferred data. you can also customize this component. By default, we support two types : json and protobuf.

• Interface

// stream 解析器 encode decode操作
type Encoder interface {
	Unmarshal(data []byte) (any, error)
	Marshal(msg any) ([]byte, error)
	LittleEndian(...bool) bool
}

• JSON

• Protobuf

Binder

It has three basic functions: binding Encoder, binding handle and route functions. It corresponds one-to-one with the encoder. the methods of Register, RegisterHandle and Route will be called by Router

• Interface

type Binder interface {
    // 绑定消息ID 和消息
    Register(id MID, msg any)
    // 绑定 handle 到 路由
    RegisterHandle(id MID, handle typehandle.HandleMessage)
    // 继承执行器
    RouteExecuter
}


type RouteExecuter interface {
    // 路由分发消息  给 对应的handle
    Route(msg any, ag any) error
}

ListenServers

I had defined various servers followed by network protocol.

Any of them can be New. so It is very convenient to use more than one servers in your project. Any instance servers can use different components. Also they can be customed.

The Listen Server like a container of components, enable smooth collaboration among various components to complete tasks.

interface

All of the servers should implement the interface of ListenServer. They will all be used uniformly in the easy.Serv().

import (
    "github.com/slclub/easy/nets/agent"
    "github.com/slclub/easy/route"
)

type ListenServer interface {
    Init(*agent.Gate)
    OnInit()
    Router() route.Router
    Start()
    Hook() *hookAgent // agent 链接 回调
    //OnClose(func())
    Close()
}

websocket

• Name

WSServer

• Create

// import github.com/slclub/easy/servers
servers.NewWSServer()

TCP

• Name

TCPServer

• Create

// import github.com/slclub/easy/servers
servers.NewTCPServer()

WEB

Customize

components:

• Listen Server
• Router
• route.Binder
• route.Encoder
• Agent Of Net
• FromConnReadWriter of conns
• Conn of conns

Open Packages

option package

aoi package

events package

log8q package

---

NETS

agent.Agent

When you send or recvive messages from client,you will need to use this.

The first argment of the handle that registed in your Router is agent.Agent type.

You will bind it to your own entity.

type Agent interface {
    WriteMsg(msg any)
    LocalAddr() net.Addr
    RemoteAddr() net.Addr
    Close()
    Destroy()
    UserData() any
    SetUserData(data any)
    LoopRecv(handle AgentHandle)
}

• Send Message

Agent.WriteMsg(msg any)

• Recive Message

Will be called by Router Excuter. So we do not need to care about it.

The handle functions is the processor that receives messages.

conns.Conn

It is does not matter with the logical business. Just open for framework customed.

type Conn interface {
    ReadMsg() ([]byte, error)
    WriteMsg(args []byte) error
    LocalAddr() net.Addr
    RemoteAddr() net.Addr
    Close()
    Destroy()
    Done() chan struct{}
    GetOption() *Option
}

RPC

The easy framework program integrates GRPC and ETCD. constitutes a complete service discovery and distributed RPC communication server architecture.

easy

tutorials and example

ETCD with docker

grpc-go 官网

etcd 官网

docker image (quay.io/coreos/etcd). Ofcourse, you can used any image according to your preferences.

Examples

Detail

Building With Docker

Under Construction.

Contribution

License

Copyright (c) 2023 许亚军

MIT