Documentation
¶
Index ¶
- Constants
- Variables
- type 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
- type Protocol
- type Session
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.
Functions ¶
This section is empty.
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 ¶
WithHandler sets the handler.
func (*Config) WithKeepAliveDisabled ¶
func (*Config) WithKeepAliveInterval ¶
func (*Config) WithProtocol ¶
WithProtocol sets the protocol.
func (*Config) WithSlogAttribute ¶
WithSlogAttribute adds an attribute to the slice of attributes.
func (*Config) WithSlogAttributes ¶
WithSlogAttributes adds given attributes to the slice of attributes.
func (*Config) WithSlogHandler ¶
WithSlogHandler sets the slog handler.
type EndpointWriter ¶
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 Network ¶
type Network struct {
// contains filtered or unexported fields
}
func NewNetwork ¶
func NewNetwork() *Network
func (*Network) NewSession ¶
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 ¶
Close is used to close the session. It is safe to call Close multiple times from different goroutines, subsequent calls do nothing.
func (*Session) LocalAddrPort ¶
func (*Session) RemoteAddr ¶
RemoteAddr returns the remote network address.
Source Files