engineio

Documentation

Overview

Package engineio implements the Engine.IO server, the transport layer Socket.IO is built on. It speaks protocol revision 4 (Engine.IO v4 and above) and, when enabled, revision 3 (Engine.IO v3, used by Socket.IO v2 clients).

It only depends on the Go standard library; the WebSocket transport uses an RFC 6455 implementation that ships with this module.

Index

• Constants
• Variables
• type CORS
• type Cookie
• type Options
• type Server
  • func NewServer(opts *Options) *Server
  • func (s *Server) Close() error
  • func (s *Server) Count() int
  • func (s *Server) OnConnection(fn func(*Socket))
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Socket
  • func (s *Socket) Close()
  • func (s *Socket) ID() string
  • func (s *Socket) OnClose(fn func(reason string))
  • func (s *Socket) OnMessage(fn func(data []byte, binary bool))
  • func (s *Socket) Protocol() int
  • func (s *Socket) Send(data []byte, binary bool)
  • func (s *Socket) SendString(data string)
  • func (s *Socket) Transport() string

Constants

const (
	TransportPolling   = "polling"
	TransportWebSocket = "websocket"
)

Transport names.

const (
	DefaultPingInterval      = 25 * time.Second
	DefaultPingTimeout       = 20 * time.Second
	DefaultUpgradeTimeout    = 10 * time.Second
	DefaultMaxHTTPBufferSize = int64(1e6)
)

Defaults matching the reference implementation.

Variables

var ErrServerClosed = errors.New("engine.io: server closed")

ErrServerClosed is returned by Close when the server was already shut down.

Types

type CORS

type CORS struct {
	// AllowedOrigins lists the origins allowed to connect. The single
	// entry "*" allows every origin.
	AllowedOrigins []string
	// AllowOriginFunc, when set, decides per origin and takes precedence
	// over AllowedOrigins.
	AllowOriginFunc func(origin string) bool
	// AllowCredentials sets Access-Control-Allow-Credentials, which the
	// client needs when it is configured with `withCredentials: true`.
	AllowCredentials bool
	// AllowedHeaders defaults to the request's own
	// Access-Control-Request-Headers.
	AllowedHeaders []string
	// MaxAge is the preflight cache lifetime in seconds.
	MaxAge int
}

CORS configures the cross-origin headers added to every Engine.IO response.

A zero CORS value adds no headers at all, which is the right choice when the page and the server share an origin.

type Cookie

type Cookie struct {
	Name     string // defaults to "io"
	Path     string // defaults to "/"
	HTTPOnly bool
	Secure   bool
	SameSite string // "Lax", "Strict" or "None"; empty omits the attribute
}

Cookie configures the session cookie some deployments need for sticky load balancing. A nil *Cookie disables it.

type Options

type Options struct {
	// PingInterval is how often a heartbeat is exchanged.
	PingInterval time.Duration
	// PingTimeout is how long to wait for the peer's heartbeat reply
	// before considering the connection dead.
	PingTimeout time.Duration
	// UpgradeTimeout bounds how long a transport upgrade may take.
	UpgradeTimeout time.Duration
	// MaxHTTPBufferSize caps the size of a single message, in bytes.
	MaxHTTPBufferSize int64
	// Transports lists the enabled transports. It defaults to both
	// "polling" and "websocket".
	Transports []string
	// AllowUpgrades enables the polling-to-WebSocket upgrade. Defaults to
	// true; set DisableUpgrades to turn it off.
	DisableUpgrades bool
	// AllowEIO3 accepts Engine.IO protocol revision 3 clients, which is
	// what Socket.IO v2 clients speak.
	AllowEIO3 bool
	// CORS configures cross-origin access.
	CORS *CORS
	// Cookie enables the sticky-session cookie.
	Cookie *Cookie
	// AllowRequest can reject a handshake. Returning an error responds
	// with 403.
	AllowRequest func(r *http.Request) error
	// GenerateID produces session identifiers. It defaults to a random
	// 120-bit base64 string.
	GenerateID func(r *http.Request) (string, error)
}

Options configures a Server. The zero value is usable; every field falls back to the documented default.

type Server

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

Server accepts Engine.IO sessions over HTTP. It implements http.Handler and is safe for concurrent use.

func NewServer

func NewServer(opts *Options) *Server

NewServer returns a server configured by opts, which may be nil.

func (*Server) Close

func (s *Server) Close() error

Close ends every session and refuses new ones.

func (*Server) Count

func (s *Server) Count() int

Count returns the number of live sessions.

func (*Server) OnConnection

func (s *Server) OnConnection(fn func(*Socket))

OnConnection installs the handler run for every new session. It is called synchronously, before any packet is delivered, so it is the right place to register the session's own handlers.

func (*Server) ServeHTTP

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

ServeHTTP handles every Engine.IO request: handshakes, polls, data posts and WebSocket upgrades.

type Socket

type Socket struct {

	// Request is the HTTP request that opened the session. Its body has
	// already been consumed.
	Request *http.Request
	// URL is a copy of the handshake request's URL.
	URL *url.URL
	// Header is a copy of the handshake request's headers.
	Header http.Header
	// RemoteAddr is the peer address of the handshake request.
	RemoteAddr string
	// contains filtered or unexported fields
}

Socket is one Engine.IO session. It survives a transport upgrade, so its identity is independent of the underlying HTTP request or WebSocket.

func (*Socket) Close

func (s *Socket) Close()

Close ends the session, letting anything already queued go out first.

func (*Socket) ID

func (s *Socket) ID() string

ID returns the session identifier. Treat it as a secret: anybody holding it can take over the session.

func (*Socket) OnClose

func (s *Socket) OnClose(fn func(reason string))

OnClose installs the handler called exactly once when the session ends.

func (*Socket) OnMessage

func (s *Socket) OnMessage(fn func(data []byte, binary bool))

OnMessage installs the handler for incoming messages. Handlers run one at a time, in arrival order, on a goroutine owned by the session.

func (*Socket) Protocol

func (s *Socket) Protocol() int

Protocol reports the Engine.IO revision in use, 3 or 4.

func (*Socket) Send

func (s *Socket) Send(data []byte, binary bool)

Send queues a message for delivery.

func (*Socket) SendString

func (s *Socket) SendString(data string)

SendString queues a text message for delivery.

func (*Socket) Transport

func (s *Socket) Transport() string

Transport reports the name of the transport currently in use.