Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/xfxdev/xtcp
A TCP Server Framework with graceful shutdown, custom protocol.
https://github.com/xfxdev/xtcp
framework golang graceful server tcp
Last synced: about 2 months ago
JSON representation
A TCP Server Framework with graceful shutdown, custom protocol.
- Host: GitHub
- URL: https://github.com/xfxdev/xtcp
- Owner: xfxdev
- License: mit
- Created: 2016-03-31T16:50:14.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2020-02-29T18:57:41.000Z (almost 5 years ago)
- Last Synced: 2024-07-31T20:52:36.781Z (4 months ago)
- Topics: framework, golang, graceful, server, tcp
- Language: Go
- Homepage:
- Size: 39.1 KB
- Stars: 150
- Watchers: 14
- Forks: 31
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-go - xtcp - TCP Server Framework with simultaneous full duplex communication, graceful shutdown, and custom protocol. (Networking / Transliteration)
- zero-alloc-awesome-go - xtcp - TCP Server Framework with simultaneous full duplex communication, graceful shutdown, and custom protocol. (Networking / Transliteration)
- awesome-go-extra - xtcp - 03-31T16:50:14Z|2020-02-29T18:57:41Z| (Networking / Uncategorized)
- awesome-go-zh - xtcp
- awesome-go - xtcp - A TCP Server Framework with graceful shutdown, custom protocol. - ★ 48 (Networking)
README
# xtcp
A TCP Server Framework with graceful shutdown,custom protocol.
[](https://travis-ci.org/xfxdev/xtcp)
[](https://goreportcard.com/report/github.com/xfxdev/xtcp)
[](https://godoc.org/github.com/xfxdev/xtcp)
## Usage
### Define your protocol format:
Before create server and client, you need define the protocol format first.
```go
// 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):
```go
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:
```go
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.
```go
// 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:
```go
// 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:
```go
// 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.
```go
func (c *Conn) Send(buf []byte) error
```
To recv a packet, implement your handler function:
```go
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.
```go
// 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](https://github.com/xfxdev/xtcp/tree/master/_example)