getty

package module
v1.5.0 Latest Latest
Warning

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

 Go to latest Published: Jun 4, 2024 License: Apache-2.0 Imports: 28 Imported by: 54

README

getty

a netty like asynchronous network I/O library

Build Status codecov go.dev reference Go Report Card license

INTRO

Getty is a asynchronous network I/O library in golang. Getty works on tcp/udp/websocket network protocol and supplies a uniform interface.

In getty there are two goroutines in one connection(session), one reads tcp stream/udp packet/websocket package, the other handles logic process and writes response into network write buffer. If your logic process may take a long time, you should start a new logic process goroutine by yourself in codec.go:(Codec)OnMessage.

You can also handle heartbeat logic in codec.go:(Codec):OnCron. If you use tcp/udp, you should send hearbeat package by yourself, and then invoke session.go:(Session)UpdateActive to update its active time. Please check whether the tcp session has been timeout or not in codec.go:(Codec)OnCron by session.go:(Session)GetActive.

Whatever if you use websocket, you do not need to care about hearbeat request/response because Getty do this task in session.go:(Session)handleLoop by sending/received websocket ping/pong frames. You just need to check whether the websocket session has been timeout or not in codec.go:(Codec)OnCron by session.go:(Session)GetActive.

LICENCE

Apache License 2.0

Documentation

Index

Constants

View Source 
const (
	CompressNone            CompressType = flate.NoCompression      // 0
	CompressZip                          = flate.DefaultCompression // -1
	CompressBestSpeed                    = flate.BestSpeed          // 1
	CompressBestCompression              = flate.BestCompression    // 9
	CompressHuffman                      = flate.HuffmanOnly        // -2
	CompressSnappy                       = 10
)
View Source 
const (
	// LoggerLevelDebug DebugLevel logs are typically voluminous, and are usually disabled in
	// production.
	LoggerLevelDebug = LoggerLevel(zapcore.DebugLevel)
	// LoggerLevelInfo InfoLevel is the default logging priority.
	LoggerLevelInfo = LoggerLevel(zapcore.InfoLevel)
	// LoggerLevelWarn WarnLevel logs are more important than Infof, but don't need individual
	// human review.
	LoggerLevelWarn = LoggerLevel(zapcore.WarnLevel)
	// LoggerLevelError ErrorLevel logs are high-priority. If an application is running smoothly,
	// it shouldn't generate any error-level logs.
	LoggerLevelError = LoggerLevel(zapcore.ErrorLevel)
	// LoggerLevelDPanic DPanicLevel logs are particularly important errors. In development the
	// logger panics after writing the message.
	LoggerLevelDPanic = LoggerLevel(zapcore.DPanicLevel)
	// LoggerLevelPanic PanicLevel logs a message, then panics.
	LoggerLevelPanic = LoggerLevel(zapcore.PanicLevel)
	// LoggerLevelFatal FatalLevel logs a message, then calls os.Exit(1).
	LoggerLevelFatal = LoggerLevel(zapcore.FatalLevel)
)
View Source 
const (

	// MaxWheelTimeSpan 900s, 15 minute
	MaxWheelTimeSpan = 900e9
)

Variables

View Source 
var (
	ErrSessionClosed  = perrors.New("session Already Closed")
	ErrSessionBlocked = perrors.New("session Full Blocked")
	ErrNullPeerAddr   = perrors.New("peer address is nil")
)
View Source 
var EndPointType_name = map[int32]string{
	0: "UDP_ENDPOINT",
	1: "UDP_CLIENT",
	2: "TCP_CLIENT",
	3: "WS_CLIENT",
	4: "WSS_CLIENT",
	7: "TCP_SERVER",
	8: "WS_SERVER",
	9: "WSS_SERVER",
}
View Source 
var EndPointType_value = map[string]int32{
	"UDP_ENDPOINT": 0,
	"UDP_CLIENT":   1,
	"TCP_CLIENT":   2,
	"WS_CLIENT":    3,
	"WSS_CLIENT":   4,
	"TCP_SERVER":   7,
	"WS_SERVER":    8,
	"WSS_SERVER":   9,
}

Functions

func SetLogger added in v1.3.10 

func SetLogger(logger Logger)

SetLogger customize yourself logger.

func SetLoggerCallerDisable added in v1.3.10 

func SetLoggerCallerDisable() error

SetLoggerCallerDisable disable caller info in production env for performance improve. It is highly recommended that you execute this method in a production environment.

func SetLoggerLevel added in v1.3.10 

