networking

Documentation

Index

• Constants
• Variables
• type Config
  • func NewConfig() *Config
  • func (c *Config) WithHandler(h Handler) *Config
  • func (c *Config) WithKeepAliveDisabled() *Config
  • func (c *Config) WithKeepAliveInterval(interval time.Duration) *Config
  • func (c *Config) WithProtocol(p Protocol) *Config
  • func (c *Config) WithSlogAttribute(attr slog.Attr) *Config
  • func (c *Config) WithSlogAttributes(attrs ...slog.Attr) *Config
  • func (c *Config) WithSlogHandler(handler slog.Handler) *Config
  • func (c *Config) WithWriteTimeout(timeout time.Duration) *Config
• type EndpointWriter
• type Handler
• type Handshake
• type Header
• type Network
  • func NewNetwork() *Network
  • func (n *Network) NewSession(ctx context.Context, conn io.ReadWriteCloser, conf *Config) (*Session, error)
• type Protocol
• type Session
  • func (s *Session) Close() error
  • func (s *Session) LocalAddr() net.Addr
  • func (s *Session) LocalAddrPort() netip.AddrPort
  • func (s *Session) RemoteAddr() net.Addr
  • func (s *Session) RemoteAddrPort() netip.AddrPort
  • func (s *Session) String() string
  • func (s *Session) Write(msg []byte) (int, error)

Constants

const Namespace = "NET"

Variables

var (
	// ErrInvalidConfigurationNoProtocol is used when the configuration has no protocol.
	ErrInvalidConfigurationNoProtocol = errors.New("invalid configuration: empty protocol")

	// ErrInvalidConfigurationNoHandler is used when the configuration has no handler.
	ErrInvalidConfigurationNoHandler = errors.New("invalid configuration: empty handler")

	// ErrInvalidConfigurationNoKeepAliveInterval is used when the configuration has an invalid keep-alive interval.
	ErrInvalidConfigurationNoKeepAliveInterval = errors.New("invalid configuration: invalid keep-alive interval value")

	// ErrInvalidConfigurationNoWriteTimeout is used when the configuration has an invalid write timeout.
	ErrInvalidConfigurationNoWriteTimeout = errors.New("invalid configuration: invalid write timeout value")

	// ErrUnacceptableHandshake is used when the handshake is not accepted.
	ErrUnacceptableHandshake = errors.New("handshake is not accepted")

	// ErrSessionShutdown is used if there is a shutdown during an operation.
	ErrSessionShutdown = errors.New("session shutdown")

	// ErrConnectionWriteTimeout indicates that we hit the timeout writing to the underlying stream connection.
	ErrConnectionWriteTimeout = errors.New("connection write timeout")

	// ErrKeepAliveProtocolFailure is used when the protocol failed to provide a keep-alive message.
	ErrKeepAliveProtocolFailure = errors.New("protocol failed to provide a keep-alive message")

	// ErrConnectionClosedOnRead indicates that the connection was closed while reading.
	ErrConnectionClosedOnRead = errors.New("connection closed on read")

	// ErrKeepAliveTimeout indicates that we failed to send keep-alive message and abandon a keep-alive loop.
	ErrKeepAliveTimeout = errors.New("keep-alive loop timeout")

	// ErrEmptyTimerPool is raised on creation of Session with a nil pool.
	ErrEmptyTimerPool = errors.New("empty timer pool")
)

TODO: Consider special Error type for all networking errors.

Types

type Config

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

Config allows to set some parameters of the [Conn] or it's underlying connection.

func NewConfig

func NewConfig() *Config

NewConfig creates a new Config and sets default keepAliveInterval and connectionWriteTimeout. KeepAlive is enabled by default. Protocol and Handler should be set explicitly.

func (*Config) WithHandler

func (c *Config) WithHandler(h Handler) *Config

WithHandler sets the handler.

func (*Config) WithKeepAliveDisabled

func (c *Config) WithKeepAliveDisabled() *Config

func (*Config) WithKeepAliveInterval

func (c *Config) WithKeepAliveInterval(interval time.Duration) *Config

func (*Config) WithProtocol

func (c *Config) WithProtocol(p Protocol) *Config

WithProtocol sets the protocol.

