eio

Documentation

Index

• Constants
• Variables
• func GenerateBase64ID(size int) (string, error)
• type Callbacks
• type ClientConfig
• type ClientSocket
  • func Dial(rawURL string, callbacks *Callbacks, config *ClientConfig) (ClientSocket, error)
• type ClientTransport
• type CloseCallback
• type Debugger
  • func NewNoopDebugger() Debugger
  • func NewPrintDebugger() Debugger
• type ErrorCallback
• type InternalError
  • func (e InternalError) Error() string
  • func (e InternalError) Unwrap() error
• type NewSocketCallback
• type PacketCallback
• type Reason
• type Server
  • func NewServer(onSocket NewSocketCallback, config *ServerConfig) *Server
  • func (s *Server) Close() error
  • func (s *Server) HTTPWriteTimeout() time.Duration
  • func (s *Server) IsClosed() bool
  • func (s *Server) PollTimeout() time.Duration
  • func (s *Server) Run() error
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type ServerAuthFunc
• type ServerConfig
• type ServerError
  • func GetServerError(code int) (se ServerError, ok bool)
• type ServerSocket
• type ServerTransport
• type Socket

Constants

const (
	Base64IDSize   = 15
	Base64IDMaxTry = 10
)

const (
	ErrorUnknownTransport = iota
	ErrorUnknownSID
	ErrorBadHandshakeMethod
	ErrorBadRequest
	ErrorForbidden
	ErrorUnsupportedProtocolVersion
)

const (
	ProtocolVersion = parser.ProtocolVersion
)

Variables

var (
	ErrBase64IDMaxTryReached = fmt.Errorf("eio: base64 ID generation failed: base64IDMaxTry reached")
)

Functions

func GenerateBase64ID

func GenerateBase64ID(size int) (string, error)

Types

type Callbacks

type Callbacks struct {
	OnPacket PacketCallback
	OnError  ErrorCallback
	OnClose  CloseCallback
}

type ClientConfig

type ClientConfig struct {
	// Valid transports are: polling, websocket.
	//
	// Default value is: ["polling", "websocket"]
	Transports []string

	// Timeout for transport upgrade.
	// If this timeout exceeds before an upgrade takes place, Dial will return an error.
	UpgradeTimeout time.Duration

	// Additional callback to get notified about the transport upgrade.
	UpgradeDone func(transportName string)

	// This is a special data type to concurrently
	// store the additional HTTP request headers to use.
	// Values can be retrieved and changed at any time with Get, Set, Del methods.
	// Create this with transport.NewRequestHeader function.
	RequestHeader *transport.RequestHeader

	// Custom HTTP transport to use.
	//
	// If this is a http.Transport it will be cloned and timeout(s) will be set later on.
	// If not, it is the user's responsibility to set a proper timeout so when polling takes too long, we don't fail.
	HTTPTransport http.RoundTripper

	// Custom WebTransport dialer to use
	WebTransportDialer *webtransport.Dialer

	// Custom WebSocket dialer to use
	WebSocketDialOptions *websocket.DialOptions

	// For debugging purposes. Leave it nil if it is of no use.
	Debugger Debugger
}

type ClientSocket

type ClientSocket interface {
	Socket

	// Available upgrades
	Upgrades() []string
}

func Dial

func Dial(rawURL string, callbacks *Callbacks, config *ClientConfig) (ClientSocket, error)

type ClientTransport

type ClientTransport interface {
	// Name of the transport in lowercase.
	Name() string

	// This method is used for connecting to the server.
	//
	// You should receive the OPEN packet unless the transport is used for upgrade purposes.
	// If sid is set, you're upgrading to this transport. Expect an OPEN packet. (see websocket/client.go for example)
	//
	// onPacket callback must not be called in this method.
	Handshake() (hr *parser.HandshakeResponse, err error)

	// This method will be called right after the handshake is done and it will only called once, on a new goroutine.
	// Use this method to start the connection loop.
	Run()

	// If you run this method in a transport (see the close method of polling for example), call it on a new goroutine.
	// Otherwise it can call the close function recursively.
	Send(packets ...*parser.Packet)

	// This method closes the transport but doesn't call the onClose callback.
	// This method will be called after an upgrade to discard and remove this transport.
	//
	// You must make sure that this method doesn't block or recursively call itself.
	Discard()

	// This method closes the transport and calls the onClose callback.
	//
	// You must make sure that this method doesn't block or recursively call itself.
	Close()
}

type CloseCallback

type CloseCallback func(reason Reason, err error)

err can be nil. Always do a nil check.

type Debugger

type Debugger interface {
	Log(main string, v ...any)
	WithContext(context string) Debugger
	WithDynamicContext(context string, dynamicContext func() string) Debugger
}

