tcpack

README

tcpack

English | 简体中文

tcpack is an application protocol based on TCP to Pack and Unpack bytes stream in go (or 'golang' for search engine friendliness) program.

What dose tcpack do?

As we all know, TCP is a transport layer protocol oriented to byte streams. Its data transmission has no clear boundaries, so the data read by the application layer may contain multiple requests and cannot be processed.

tcpack is to solve this problem by encapsulating the request data into a message, packaging it when sending and unpacking it when receiving.

notice: It is unsafe to use a packer to read and write messages concurrently on the same connection. Do not do this, as it will have unpredictable consequences!

If you want to use multiple packagers based on the same TCP connection to send and receive messages concurrently, please use safetcpack.

What's in the box?

This library provides a packager which support Pack and Unpack.

Installation Guidelines

1. To install the tcpack package, you first need to have Go installed, then you can use the command below to add tcpack as a dependency in your Go program.

go get -u github.com/lim-yoona/tcpack

1. Import it in your code:

import "github.com/lim-yoona/tcpack"

Usage

package main

import "github.com/lim-yoona/tcpack"

func main() {
	// 创建一个打包器
	mp := tcpack.NewMsgPack(8, tcpConn)

	// 打包一个消息并发送
	msg := tcpack.NewMessage(0, uint32(len([]byte(data))), []byte(data))
	num, err := mp.Pack(msg)

	// 解包一个消息并接收
	msg, err := mp.Unpack()
}

Support JSON

type Person struct {
	Name string `json:"name"`
	Age  int    `json:"age"`
}

// Create a packager
mp := tcpack.NewMsgPack(8, tcpConn)

// data JSON Marshal
data := &Person{
	Name: "jack",
	Age:  20,
}
dataJSON, _ := json.Marshal(data)

// Pack and send a message
msgSend := tcpack.NewMessage(0, uint32(len(dataJSON)), dataJSON)
num, err := mp.Pack(msgSend)

// Unpack and receive a message
msgRsv, err := mp.Unpack()

// JSON UnMarshal
var dataRsv Person
json.Unmarshal(msgRsv.GetMsgData(), &dataRsv)

Examples

Here are some Examples.

Documentation

Index

• type IMsgPack
• type Imessage
• type Message
  • func NewMessage(id, datalen uint32, data []byte) *Message
  • func (msg *Message) GetDataLen() uint32
  • func (msg *Message) GetMsgData() []byte
  • func (msg *Message) GetMsgId() uint32
• type MsgPack
  • func NewMsgPack(headlen uint32, conn net.Conn) *MsgPack
  • func (mp *MsgPack) GetHeadLen() uint32
  • func (mp *MsgPack) Pack(msg Imessage) (uint32, error)
  • func (mp *MsgPack) Unpack() (Imessage, error)

Types

type IMsgPack

type IMsgPack interface {
	// Get the head length of the message package.
	GetHeadLen() uint32
	// Pack returns bytes stream packed from a message.
	Pack(Imessage) (uint32, error)
	// Unpack returns a message from bytes stream.
	Unpack() (Imessage, error)
}

IMsgPack is an interface that defined a packager, which carries HeadLen, and provides Pack() and Unpack() method.

type Imessage

type Imessage interface {
	GetDataLen() uint32
	GetMsgId() uint32
	GetMsgData() []byte
}

Imessage is an interface that definds a message, which carries DataLen, MsgId and MsgData.

type Message

type Message struct {
	Id      uint32
	DataLen uint32
	Data    []byte
}

Message implements Imessage.

func NewMessage

func NewMessage(id, datalen uint32, data []byte) *Message

NewMessage returns a message typed *Message.

func (*Message) GetDataLen

func (msg *Message) GetDataLen() uint32

GetDataLen returns DataLen typed uint32.

func (*Message) GetMsgData

func (msg *Message) GetMsgData() []byte

GetMsgData returns Data typed []byte.

func (*Message) GetMsgId

func (msg *Message) GetMsgId() uint32

GetMsgId returns Id typed uint32.

type MsgPack

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

MsgPack implements the interface IMsgPack, carrying HeadLen and conn for Pack() and Unpack().

func NewMsgPack

func NewMsgPack(headlen uint32, conn net.Conn) *MsgPack

NewMsgPack returns a packager *MsgPack.

func (*MsgPack) GetHeadLen

func (mp *MsgPack) GetHeadLen() uint32

GetHeadLen return HeadLen of the message.

func (*MsgPack) Pack

func (mp *MsgPack) Pack(msg Imessage) (uint32, error)

Pack packs a message to bytes stream and sends it.

func (*MsgPack) Unpack

func (mp *MsgPack) Unpack() (Imessage, error)

Unpack unpacks a certain length bytes stream to a message.