comm

README

This package provides an abstraction layer for communication protocols in Go, enabling easy implementation of connection and listener interfaces for various communication methods.

Installation

go get github.com/exonlabs/go-utils/pkg/comm

Usage Examples

https://github.com/exonlabs/go-utils/tree/master/examples/comm

Documentation

Index

• Variables
• func IsClosedError(err error) bool
• func IsTLSError(err error) bool
• func LogMsg(log *logging.Logger, msg string, args ...any)
• func LogRx(log *logging.Logger, data []byte, addr any)
• func LogTx(log *logging.Logger, data []byte, addr any)
• type Connection
• type KeepaliveConfig
  • func ParseKeepaliveConfig(opts dictx.Dict) (*KeepaliveConfig, error)
• type LimiterConfig
  • func ParseLimiterConfig(opts dictx.Dict) (*LimiterConfig, error)
• type Listener
• type PollingConfig
  • func ParsePollingConfig(opts dictx.Dict) (*PollingConfig, error)
• type TlsConfig
  • func ParseTlsConfig(opts dictx.Dict) (*TlsConfig, error)

Variables

var (
	// ErrError indicates the parent error.
	ErrError = errors.New("")

	// ErrUri indicates an invalid URI error.
	ErrUri = fmt.Errorf("%winvalid uri", ErrError)
	// ErrConnection indicates a connection failure.
	ErrConnection = fmt.Errorf("%wconnection failed", ErrError)
	// ErrClosed indicates that the connection is closed.
	ErrClosed = fmt.Errorf("%wconnection closed", ErrError)
	// ErrBreak indicates an operation interruption.
	ErrBreak = fmt.Errorf("%woperation break", ErrError)
	// ErrTimeout indicates that the operation timed out.
	ErrTimeout = fmt.Errorf("%woperation timeout", ErrError)
	// ErrSend indicates a send failure.
	ErrSend = fmt.Errorf("%wsend failed", ErrError)
	// ErrRecv indicates a recv failure.
	ErrRecv = fmt.Errorf("%wrecv failed", ErrError)
)

Functions

func IsClosedError

func IsClosedError(err error) bool

IsClosedError checks if the error is related to a closed connection. It recognizes common network errors like EOF, broken pipe, and reset by peer errors.

func IsTLSError

func IsTLSError(err error) bool

IsTLSError checks if the error is related to TLS error

func LogMsg

func LogMsg(log *logging.Logger, msg string, args ...any)

LogMsg logs general communication messages.

func LogRx

func LogRx(log *logging.Logger, data []byte, addr any)

LogRx logs communication received data in formatted hexadecimal.

Example

2006-01-02 15:04:05.000000 RX << 0102030405060708090A0B0C0D0E0F

func LogTx

func LogTx(log *logging.Logger, data []byte, addr any)

LogTx logs communication transmitted data in formatted hexadecimal.

Example

2006-01-02 15:04:05.000000 TX >> 0102030405060708090A0B0C0D0E0F

Types

type Connection

type Connection interface {
	// Uri returns the URI of the connection.
	Uri() string

	// Type returns the type of the connection.
	Type() string

	// Parent returns the listener that created this connection.
	Parent() Listener

	// IsOpened checks if the connection is currently open.
	IsOpened() bool

	// Open establishes the connection, with a specified timeout.
	Open(timeout float64) error

	// Close terminates the connection.
	Close()

	// Cancel interrupts any ongoing operation with this connection.
	Cancel()

	// CancelSend interrupts any ongoing sending operation with this connection.
	CancelSend()

	// CancelRecv interrupts any ongoing receiving operation with this connection.
	CancelRecv()

	// Send transmits data over the connection, with a specified timeout.
	Send(data []byte, timeout float64) error

	// SendTo transmits data to addr over the connection, with a specified timeout.
	SendTo(data []byte, addr any, timeout float64) error

	// Recv receives data over the connection, with a specified timeout.
	Recv(timeout float64) (data []byte, err error)

	// RecvFrom receives data from addr over the connection, with a specified timeout.
	RecvFrom(timeout float64) (data []byte, addr any, err error)
}