func NewNoopDebugger

func NewNoopDebugger() Debugger

func NewPrintDebugger

func NewPrintDebugger() Debugger

type ErrorCallback

type ErrorCallback func(err error)

type InternalError

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

This is a wrapper for the errors internal to engine.io.

If you see this error, this means that the problem is neither a network error, nor an error caused by you, but the source of the error is engine.io. Open an issue on GitHub.

func (InternalError) Error

func (e InternalError) Error() string

func (InternalError) Unwrap

func (e InternalError) Unwrap() error

type NewSocketCallback

type NewSocketCallback func(socket ServerSocket) *Callbacks

type PacketCallback

type PacketCallback func(packets ...*parser.Packet)

type Reason

type Reason string

const (
	ReasonTransportError Reason = "transport error"
	ReasonTransportClose Reason = "transport close"
	ReasonForcedClose    Reason = "forced close"
	ReasonPingTimeout    Reason = "ping timeout"
	ReasonParseError     Reason = "parse error"
)

type Server

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

func NewServer

func NewServer(onSocket NewSocketCallback, config *ServerConfig) *Server

func (*Server) Close

func (s *Server) Close() error

func (*Server) HTTPWriteTimeout

func (s *Server) HTTPWriteTimeout() time.Duration

func (*Server) IsClosed

func (s *Server) IsClosed() bool

func (*Server) PollTimeout

func (s *Server) PollTimeout() time.Duration

func (*Server) Run

func (s *Server) Run() error

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

type ServerAuthFunc

type ServerAuthFunc func(w http.ResponseWriter, r *http.Request) (ok bool)

type ServerConfig

type ServerConfig struct {
	// This is a middleware function to authenticate clients before doing the handshake.
	// If this function returns false authentication will fail. Or else, the handshake will begin as usual.
	Authenticator ServerAuthFunc

	// When to send PING packets to clients.
	PingInterval time.Duration

	// After sending PING, client should send PONG before this timeout exceeds.
	PingTimeout time.Duration

	// Timeout to wait while a client transport is being upgraded.
	UpgradeTimeout time.Duration

	// MaxBufferSize is used for preventing denial of service (DOS).
	// This is the equivalent of `maxHTTPBufferSize` in original Engine.IO.
	MaxBufferSize        int64
	DisableMaxBufferSize bool

	// For accepting WebTransport connections
	WebTransportServer *webtransport.Server

	// Custom WebSocket options to use.
	WebSocketAcceptOptions *websocket.AcceptOptions

	// Callback function for Engine.IO server errors.
	// You may use this function to log server errors.
	OnError ErrorCallback

	// For debugging purposes. Leave it nil if it is of no use.
	Debugger Debugger
}

type ServerError

type ServerError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

func GetServerError

func GetServerError(code int) (se ServerError, ok bool)

type ServerSocket

type ServerSocket interface {
	Socket
}

type ServerTransport

type ServerTransport interface {
	// Name of the transport in lowercase.
	Name() string

	// handshakePacket can be nil. Do a nil check.
	// onPacket callback must not be called in this method.
	//
	// Handshake packet will either be sent via `Handshake` or `PostHandshake` but not both.
	Handshake(handshakePacket *parser.Packet, w http.ResponseWriter, r *http.Request) (sid string, err error)

	// This method is for handling an open connection (such as websocket.Conn) without closing the handshake request.
	// Currently this is only used by the websocket transport.
	//
	// Handshake packet will either be sent via `Handshake` or `PostHandshake` but not both.
	PostHandshake(handshakePacket *parser.Packet)

	// If the transport supports handling HTTP requests (after the handshake is completely done) make use of this method.
	// Otherwise, just reply with 400 (Bad request).
	ServeHTTP(w http.ResponseWriter, r *http.Request)

	// Return the packets that are waiting on the pollQueue (polling only).
	QueuedPackets() []*parser.Packet

	// If you run this method in a transport (see the close method of polling for example), call it on a new goroutine.
	// Otherwise it can call the close function recursively.
	Send(packets ...*parser.Packet)

	// This method closes the transport but doesn't call the onClose callback.
	// This method will be called after an upgrade to discard and remove this transport.
	//
	// You must make sure that this method doesn't block or recursively call itself.
	Discard()

	// This method closes the transport and calls the onClose callback.
	//
	// You must make sure that this method doesn't block or recursively call itself.
	Close()
}

type Socket

type Socket interface {
	// Session ID (sid)
	ID() string

	PingInterval() time.Duration
	PingTimeout() time.Duration

	// Name of the current transport
	TransportName() string

	Send(packets ...*parser.Packet)

	Close()
}