func SetLoggerLevel(level LoggerLevel) error

SetLoggerLevel set logger level

Types

type Client 

type Client interface {
	EndPoint
}

func NewTCPClient added in v0.8.3 

func NewTCPClient(opts ...ClientOption) Client

NewTCPClient builds a tcp client.

func NewUDPClient added in v0.8.3 

func NewUDPClient(opts ...ClientOption) Client

NewUDPClient builds a connected udp client

func NewWSClient added in v0.8.3 

func NewWSClient(opts ...ClientOption) Client

NewWSClient builds a ws client.

func NewWSSClient added in v0.8.3 

func NewWSSClient(opts ...ClientOption) Client

NewWSSClient function builds a wss client.

type ClientOption added in v0.8.3 

type ClientOption func(*ClientOptions)

func WithClientSslEnabled added in v1.3.10 

func WithClientSslEnabled(sslEnabled bool) ClientOption

WithClientSslEnabled enable use tls

func WithClientTaskPool added in v1.4.0 

func WithClientTaskPool(pool gxsync.GenericTaskPool) ClientOption

WithClientTaskPool @pool client task pool.

func WithClientTlsConfigBuilder added in v1.3.10 

func WithClientTlsConfigBuilder(tlsConfigBuilder TlsConfigBuilder) ClientOption

WithClientTlsConfigBuilder sslConfig is tls config

func WithConnectionNumber added in v0.8.3 

func WithConnectionNumber(num int) ClientOption

WithConnectionNumber @num is connection number.

func WithReconnectInterval added in v1.3.10 

func WithReconnectInterval(reconnectInterval int) ClientOption

WithReconnectInterval @reconnectInterval is server address.

func WithRootCertificateFile added in v0.8.3 

func WithRootCertificateFile(cert string) ClientOption

WithRootCertificateFile @certs is client certificate file. it can be empty.

func WithServerAddress added in v0.8.3 

func WithServerAddress(addr string) ClientOption

WithServerAddress @addr is server address.

type ClientOptions added in v0.8.3 

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

type ClientTlsConfigBuilder added in v1.3.10 

type ClientTlsConfigBuilder struct {
	ClientKeyCertChainPath        string
	ClientPrivateKeyPath          string
	ClientKeyPassword             string
	ClientTrustCertCollectionPath string
}

ClientTlsConfigBuilder impl TlsConfigBuilder for client

func (*ClientTlsConfigBuilder) BuildTlsConfig added in v1.3.10 

func (c *ClientTlsConfigBuilder) BuildTlsConfig() (*tls.Config, error)

BuildTlsConfig impl TlsConfigBuilder method

type CompressType added in v0.8.3 

type CompressType int

type Connection added in v0.8.3 

type Connection interface {
	ID() uint32
	SetCompressType(CompressType)
	LocalAddr() string
	RemoteAddr() string
	// IncReadPkgNum increases connection's read pkg number
	IncReadPkgNum()
	// IncWritePkgNum increases connection's write pkg number
	IncWritePkgNum()
	// UpdateActive update session's active time
	UpdateActive()
	// GetActive get session's active time
	GetActive() time.Time
	// ReadTimeout gets deadline for the future read calls.
	ReadTimeout() time.Duration
	// SetReadTimeout sets deadline for the future read calls.
	SetReadTimeout(time.Duration)
	// WriteTimeout gets deadline for the future write calls.
	WriteTimeout() time.Duration
	// SetWriteTimeout sets deadline for the future write calls.
	SetWriteTimeout(time.Duration)
	// Send pkg data to peer
	Send(interface{}) (int, error)
	// CloseConn close connection
	CloseConn(int)
	// SetSession sets related session
	SetSession(Session)
}

Connection wrap some connection params and operations

type EndPoint added in v0.8.3 

type EndPoint interface {
	// ID get EndPoint ID
	ID() EndPointID
	// EndPointType get endpoint type
	EndPointType() EndPointType
	// RunEventLoop run event loop and serves client request.
	RunEventLoop(newSession NewSessionCallback)
	// IsClosed check the endpoint has been closed
	IsClosed() bool
	// Close close the endpoint and free its resource
	Close()
	// GetTaskPool get task pool implemented by dubbogo/gost
	GetTaskPool() gxsync.GenericTaskPool
}

EndPoint represents the identity of the client/server

type EndPointID added in v1.3.10 

type EndPointID = int32

type EndPointType added in v0.8.3 

