netcomm

README

This package provides functionalities for establishing network-based communications in Go applications.

Installation

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

Usage

Connection URI

<network>@<host>:<port>

• network: TCP and UDP networks {tcp|tcp4|tcp6|udp|udp4|udp6}
• host: The host FQDN or IP address.
• port: The port number. can be number or protocol name.

Usage Example

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

Documentation

Index

• func GetAddr(network, address string) (net.Addr, error)
• func ParseUri(uri string) (string, string, error)
• type Connection
  • func NewConnection(uri string, commlog *logging.Logger, opts dictx.Dict) (*Connection, error)
  • func (c *Connection) Cancel()
  • func (c *Connection) CancelRecv()
  • func (c *Connection) CancelSend()
  • func (c *Connection) Close()
  • func (c *Connection) IsOpened() bool
  • func (c *Connection) NetConn() any
  • func (c *Connection) Open(timeout float64) error
  • func (c *Connection) Parent() comm.Listener
  • func (c *Connection) Recv(timeout float64) ([]byte, error)
  • func (c *Connection) RecvFrom(timeout float64) ([]byte, any, error)
  • func (c *Connection) Send(data []byte, timeout float64) error
  • func (c *Connection) SendTo(data []byte, addr any, timeout float64) error
  • func (c *Connection) String() string
  • func (c *Connection) Type() string
  • func (c *Connection) Uri() string
• type Listener
  • func NewListener(uri string, commlog *logging.Logger, opts dictx.Dict) (*Listener, error)
  • func (l *Listener) IsActive() bool
  • func (l *Listener) NetListener() any
  • func (l *Listener) SetConnHandler(handler func(comm.Connection))
  • func (l *Listener) Start() error
  • func (l *Listener) Stop()
  • func (l *Listener) String() string
  • func (l *Listener) Type() string
  • func (l *Listener) Uri() string

Functions

func GetAddr

func GetAddr(network, address string) (net.Addr, error)

GetAddr returns (net.Addr) type for network and address.

func ParseUri

func ParseUri(uri string) (string, string, error)

ParseUri parses a network URI.

The expected URI format is `<network>@<host>:<port>`

