quickproto

README

Fast golang protocol parser

Supports:

• Headers (Support listed values, IE: Key=[Value, Value, Value])
• Files (Supports multiple files)
• Body (Can be encoded/decoded to any type)
  • !WARNING! !Make sure your delimiter not in the encoding's alphabet!
  • !WARNING! !Make sure your delimiter is not in the message headers, body or filenames!
• Delimiters
  • No alphabetic characters from [A-Z a-z 0-9 =]
• Encryption
  • When encryption is enabled, the client will send a random AES key to the server.
    • This key can be encrypted, if the server was provided with a private key, and the client with a public key.
    • Providing a public or private key is optional.

Data is split apart by the delimiter.

Say the delimiter is a $:

The body and header will be split by the delimiter * 4

Each key value pair will be split by the delimiter * 2

Then the key values will be split by the delimiter.

Example:

key1$value1&value2$$key2$value2$$$$BODYBODYBODY

Usage:

Initialize a config like so:

conf := quickproto.NewConfig([]byte(DELIMITER), USE_ENCODING, USE_CRYPTO, 2048, quickproto.Base16Encoding, quickproto.Base16Decoding)
// RSA only used if USE_CRYPTO is true, and when sending the AES key from client to server.
// The RSA keys are however not required, but highly recommended to securely send the AES key from client to server!
conf.PrivateKey = \*rsa.PrivateKey // Client does not need the private key! This is a security risk!
conf.PublicKey = \*rsa.PublicKey // Server does not need the public key, but it would not pose a security risk.

Then you can simply run a server with the following lines of code:

s := server.New(IP, Port, conf)
s.Listen()
for {
	conn, client, err := s.Accept()
	msg, err := s.Read(client)
}

Or create a client like so:

c := client.New(IP, Port, conf, nil)
c.Connect()
msg := c.CONFIG.NewMessage() // Use config to generate message to omit providing arguments
msg.AddHeader("Test_key", "Test_value")
msg.AddHeader("Test2_key", "Test2_value")
msg.AddHeader("Test3_key", "Test3_value")
msg.AddRawFile("test.txt", []byte("Hello World"))
msg.AddRawFile("test2.txt", []byte("Hello World"))
msg.AddRawFile("test3.txt", []byte("Hello World"))
msg.AddContent("Hello World")
c.Write(msg)

It is also possible to broadcast to multiple clients at once, simply use s.Broadcast(msg).

To capture broadcasts on the client side and interact with them, run a goroutine like so:

func OnBroadcast(msg *quickproto.Message) {
  // Do something with the message
}

c := client.New(IP, Port, conf, nil)
c.Connect()
c.OnMessage = OnBroadcast
go c.Listen()

Documentation

Index

• Variables
• func Base16Decoding(data []byte) ([]byte, error)
• func Base16Encoding(data []byte) []byte
• func Base32Decoding(data []byte) ([]byte, error)
• func Base32Encoding(data []byte) []byte
• func Base64Decoding(data []byte) ([]byte, error)
• func Base64Encoding(data []byte) []byte
• func CraftAddr(ip string, port any) string
• func GZIPcompress(data []byte) ([]byte, error)
• func GZIPdecompress(data []byte) ([]byte, error)
• func GobDecoding(data []byte) ([]byte, error)
• func GobEncoding(data []byte) []byte
• func KeyDecoder(data []byte) (*[32]byte, error)
• func KeyEncoder(key *[32]byte) []byte
• func NewmessageFile(name string, data []byte) messageFile
• func WriteConn(conn net.Conn, msg *Message, aes_key *[32]byte, compress bool) error
• type Config
  • func NewConfig(delimiter []byte, useencoding bool, usecrypto bool, bufsize int, ...) *Config
  • func (c *Config) NewMessage() *Message
• type Message
  • func NewMessage(delimiter []byte, useencoding bool, encode_func func([]byte) []byte, ...) *Message
  • func ReadConn(conn net.Conn, conf *Config, aes_key *[32]byte, compress bool) (*Message, error)
  • func (m *Message) AddContent(content any) error
  • func (m *Message) AddFile(file *messageFile)
  • func (m *Message) AddHeader(key string, value string) error
  • func (m *Message) AddRawFile(name string, data []byte)
  • func (m *Message) BodyDelimiter() []byte
  • func (m *Message) ContentLength() int
  • func (m *Message) EndingDelimiter() []byte
  • func (m *Message) FileDelimiter() []byte
  • func (m *Message) FileSizes() map[string]int
  • func (m *Message) Generate() (*Message, error)
  • func (m *Message) HeaderDelimiter() []byte
  • func (m *Message) Parse() (*Message, error)

Variables

var BANNED_DELIMITERS = []string{
	"=", "_", "\x08", "\x1e", "\x00", "(", ")",
	"A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z",
	"a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z",
}

These are tested not to work. Byte "\x00" is used as a body, when body is empty.

