net

package
v0.0.0-...-915fa77 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 22, 2022 License: BSD-2-Clause Imports: 12 Imported by: 0

Documentation

Overview

Package net provides abstractions for TCP servers and clients which handle massively parallel IO and present a unified interface for implementing security and messaging protocols on top of them.

Network message (max length 32KB) 

flags
    11: compressed
    12: encrypted
    13: reserved
    14: reserved
    15: reserved
    16: reserved

[0-1] msgtype (bits 1-10 for 1024 unique msg types), flags (bits 11-16) [2-3] msgsize (uint16) [4-7] crc32 checksum of payload (uint32) [8-32767] payload is msg size

Index

Constants

View Source 
const (
	DEFAULT_EVT_TIMEOUT_SEC = 5
	DEFAULT_MSG_TIMEOUT_SEC = 15
	MAX_TIMEOUT_SEC         = 300
	MIN_TIMEOUT_SEC         = 1
	QUEUE_TIMEOUT_SEC       = 5
)

Timeouts.

View Source 
const (
	HEADER_LEN_B    = 8
	MAX_MSG_TYPE    = 1023
	MAX_NET_MSG_LEN = 32 * 1024
)

Message header constants.

View Source 
const (
	PERF_PROTO_CONNECT = iota
	PERF_PROTO_DISCONNECT
	PERF_PROTO_ERR_AUTH_CLIENT
	PERF_PROTO_ERR_DESERIALIZE
	PERF_PROTO_ERR_MAX_MSG_SIZE
	PERF_PROTO_ERR_NO_ACCESS
	PERF_PROTO_ERR_NO_PROVIDER
	PERF_PROTO_ERR_RCV_CHECKSUM
	PERF_PROTO_ERR_RCV_CON_NIL
	PERF_PROTO_ERR_RCV_DECRYPT
	PERF_PROTO_ERR_RCV_DECOMPRESS
	PERF_PROTO_ERR_SEND_COMPRESS
	PERF_PROTO_ERR_SEND_ENCRYPT
	PERF_PROTO_ERR_SEND_INVALID_CLI
	PERF_PROTO_ERR_SEND_INVALID_MSG_TYPE
	PERF_PROTO_ERR_SERIALIZE
	PERF_PROTO_RCV_BYTES
	PERF_PROTO_RCV_OK
	PERF_PROTO_RCV_TOTAL
	PERF_PROTO_SEND_BYTES
	PERF_PROTO_SEND_OK
	PERF_PROTO_SEND_TOTAL
	PERF_PROTO_TIMEOUT_CONNECT
	PERF_PROTO_TIMEOUT_DISCONNECT
	PERF_PROTO_TIMEOUT_GENERAL
	PERF_PROTO_TIMEOUT_RCV
	PERF_PROTO_TIMEOUT_SEND
	PERF_PROTO_COUNT
)

Perf counters.

View Source 
const (
	PERF_TCP_CONNECTIONS = iota
	PERF_TCP_DISCO
	PERF_TCP_MSG_RECEIVE
	PERF_TCP_MSG_RECEIVE_BYTES
	PERF_TCP_MSG_SEND
	PERF_TCP_MSG_SEND_BYTES
	PERF_TCP_MSG_TIMEOUT
	PERF_TCP_SERVERS
	PERF_TCP_COUNT
)

Perf counters.

View Source 
const (
	TIMEOUT_CONNECT = iota
	TIMEOUT_DISCONNECT
	TIMEOUT_GENERAL
	TIMEOUT_RCV
	TIMEOUT_SEND
)

Timeout types.

View Source 
const (
	PERF_UDP_MSG_RECEIVE = iota
	PERF_UDP_MSG_RECEIVE_BYTES
	PERF_UDP_MSG_SEND
	PERF_UDP_MSG_SEND_BYTES
	PERF_UDP_MSG_TIMEOUT
	PERF_UDP_SERVERS
	PERF_UDP_COUNT
)

Perf counters.

View Source 
const QUEUE_BUFFERS = 100

Event queue buffer sizes

View Source 
const TCP_BUFFER_SIZE_B = 256

TCP Buffer size for reading data off the line.

Variables

View Source 
var (
	ErrDeserializeFailed = errors.New("Deserialization failed")
	ErrInvalidType       = errors.New("Invalid type received")
	ErrBufferTooSmall    = errors.New(
		"msgData buffer not large enough to contain a message",
	)
	ErrInvalidMsgType = errors.New("msgType > MAX_MSG_TYPE")
	ErrMaxMsgSize     = errors.New("Message size > MAX_NET_MSG_LEN")
)