<network>  {tcp|tcp4|tcp6|udp|udp4|udp6}
<host>     The host FQDN or IP address.
<port>     The port number. can be number or protocol name.

 -- see net.dial for full details.
	(referance:  https://pkg.go.dev/net#Dial)

example:
server
   - tcp@0.0.0.0:1234
   - tcp6@[::1]:1234
   - udp@0.0.0.0:http
client
   - tcp@1.2.3.4:1234
   - tcp4@1.2.3.4:1234
   - tcp6@[2001:db8::1]:http
   - udp@1.2.3.4:1234

Returns the parsed network type, address, or error for invalid URI format.

Types

type Connection

type Connection struct {

	// CommLog is the logger instance for communication data logging.
	CommLog *logging.Logger

	// PollConfig defines the read polling.
	PollConfig *comm.PollingConfig
	// KeepaliveConfig defines the keep-alive probes for TCP connections.
	KeepaliveConfig *comm.KeepaliveConfig
	// TlsConfig defines the TLS attributes for TCP connections.
	TlsConfig *comm.TlsConfig
	// contains filtered or unexported fields
}

Connection represents a network connection with event support and logging.

func NewConnection

func NewConnection(uri string, commlog *logging.Logger, opts dictx.Dict) (*Connection, error)

NewConnection creates and initializes a new Connection for the given URI.

The parsed options are:

• Polling Options: detailed in comm.ParsePollingConfig
• Keepalive Options: detailed in comm.ParseKeepaliveConfig
• TLS Options: detailed in comm.ParseTlsConfig

func (*Connection) Cancel

func (c *Connection) Cancel()

Cancel cancels any ongoing operations on the connection.

func (*Connection) CancelRecv

func (c *Connection) CancelRecv()

Cancel interrupts the ongoing receiving operation for this Connection.

func (*Connection) CancelSend

func (c *Connection) CancelSend()

Cancel interrupts the ongoing sending operation for this Connection.

func (*Connection) Close

func (c *Connection) Close()

Close shuts down the connection and cleaning up resources.

func (*Connection) IsOpened

func (c *Connection) IsOpened() bool

IsOpened indicates whether the connection is currently open and active.

func (*Connection) NetConn

func (c *Connection) NetConn() any

NetConn returns the net connection (net.Conn|net.PacketConn).

func (*Connection) Open

func (c *Connection) Open(timeout float64) error

Open establishes the connection.

func (*Connection) Parent

func (c *Connection) Parent() comm.Listener

Parent returns the parent Listener if any is associated with the Connection.

func (*Connection) Recv

func (c *Connection) Recv(timeout float64) ([]byte, error)

Recv waits for incoming data over the connection until a timeout or interrupt event occurs. Setting timeout=0 will wait indefinitely.

func (*Connection) RecvFrom

func (c *Connection) RecvFrom(timeout float64) ([]byte, any, error)

RecvFrom waits for incoming data from addr over the connection until a timeout or interrupt event occurs.

Setting timeout 0 or negative value will wait indefinitely.

func (*Connection) Send

func (c *Connection) Send(data []byte, timeout float64) error

Send transmits data over the connection, with a specified timeout.

func (*Connection) SendTo

func (c *Connection) SendTo(data []byte, addr any, timeout float64) error

SendTo transmits data to addr over the connection, with a specified timeout.

Setting timeout 0 or negative value will wait indefinitely.

func (*Connection) String

func (c *Connection) String() string

String returns a string representation of the Connection.

func (*Connection) Type

func (c *Connection) Type() string

Type returns the type of the connection as inferred from the Uri.

func (*Connection) Uri

func (c *Connection) Uri() string

Uri returns the URI of the connection

type Listener

type Listener struct {

	// ConnectionHandler defines the function to handle incoming connections.
	ConnectionHandler func(comm.Connection)

	// CommLog is the logger instance for communication data logging.
	CommLog *logging.Logger

	// PollConfig defines the read polling.
	PollConfig *comm.PollingConfig
	// LimiterConfig defines the limits for TCP connections.
	LimiterConfig *comm.LimiterConfig
	// KeepaliveConfig defines the keep-alive probes for TCP connections.
	KeepaliveConfig *comm.KeepaliveConfig
	// TlsConfig defines the TLS attributes for TCP connections.
	TlsConfig *comm.TlsConfig
	// contains filtered or unexported fields
}

Listener represents a network listener that handles incoming connections with a custom connection handler.

func NewListener

func NewListener(uri string, commlog *logging.Logger, opts dictx.Dict) (*Listener, error)

NewListener creates a new network Listener.

The parsed options are:

• Polling Options: detailed in comm.ParsePollingConfig
• Limiter Options: detailed in comm.ParseLimiterConfig
• Keepalive Options: detailed in comm.ParseKeepaliveConfig
• TLS Options: detailed in comm.ParseTlsConfig

func (*Listener) IsActive

func (l *Listener) IsActive() bool

IsActive checks if the listener is currently active.

func (*Listener) NetListener

func (l *Listener) NetListener() any

NetListener returns the net listener instance (net.Listener|net.PacketConn).

func (*Listener) SetConnHandler

func (l *Listener) SetConnHandler(handler func(comm.Connection))

SetConnHandler sets a callback function to handle connections.

func (*Listener) Start

func (l *Listener) Start() error

Start begins listening for connections, calling the connectionHandler for each established connection.

func (*Listener) Stop

func (l *Listener) Stop()

Stop gracefully shuts down the listener.

func (*Listener) String

func (l *Listener) String() string

String returns a string representation of the Listener.

func (*Listener) Type

func (l *Listener) Type() string

Type returns the type of the listener as inferred from the Uri.

func (*Listener) Uri

func (l *Listener) Uri() string

Uri returns the URI of the listener