var STANDARD_DELIM []byte = []byte("$")

Standard delimiter.

Functions

func Base16Decoding

func Base16Decoding(data []byte) ([]byte, error)

Hex decoding.

func Base16Encoding

func Base16Encoding(data []byte) []byte

Hex encoding.

func Base32Decoding

func Base32Decoding(data []byte) ([]byte, error)

Base 32 decoding.

func Base32Encoding

func Base32Encoding(data []byte) []byte

Base 32 encoding.

func Base64Decoding

func Base64Decoding(data []byte) ([]byte, error)

Base 64 decoding.

func Base64Encoding

func Base64Encoding(data []byte) []byte

Base 64 encoding.

func CraftAddr

func CraftAddr(ip string, port any) string

Convenience function to craft an address from an IP and a port. Port could be string or int, IP must be string.

func GZIPcompress

func GZIPcompress(data []byte) ([]byte, error)

func GZIPdecompress

func GZIPdecompress(data []byte) ([]byte, error)

func GobDecoding

func GobDecoding(data []byte) ([]byte, error)

Gob decoding.

func GobEncoding

func GobEncoding(data []byte) []byte

Gob encoding.

func KeyDecoder

func KeyDecoder(data []byte) (*[32]byte, error)

func KeyEncoder

func KeyEncoder(key *[32]byte) []byte

func NewmessageFile

func NewmessageFile(name string, data []byte) messageFile

NewmessageFile creates a new messageFile.

func WriteConn

func WriteConn(conn net.Conn, msg *Message, aes_key *[32]byte, compress bool) error

WriteConn writes a message to a connection and encrypts it if needed.

Types

type Config

type Config struct {
	// Delimiter used for separating message data.
	Delimiter []byte
	// Use encoding?
	UseEncoding bool
	// Use crypto?
	UseCrypto bool
	// Buffer size.
	BufSize int
	// Encoding/Decoding functions.
	Encode_func func([]byte) []byte
	Decode_func func([]byte) ([]byte, error)
	// RSA keys
	PrivateKey *rsa.PrivateKey // Server-side.
	PublicKey  *rsa.PublicKey  // Client-side.
	// Compress the messages
	Compressed bool
}

General configuration to use for client and server.

func NewConfig

func NewConfig(delimiter []byte, useencoding bool, usecrypto bool, bufsize int, encode_f func([]byte) []byte, decode_f func([]byte) ([]byte, error)) *Config

NewConfig creates a new Config.

func (*Config) NewMessage

func (c *Config) NewMessage() *Message

Generate a new message with default configuration options.

type Message

type Message struct {
	Data        []byte
	Delimiter   []byte
	Headers     map[string][]string
	Body        []byte
	Files       map[string]*messageFile
	UseEncoding bool
	Encode_func func([]byte) []byte
	Decode_func func([]byte) ([]byte, error)
	F_Encoder   func([]byte) []byte
	F_Decoder   func([]byte) ([]byte, error)
}

A Message is a protocol message.

func NewMessage

func NewMessage(delimiter []byte, useencoding bool, encode_func func([]byte) []byte, decode_func func([]byte) ([]byte, error)) *Message

NewMessage creates a new Message.

func ReadConn

func ReadConn(conn net.Conn, conf *Config, aes_key *[32]byte, compress bool) (*Message, error)

ReadConn reads a message from a connection.

func (*Message) AddContent

func (m *Message) AddContent(content any) error

Add content to the message. Either add []bytes, or a string.

func (*Message) AddFile

func (m *Message) AddFile(file *messageFile)

Add a MessageFile to the message.

func (*Message) AddHeader

func (m *Message) AddHeader(key string, value string) error

Add a header to the message.

func (*Message) AddRawFile

func (m *Message) AddRawFile(name string, data []byte)

Create a MessageFile, and add it to the message.

func (*Message) BodyDelimiter

func (m *Message) BodyDelimiter() []byte

Body delimiter, returns HEADER_DELIMITER + HEADER_DELIMITER

func (*Message) ContentLength

func (m *Message) ContentLength() int

Get content length of the message.

func (*Message) EndingDelimiter

func (m *Message) EndingDelimiter() []byte

End delimiter, returns BODY_DELIMITER + BODY_DELIMITER

func (*Message) FileDelimiter

func (m *Message) FileDelimiter() []byte

File delimiter, returns BODY_DELIMITER + HEADER_DELIMITER

func (*Message) FileSizes

func (m *Message) FileSizes() map[string]int

func (*Message) Generate

func (m *Message) Generate() (*Message, error)

creates a protocol message. Header is a map of key/value pairs. Body is a base64 encoded byte slice.

func (*Message) HeaderDelimiter

func (m *Message) HeaderDelimiter() []byte

Header delimiter, returns DELIMITER + DELIMITER

func (*Message) Parse

func (m *Message) Parse() (*Message, error)

parses protocol messages. Header is a map of key/value pairs. Body is a base64 encoded byte slice.