type EndPointType int32
const (
	UDP_ENDPOINT EndPointType = 0
	UDP_CLIENT   EndPointType = 1
	TCP_CLIENT   EndPointType = 2
	WS_CLIENT    EndPointType = 3
	WSS_CLIENT   EndPointType = 4
	TCP_SERVER   EndPointType = 7
	WS_SERVER    EndPointType = 8
	WSS_SERVER   EndPointType = 9
)

func (EndPointType) String added in v0.8.3 

func (x EndPointType) String() string

type EventListener 

type EventListener interface {
	// OnOpen invoked when session opened
	// If the return error is not nil, @Session will be closed.
	OnOpen(Session) error

	// OnClose invoked when session closed.
	OnClose(Session)

	// OnError invoked when got error.
	OnError(Session, error)

	// OnCron invoked periodically, its period can be set by (Session)SetCronPeriod
	OnCron(Session)

	// OnMessage invoked when getty received a package. Pls attention that do not handle long time
	// logic processing in this func. You'd better set the package's maximum length.
	// If the message's length is greater than it, u should should return err in
	// Reader{Read} and getty will close this connection soon.
	//
	// If ur logic processing in this func will take a long time, u should start a goroutine
	// pool(like working thread pool in cpp) to handle the processing asynchronously. Or u
	// can do the logic processing in other asynchronous way.
	// !!!In short, ur OnMessage callback func should return asap.
	//
	// If this is a udp event listener, the second parameter type is UDPContext.
	OnMessage(Session, interface{})
}

EventListener is used to process pkg that received from remote session

type Logger added in v1.3.10 

type Logger interface {
	Info(args ...interface{})
	Warn(args ...interface{})
	Error(args ...interface{})
	Debug(args ...interface{})

	Infof(fmt string, args ...interface{})
	Warnf(fmt string, args ...interface{})
	Errorf(fmt string, args ...interface{})
	Debugf(fmt string, args ...interface{})
}

Logger for user who want to customize logger of getty

func GetLogger added in v1.3.10 

func GetLogger() Logger

GetLogger get getty logger

type LoggerLevel added in v1.3.10 

type LoggerLevel int8

type NewSessionCallback 

type NewSessionCallback func(Session) error

NewSessionCallback will be invoked when server accepts a new client connection or client connects to server successfully. If there are too many client connections or u do not want to connect a server again, u can return non-nil error. And then getty will close the new session.

type PacketServer added in v1.3.10 

type PacketServer interface {
	Server
	// PacketConn get the network listener
	PacketConn() net.PacketConn
}

PacketServer is like udp listen endpoint

type ReadWriter 

type ReadWriter interface {
	Reader
	Writer
}

ReadWriter interface use for handle application packages

type Reader 

type Reader interface {
	// Read Parse tcp/udp/websocket pkg from buffer and if possible return a complete pkg.
	// When receiving a tcp network streaming segment, there are 4 cases as following:
	// case 1: a error found in the streaming segment;
	// case 2: can not unmarshal a pkg header from the streaming segment;
	// case 3: unmarshal a pkg header but can not unmarshal a pkg from the streaming segment;
	// case 4: just unmarshal a pkg from the streaming segment;
	// case 5: unmarshal more than one pkg from the streaming segment;
	//
	// The return value is (nil, 0, error) as case 1.
	// The return value is (nil, 0, nil) as case 2.
	// The return value is (nil, pkgLen, nil) as case 3.
	// The return value is (pkg, pkgLen, nil) as case 4.
	// The handleTcpPackage may invoke func Read many times as case 5.
	Read(Session, []byte) (interface{}, int, error)
}

Reader is used to unmarshal a complete pkg from buffer

type Server 

type Server interface {
	EndPoint
}

Server interface

func NewTCPServer added in v0.8.3 

func NewTCPServer(opts ...ServerOption) Server

NewTCPServer builds a tcp server.

func NewUDPEndPoint added in v1.4.6 

func NewUDPEndPoint(opts ...ServerOption) Server

NewUDPEndPoint builds a unconnected udp server.

func NewWSSServer added in v0.8.3 

func NewWSSServer(opts ...ServerOption) Server

NewWSSServer builds a secure websocket server.

func NewWSServer added in v0.8.3 

func NewWSServer(opts ...ServerOption) Server

NewWSServer builds a websocket server.

type ServerOption added in v0.8.3 

type ServerOption func(*ServerOptions)

func WithLocalAddress added in v0.8.3 

func WithLocalAddress(addr string) ServerOption

WithLocalAddress @addr server listen address.