Common error messages.

Functions

func GetMsgChecksum 

func GetMsgChecksum(header uint64) uint32

GetMsgChecksum retrieves the checksum field from raw line data.

func GetMsgCompressedFlag 

func GetMsgCompressedFlag(header uint64) bool

GetMsgCompressedFlag retrieves bit 11 of the message header, which is used to specify whether the message data itself is compressed or not.

func GetMsgEncryptedFlag 

func GetMsgEncryptedFlag(header uint64) bool

GetMsgEncryptedFlag retrieves bit 12 of the message header, which is used to specify whether the message data itself is encrypted or not.

func GetMsgHeader 

func GetMsgHeader(msgData []byte) (uint64, error)

GetMsgHeader retrieves the 64bit header from a raw message buffer.

func GetMsgPayload 

func GetMsgPayload(msgData []byte) ([]byte, error)

GetMsgPayload returns the payload portion of a raw message buffer.

func GetMsgSig 

func GetMsgSig(header uint64) uint16

GetMsgSig retrieves the message type signature out of a raw message header.

func GetMsgSigPart 

func GetMsgSigPart(value uint16) uint16

GetMsgSigPart returns the message signature portion of a uint16 value.

func GetMsgSize 

func GetMsgSize(header uint64) uint16

GetMsgSize retrieves the data size property from a 64bit header.

func InitHttpSrv 

func InitHttpSrv(addr string)

InitHttpSrv initializes the http server. Register handlers as is normal for the net/http service.

func NextNetID 

func NextNetID() uint32

NextNetID retrieves the next available network ID for use.

func SetMsgChecksum 

func SetMsgChecksum(header *uint64, hash uint32)

SetMsgChecksum sets bytes 4-8 to the computed crc32 hash of the payload data.

func SetMsgCompressedFlag 

func SetMsgCompressedFlag(header *uint64, val bool)

SetMsgCompressedFlag sets bit 11 of a raw header object, which is used to specify whether the following data block is compressed or not.

func SetMsgEncryptedFlag 

func SetMsgEncryptedFlag(header *uint64, val bool)

SetMsgEncryptedFlag sets bit 12 of a raw header object, which is used to specify whether the following data block is encrypted or not.

func SetMsgHeader 

func SetMsgHeader(header uint64, msgData []byte) error

SetMsgHeader sets the first 8 bytes of a raw data buffer with the supplied header.

func SetMsgPayload 

func SetMsgPayload(data, msgData []byte)

SetMsgPayload takes the supplied message payload, sets the message size property, computes and sets the checksum property, and also copies the message payload into the raw buffer.

func SetMsgSig 

func SetMsgSig(header *uint64, msgType uint16) error

SetMsgSig sets the first 10 bits of a message header with the supplied msgType.

func SetMsgSize 

func SetMsgSize(header *uint64, size int) error

SetMsgSize sets the message size property on a raw data buffer.

func ValidateMsgHeader 

func ValidateMsgHeader(msgData []byte) bool

ValidateMsgHeader does some simple validation of the header in a raw data buffer.

Types

type AccessProvider 

type AccessProvider interface {
	Authorize(con Connection) (byte, error)
	Close()
	Init(proto *Protocol)
}

AccessProvider specifies the interface which network protocols will use to authorize messages for sending or processing. All incoming messages flow through Authorize(). It is left to the individual MsgProcessors to decide whether to check authorization for outgoing messages or not.

type BroadcastGroup 

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

BroadcastGroup represents a group of Connections that can be addressed by via a single NetID. BroadcastGroup itself implements the Connection interface so that it can be used interchangebly with single Connection objects.

func NewBroadcastGroup 

func NewBroadcastGroup(name string) *BroadcastGroup

NewBroadcastGroup is a constructor helper which builds a newly initalized instance of BroadcastGroup and returns a pointer to it for use.

func (*BroadcastGroup) AddConnection 

func (this *BroadcastGroup) AddConnection(con Connection)

AddConnection adds a new Connection object to this group.

func (*BroadcastGroup) Close 

func (this *BroadcastGroup) Close()

Close removes all Connection objects from the group, after calling Close() on each.

func (*BroadcastGroup) GetConnection 

func (this *BroadcastGroup) GetConnection(id uint32) Connection

GetConnection returns the member Connection object matching the given id if one exists, otherwise returns nil.

func (*BroadcastGroup) Id 

func (this *BroadcastGroup) Id() uint32

Id returns the net ID for this BroadcastGroup.

func (*BroadcastGroup) Key 

func (this *BroadcastGroup) Key() string

