xtcp

A TCP Server Framework with graceful shutdown, custom protocol.

Programming language: Go

License: MIT License

Tags: Networking    

README

xtcp

A TCP Server Framework with graceful shutdown,custom protocol.

Usage

Define your protocol format:

Before create server and client, you need define the protocol format first.

// Packet is the unit of data.
type Packet interface {
    fmt.Stringer
}

// Protocol use to pack/unpack Packet.
type Protocol interface {
    // return the size need for pack the Packet.
    PackSize(p Packet) int
    // PackTo pack the Packet to w.
    // The return value n is the number of bytes written;
    // Any error encountered during the write is also returned.
    PackTo(p Packet, w io.Writer) (int, error)
    // Pack pack the Packet to new created buf.
    Pack(p Packet) ([]byte, error)
    // try to unpack the buf to Packet. If return len > 0, then buf[:len] will be discard.
    // The following return conditions must be implement:
    // (nil, 0, nil) : buf size not enough for unpack one Packet.
    // (nil, len, err) : buf size enough but error encountered.
    // (p, len, nil) : unpack succeed.
    Unpack(buf []byte) (Packet, int, error)
}

Set your logger(optional):

func SetLogger(l Logger)

Note: xtcp will not output any log by default unless you implement your own logger.

Provide event handler:

In xtcp, there are some events to notify the state of net conn, you can handle them according your need:

const (
    // EventAccept mean server accept a new connect.
    EventAccept EventType = iota
    // EventConnected mean client connected to a server.
    EventConnected
    // EventRecv mean conn recv a packet.
    EventRecv
    // EventClosed mean conn is closed.
    EventClosed
)

To handle the event, just implement the OnEvent interface.

// Handler is the event callback.
// p will be nil when event is EventAccept/EventConnected/EventClosed
type Handler interface {
    OnEvent(et EventType, c *Conn, p Packet)
}

Create server:

// 1. create protocol and handler.
// ...

// 2. create opts.
opts := xtcp.NewOpts(handler, protocol)

// 3. create server.
server := xtcp.NewServer(opts)

// 4. start.
go server.ListenAndServe("addr")

Create client:

// 1. create protocol and handler.
// ...

// 2. create opts.
opts := xtcp.NewOpts(handler, protocol)

// 3. create client.
client := NewConn(opts)

// 4. start
go client.DialAndServe("addr")

Send and recv packet.

To send data, just call the 'Send' function of Conn. You can safe call it in any goroutines.

func (c *Conn) Send(buf []byte) error

To recv a packet, implement your handler function:

func (h *myhandler) OnEvent(et EventType, c *Conn, p Packet) {
    switch et {
        case EventRecv:
            ...
    }
}

Stop

xtcp have three stop modes, stop gracefully mean conn will stop until all cached data sended.

// StopMode define the stop mode of server and conn.
type StopMode uint8

const (
    // StopImmediately mean stop directly, the cached data maybe will not send.
    StopImmediately StopMode = iota
    // StopGracefullyButNotWait stop and flush cached data.
    StopGracefullyButNotWait
    // StopGracefullyAndWait stop and block until cached data sended.
    StopGracefullyAndWait
)

Example

The example define a protocol format which use protobuf inner. You can see how to define the protocol and how to create server and client.

example