Connection represents a generic interface for handling client side connections.

type KeepaliveConfig

type KeepaliveConfig struct {
	// Interval defines in seconds the time between keep-alive probes.
	// use 0 to enable keep-alive probes with OS defined values. (default is 0)
	// use -1 to disable keep-alive probes.
	Interval int
}

KeepaliveConfig is used to configure keep-alive probes for TCP connections.

func ParseKeepaliveConfig

func ParseKeepaliveConfig(opts dictx.Dict) (*KeepaliveConfig, error)

ParseKeepaliveConfig returns keep-alive configuration from parsed options.

The parsed options are:

• keepalive_interval: (int) the keep-alive interval in seconds. use 0 to enable keep-alive probes with OS defined values. (default is 0) use -1 to disable keep-alive probes.

type LimiterConfig

type LimiterConfig struct {
	// SimultaneousConn defines the at most number of connections that
	// the listener accepts simultaneously.
	// use 0 or negative value to disable connections limit.
	SimultaneousConn int
}

LimiterConfig is used to configure limits for listeners.

func ParseLimiterConfig

func ParseLimiterConfig(opts dictx.Dict) (*LimiterConfig, error)

ParseLimiterConfig returns keep-alive configuration from parsed options.

The parsed options are:

• simultaneous_connections: (int) the limit on number of concurrent connections. use 0 or negative value to disable connections limit.

type Listener

type Listener interface {
	// Uri returns the URI of the listener.
	Uri() string

	// Type returns the type of listener.
	Type() string

	// IsActive checks if the listener is currently active.
	IsActive() bool

	// Start initializes the listener and begins accepting connections.
	Start() error

	// Stop terminates the listener and closes all connections.
	Stop()

	// SetConnHandler sets a callback function to handle incoming connections.
	SetConnHandler(handler func(conn Connection))
}

Listener represents a generic interface for handling server side connections.

type PollingConfig

type PollingConfig struct {
	// Timeout defines the timeout in seconds for read data polling.
	// polling timeout value must be > 0.
	Timeout float64
	// ChunkSize defines the size of chunks to read during polling.
	// polling chunk size value must be > 0.
	ChunkSize int
	// MaxSize defines the maximum size for read data.
	// use 0 or negative value to disable max limit.
	MaxSize int
}

PollingConfig is used to configure read polling.

func ParsePollingConfig

func ParsePollingConfig(opts dictx.Dict) (*PollingConfig, error)

ParsePollingConfig returns polling configuration from parsed options.

The parsed options are:

• poll_timeout: (float64) the timeout in seconds for read data polling. polling timeout value must be > 0.
• poll_chunksize: (int) the size of chunks to read during polling. polling chunk size value must be > 0.
• poll_maxsize: (int) the maximum size for read data. use 0 or negative value to disable max limit for read polling.

type TlsConfig

type TlsConfig = tls.Config

TlsConfig is used to configure the TLS attributes for TCP connections.

func ParseTlsConfig

func ParseTlsConfig(opts dictx.Dict) (*TlsConfig, error)

ParseTlsConfig returns tls configuration from parsed options.

The parsed options are:

• tls_enable: (bool) enable/disable TLS, default disabled.
• tls_mutual_auth: (bool) enable/disable mutual TLS auth, default disabled.
• tls_server_name: (string) server name to use by client TLS session.
• tls_min_version: (float64) min TLS version to use. default TLS v1.2
• tls_max_version: (float64) max TLS version to use. default TLS v1.3
• tls_ca_certs: (string) comma separated list of CA certs to use. cert values could be file paths to load or cert content in PEM format.
• tls_local_cert: (string) cert to use for TLS session. cert could be file path to load or cert content in PEM format.
• tls_local_key: (string) private key to use for TLS session. key could be file path to load or key content in PEM format.