Key returns the assigned Key for this BroadcastGroup.

func (*BroadcastGroup) LocalAddr 

func (this *BroadcastGroup) LocalAddr() stdnet.Addr

LocalAddr always returns nil for a BroadcastGroup.

func (*BroadcastGroup) Name 

func (this *BroadcastGroup) Name() string

func (*BroadcastGroup) RemoteAddr 

func (this *BroadcastGroup) RemoteAddr() stdnet.Addr

RemoteAddr always returns nil for a BroadcastGroup.

func (*BroadcastGroup) RemoveConnection 

func (this *BroadcastGroup) RemoveConnection(id uint32)

RemoveConnection removes a connection from the BroadcastGroup.

func (*BroadcastGroup) Send 

func (this *BroadcastGroup) Send(data []byte, timeoutSec int)

Send transmits a slice of bytes to member Connections in the BroadcastGroup.

type CompressionProvider 

type CompressionProvider interface {
	Close()
	Compress(msg *Msg) error
	Decompress(msg *Msg) error
	Init(proto *Protocol)
}

CompressionProvider specifies the interface which network protocols will use to compress/decompress network messages. All outgoing messages flow through Compress(). Only messages received with the compression header bit set will flow through Decompress().

type Connection 

type Connection interface {
	Close()
	Id() uint32
	Key() string
	LocalAddr() stdnet.Addr
	RemoteAddr() stdnet.Addr
	Send(data []byte, timeoutSec int)
}

Connection specifies the common interface that is used by AccessProvider objects to provide authentication for network objects. A given AccessProvider may validate based on none, one, or many pieces of the exposed data.

type CryptoProvider 

type CryptoProvider interface {
	Close()
	Decrypt(msg *Msg) error
	Encrypt(msg *Msg) error
	Init(proto *Protocol)
}

CryptoProvider specifies the interface which network protocols will use to encrypt and decrypt network messages. All outgoing messages flow through Encrypt(). Only messages received with the encrypted header bit set will flow through Decrypt().

type EventHandler 

type EventHandler interface {
	Close()
	Init(proto *Protocol)
	OnConnect(con Connection)
	OnDisconnect(con Connection)
	OnError(err error)
	OnReceive(msg interface{}, fromId uint32, access byte)
	OnShutdown()
	OnTimeout(timeout *TimeoutEvent)
}

EventHandler represents the interface that user code should implement to handle events from a given protocol registered in the network layer.

type Msg 

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

Msg represents the baseline structure of data used for packaging network messages to be sent via the net service.

func NewMsg 

func NewMsg() *Msg

NewMsg initializes a new Msg object and returns a pointer to it for use.

func (*Msg) Connection 

func (this *Msg) Connection() Connection

Connection returns the Connection object (if any) associated with this Msg object.

func (*Msg) From 

func (this *Msg) From() uint32

From returns the local network ID of the network endpoint which received this message.

func (*Msg) GetBytes 

func (this *Msg) GetBytes() []byte

GetBytes retreives the Msg, fully serialized with header and payload, for transmission.

func (*Msg) GetHeader 

func (this *Msg) GetHeader() uint64

GetHeader retrieves the header portion of the Msg object.

func (*Msg) GetPayload 

func (this *Msg) GetPayload() []byte

GetPayload retrieves the payload portion of the Msg object.

func (*Msg) Len 

func (this *Msg) Len() int

Len returns the overall size of the data contained within the Msg object, including header and payload.

func (*Msg) SetCompressed 

func (this *Msg) SetCompressed(value bool)

SetCompressed sets the compressed flag in this message's header.

func (*Msg) SetConnection 

func (this *Msg) SetConnection(parentCon Connection)

SetConnection sets the connection associated with this msg.

func (*Msg) SetEncrypted 

func (this *Msg) SetEncrypted(value bool)

SetEncrypted sets the encryption flag in this message's header.

func (*Msg) SetHeader 

func (this *Msg) SetHeader(header uint64)

SetHeader sets the 64bit header for this message.

func (*Msg) SetMsgType 

func (this *Msg) SetMsgType(msgType uint16)

SetMsgType sets the message signature in this message's header.

func (*Msg) SetPayload 

func (this *Msg) SetPayload(data []byte)

SetPayload sets the payload buffer for this message and recalculates the msg size and checksum.

func (*Msg) SetTimeout 

func (this *Msg) SetTimeout(timeoutSec int)

SetTimeout sets this message's timeout (in seconds).

func (*Msg) TimeoutSec 

func (this *Msg) TimeoutSec() int