func (*Config) WithSlogAttribute

func (c *Config) WithSlogAttribute(attr slog.Attr) *Config

WithSlogAttribute adds an attribute to the slice of attributes.

func (*Config) WithSlogAttributes

func (c *Config) WithSlogAttributes(attrs ...slog.Attr) *Config

WithSlogAttributes adds given attributes to the slice of attributes.

func (*Config) WithSlogHandler

func (c *Config) WithSlogHandler(handler slog.Handler) *Config

WithSlogHandler sets the slog handler.

func (*Config) WithWriteTimeout

func (c *Config) WithWriteTimeout(timeout time.Duration) *Config

WithWriteTimeout sets connection write timeout attribute to the Config.

type EndpointWriter

type EndpointWriter interface {
	io.Writer
	RemoteAddr() net.Addr
	RemoteAddrPort() netip.AddrPort
}

EndpointWriter represents a writable endpoint that exposes the remote address in both net.Addr and netip.AddrPort formats.

type Handler

type Handler interface {
	// OnReceive is triggered when a new message is received.
	// The message is available for reading from the provided io.Reader.
	OnReceive(EndpointWriter, io.Reader)

	// OnHandshake is triggered when a valid handshake is received.
	// Called after the protocol verifies that the received handshake is acceptable.
	OnHandshake(EndpointWriter, Handshake)

	// OnHandshakeFailed is triggered when an invalid or unacceptable handshake is received.
	// Called after the protocol rejects the handshake.
	OnHandshakeFailed(EndpointWriter, Handshake)

	// OnClose is triggered when the session is closed.
	// Called when the underlying network connection is detected as closed during a read operation.
	OnClose(EndpointWriter)

	// OnFailure is triggered when a session fails due to a network error.
	// Called when an unexpected error occurs while reading from the connection or sending keep-alive messages.
	OnFailure(EndpointWriter, error)
}

Handler is an interface for handling new messages, handshakes and session close events. All handler functions are called synchronously in goroutines of internal loops. Synchronously calling functions of Session itself inside handlers may lead to deadlocks.

type Handshake

type Handshake interface {
	io.ReaderFrom
	io.WriterTo
}

Handshake is the common interface for a handshake packet.

type Header

type Header interface {
	io.ReaderFrom
	io.WriterTo
	HeaderLength() uint32
	PayloadLength() uint32
}

Header is the interface that should be implemented by the real message header packet.

type Network

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

func NewNetwork

func NewNetwork() *Network

func (*Network) NewSession

func (n *Network) NewSession(ctx context.Context, conn io.ReadWriteCloser, conf *Config) (*Session, error)

type Protocol

type Protocol interface {
	// EmptyHandshake returns the empty instance of the handshake packet.
	EmptyHandshake() Handshake

	// EmptyHeader returns the empty instance of the message header.
	EmptyHeader() Header

	// Ping return the actual ping packet.
	Ping() ([]byte, error)

	// IsAcceptableHandshake checks the handshake is acceptable.
	IsAcceptableHandshake(*Session, Handshake) bool

	// IsAcceptableMessage checks the message is acceptable by examining its header.
	// If return false, the message will be discarded.
	IsAcceptableMessage(*Session, Header) bool
}

Protocol is the interface for the network protocol implementation. It provides the methods to create the handshake packet, message header, and ping packet. It also provides the methods to validate the handshake and message header packets.

type Session

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

Session is used to wrap a reliable ordered connection.

func (*Session) Close

func (s *Session) Close() error

Close is used to close the session. It is safe to call Close multiple times from different goroutines, subsequent calls do nothing.

func (*Session) LocalAddr

func (s *Session) LocalAddr() net.Addr

LocalAddr returns the local network address.

func (*Session) LocalAddrPort

func (s *Session) LocalAddrPort() netip.AddrPort

func (*Session) RemoteAddr

func (s *Session) RemoteAddr() net.Addr

RemoteAddr returns the remote network address.

func (*Session) RemoteAddrPort

func (s *Session) RemoteAddrPort() netip.AddrPort

func (*Session) String

func (s *Session) String() string

func (*Session) Write

func (s *Session) Write(msg []byte) (int, error)

Write is used to write to the session. It is safe to call Write and/or Close concurrently.