func WithServerSslEnabled added in v1.3.10 

func WithServerSslEnabled(sslEnabled bool) ServerOption

WithServerSslEnabled enable use tls

func WithServerTaskPool added in v1.4.0 

func WithServerTaskPool(pool gxsync.GenericTaskPool) ServerOption

WithServerTaskPool @pool server task pool.

func WithServerTlsConfigBuilder added in v1.3.10 

func WithServerTlsConfigBuilder(tlsConfigBuilder TlsConfigBuilder) ServerOption

WithServerTlsConfigBuilder sslConfig is tls config

func WithWebsocketServerCert added in v0.8.3 

func WithWebsocketServerCert(cert string) ServerOption

WithWebsocketServerCert @cert: server certificate file

func WithWebsocketServerPath added in v0.8.3 

func WithWebsocketServerPath(path string) ServerOption

WithWebsocketServerPath @path: websocket request url path

func WithWebsocketServerPrivateKey added in v0.8.3 

func WithWebsocketServerPrivateKey(key string) ServerOption

WithWebsocketServerPrivateKey @key: server private key(contains its public key)

func WithWebsocketServerRootCert added in v0.8.3 

func WithWebsocketServerRootCert(cert string) ServerOption

WithWebsocketServerRootCert @cert is the root certificate file to verify the legitimacy of server

type ServerOptions added in v0.8.3 

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

type ServerTlsConfigBuilder added in v1.3.10 

type ServerTlsConfigBuilder struct {
	ServerKeyCertChainPath        string
	ServerPrivateKeyPath          string
	ServerKeyPassword             string
	ServerTrustCertCollectionPath string
}

ServerTlsConfigBuilder impl TlsConfigBuilder for server

func (*ServerTlsConfigBuilder) BuildTlsConfig added in v1.3.10 

func (s *ServerTlsConfigBuilder) BuildTlsConfig() (*tls.Config, error)

BuildTlsConfig impl TlsConfigBuilder method

type Session 

type Session interface {
	Connection
	Reset()
	Conn() net.Conn
	Stat() string
	IsClosed() bool
	// EndPoint get endpoint type
	EndPoint() EndPoint
	SetMaxMsgLen(int)
	SetName(string)
	SetEventListener(EventListener)
	SetPkgHandler(ReadWriter)
	SetReader(Reader)
	SetWriter(Writer)
	SetCronPeriod(int)
	SetWaitTime(time.Duration)
	GetAttribute(interface{}) interface{}
	SetAttribute(interface{}, interface{})
	RemoveAttribute(interface{})

	// WritePkg the Writer will invoke this function. Pls attention that if timeout is less than 0, WritePkg will send @pkg asap.
	// for udp session, the first parameter should be UDPContext.
	// totalBytesLength: @pkg stream bytes length after encoding @pkg.
	// sendBytesLength: stream bytes length that sent out successfully.
	// err: maybe it has illegal data, encoding error, or write out system error.
	WritePkg(pkg interface{}, timeout time.Duration) (totalBytesLength int, sendBytesLength int, err error)
	WriteBytes([]byte) (int, error)
	WriteBytesArray(...[]byte) (int, error)
	Close()
}

Session wrap connection between the server and the client

type StreamServer added in v1.3.10 

type StreamServer interface {
	Server
	// Listener get the network listener
	Listener() net.Listener
}

StreamServer is like tcp/websocket/wss server

type TlsConfigBuilder added in v1.3.10 

type TlsConfigBuilder interface {
	BuildTlsConfig() (*tls.Config, error)
}

TlsConfigBuilder tls config builder interface

type UDPContext added in v0.8.3 

type UDPContext struct {
	Pkg      interface{}
	PeerAddr *net.UDPAddr
}

func (UDPContext) String added in v0.8.3 

func (c UDPContext) String() string

type Writer 

type Writer interface {
	// Write if @Session is udpGettySession, the second parameter is UDPContext.
	Write(Session, interface{}) ([]byte, error)
}

Writer is used to marshal pkg and write to session

Source Files

View all Source files

Directories

Path Synopsis
benchmark
client
loop_client
server
demo
hello
hello/tcp
hello/tcp/client
hello/tcp/server
hello/tls
hello/tls/client
hello/tls/server
util
examples
echo/tcp-echo/client/app
echo/tcp-echo/server/app
echo/udp-echo/client/app
echo/udp-echo/server/app
echo/ws-echo/client/app
echo/ws-echo/server/app
echo/wss-echo/client/app
echo/wss-echo/server/app

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.