TimeoutSec returns the current timeout (in seconds) specified for this Msg object.

type MsgProcessor 

type MsgProcessor interface {
	Close()
	DeserializeMsg(msg *Msg, access byte) (interface{}, error)
	Init(proto *Protocol)
	SerializeMsg(data interface{}) (*Msg, error)
	Signature() uint16
}

MsgProcessor specifies the interface which user code should implement to define the serialization behavior of a given message signature.

type NetConnector 

type NetConnector interface {
	Start(addr string) (Connection, error)
	Stop()
}

NetConnector represents a connector to another network device. Some example implmentations of NetConnector are the built-in TCP and UDP client and server objects.

type NoSecurity 

type NoSecurity struct{}

NoSecurity implements AccessProvider in a way which always returns maximum privileges (255).

func (*NoSecurity) Authorize 

func (this *NoSecurity) Authorize(con Connection) (byte, error)

Authorize always returns 255, nil.

func (*NoSecurity) Close 

func (this *NoSecurity) Close()

Unused.

func (*NoSecurity) Init 

func (this *NoSecurity) Init(proto *Protocol)

Unused.

type Protocol 

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

Protocol represents a collection of related clients, message type signatures, and the message processing, access, crypto, and compression providers which will be used as a part of the messaging pipeline for those message types.

func NewProtocol 

func NewProtocol(pName string, evtHandler EventHandler) *Protocol

NewProtocol is a helper constructor function which creates a newly initialized Protocol object and returns a pointer to it for use.

func (*Protocol) AddSignature 

func (this *Protocol) AddSignature(proc MsgProcessor)

AddSignature registers a message type signature and its associated message processing object with this protocol.

func (*Protocol) DeleteSignature 

func (this *Protocol) DeleteSignature(proc MsgProcessor)

DeleteSignature removes a message type signature and its associated message processing object if one exists.

func (*Protocol) DialTcp 

func (this *Protocol) DialTcp(addr string) error

DialTcp attempts to create a TCP connection to the given network address.

func (*Protocol) DialUdp 

func (this *Protocol) DialUdp(addr string, socket *stdnet.UDPConn) error

DialUdp attempts to create a UDP connection object for the given UDP endpoint address.

func (*Protocol) GetAllConnections 

func (this *Protocol) GetAllConnections() []Connection

GetAllConnections returns a slice containing all connections associated with the protocol object.

func (*Protocol) GetConnection 

func (this *Protocol) GetConnection(id uint32) Connection

GetConnection queries the protocol's list of registered connections and returns the one matching the supplied NetId, otherwise it returns nil.

func (*Protocol) ListenTcp 

func (this *Protocol) ListenTcp(addr string) error

ListenTcp attempts to set up a tcpSrv instance listening on the given address.

func (*Protocol) ListenUdp 

func (this *Protocol) ListenUdp(addr string) (*stdnet.UDPConn, error)

ListenUdp attempts to set up a udp listener instance at the given address.

func (*Protocol) RegisterConnection 

func (this *Protocol) RegisterConnection(con Connection)

RegisterConnection registers a new connection object with this protocol. Connections which attempt to send messages that are a part of this protocol will auto-register, but RegisterConnection provides a manual way of adding Connection objects or ConnectionGroups as clients of the protocol.

func (*Protocol) SendMsg 

func (this *Protocol) SendMsg(id uint32, sig uint16, msg interface{}) error

SendMsg transmits the supplied message to the target connection Id.

func (*Protocol) SetAccessProvider 

func (this *Protocol) SetAccessProvider(provider AccessProvider)

SetAccessProvider sets the AccessProvider object responsible for authorizing messages and clients on this protocol.

func (*Protocol) SetCompressionProvider 

func (this *Protocol) SetCompressionProvider(provider CompressionProvider)

SetCompressionProvider sets the CompressionProvider object responsible for handling compression and decompression of messages passing through the protocol.

func (*Protocol) SetCryptoProvider 

func (this *Protocol) SetCryptoProvider(provider CryptoProvider)

SetCryptoProvider sets the CryptoProvider object responsible for handling encryption/decryption of messages passing through the protocol.

func (*Protocol) Shutdown 

func (this *Protocol) Shutdown()

Shutdown removes the Protocol from the net service, also unregistering all associated message type signatures in the process.

type TimeoutEvent 

type TimeoutEvent struct {
	Data        interface{}
	MessageType uint16
	ParentId    uint32
	TimeoutType int
}

TimeoutEvent represents a network operation and associated data which has timed out. TimeoutEvents can be handled or ignored by user code as is appropriate for the given application.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.