README
¶
go-socket.io
A Socket.IO server for Go with namespaces, rooms, acknowledgements,
broadcast and a Redis adapter for multi-instance deployments. Engine.IO is included as
the engineio sub-package and can be used on its own.
This is a maintained fork of the archived googollee/go-socket.io. The modernisation
plan, including Socket.IO protocol v5 support, is in docs/ROADMAP.md.
Compatibility
| Server | Socket.IO protocol | Engine.IO protocol | JavaScript client |
|---|---|---|---|
| v1 (this module, repository root) | v4 | v3 | socket.io-client 1.x and 2.x |
v2 (in development in v2/, no runtime yet) |
v5 | v4 | socket.io-client 3.x and 4.x |
Details and deviations: docs/PROTOCOL.md.
Install
Install the maintained fork directly:
go get github.com/sshaplygin/go-socket.io@master
Earlier tags use the upstream module path; use master until a release with the
fork's module path is tagged. Existing consumers must update their imports from
github.com/googollee/go-socket.io to github.com/sshaplygin/go-socket.io and remove
the former upstream-path replace directive, then run go mod tidy.
Quick start
package main
import (
"log"
"net/http"
socketio "github.com/sshaplygin/go-socket.io"
)
func main() {
server := socketio.NewServer(nil)
server.OnConnect("/", func(s socketio.Conn) error {
s.Join("lobby")
return nil
})
// Return values are sent back to the client as the acknowledgement.
server.OnEvent("/", "msg", func(s socketio.Conn, msg string) string {
server.BroadcastToRoom("/", "lobby", "msg", msg)
return "ok"
})
server.OnDisconnect("/", func(s socketio.Conn, reason string) {
log.Println("closed:", reason)
})
go func() { log.Fatal(server.Serve()) }()
defer server.Close()
http.Handle("/socket.io/", server)
log.Fatal(http.ListenAndServe(":8000", nil))
}
Runnable examples for gin, echo, iris, gf, CORS, Redis and graceful shutdown are in _examples/. API reference: pkg.go.dev.
Contributing
See CONTRIBUTING.md for the PR process and CLAUDE.md for how to build and test.
License
BSD 3-Clause, see LICENSE.
Documentation
¶
Index ¶
- Variables
- type Broadcast
- type Client
- func (c *Client) Close() error
- func (c *Client) Connect() error
- func (c *Client) Emit(event string, args ...interface{})
- func (c *Client) OnConnect(f func(Conn) error)
- func (c *Client) OnDisconnect(f func(Conn, string))
- func (c *Client) OnError(f func(Conn, error))
- func (c *Client) OnEvent(event string, f interface{})
- type Conn
- type EachFunc
- type Namespace
- type RedisAdapterOptions
- type Server
- func (s *Server) Adapter(opts *RedisAdapterOptions) (bool, error)
- func (s *Server) BroadcastToNamespace(namespace string, event string, args ...interface{}) bool
- func (s *Server) BroadcastToRoom(namespace string, room, event string, args ...interface{}) bool
- func (s *Server) ClearRoom(namespace string, room string) bool
- func (s *Server) Close() error
- func (s *Server) Count() int
- func (s *Server) ForEach(namespace string, room string, f EachFunc) bool
- func (s *Server) JoinRoom(namespace string, room string, connection Conn) bool
- func (s *Server) LeaveAllRooms(namespace string, connection Conn) bool
- func (s *Server) LeaveRoom(namespace string, room string, connection Conn) bool
- func (s *Server) OnConnect(namespace string, f func(Conn) error)
- func (s *Server) OnDisconnect(namespace string, f func(Conn, string))
- func (s *Server) OnError(namespace string, f func(Conn, error))
- func (s *Server) OnEvent(namespace, event string, f interface{})
- func (s *Server) Remove(sid string)
- func (s *Server) RoomLen(namespace string, room string) int
- func (s *Server) Rooms(namespace string) []string
- func (s *Server) Serve() error
- func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
Constants ¶
This section is empty.
Variables ¶
var EmptyAddrErr = ErrEmptyAddr
EmptyAddrErr is the former name of ErrEmptyAddr.
Deprecated: use ErrEmptyAddr.
var ErrEmptyAddr = errors.New("empty addr")
ErrEmptyAddr is returned by NewClient when addr is empty.
var ErrWriteBufferFull = errors.New("write buffer full")
ErrWriteBufferFull is reported once, to OnError of the packet's namespace and unordered with OnDisconnect, when an Emit or a packet the library queues (an ACK or CONNECT reply) finds the outbound queue (engineio.Options.WriteBufferSize) full before any close started; a packet being written does not count. Emit never blocks: that packet and every later one are dropped and the connection is closed without draining. An overflow in root OnConnect fails the connect and is reported with a nil Conn. Packets queued faster than they are written can close a healthy client: polling writes one engine.io frame per round trip, and a packet with k binary attachments takes k+1 frames.
Functions ¶
This section is empty.
Types ¶
type Broadcast ¶
type Broadcast interface {
Join(room string, connection Conn) // Join causes the connection to join a room
Leave(room string, connection Conn) // Leave causes the connection to leave a room
LeaveAll(connection Conn) // LeaveAll causes given connection to leave all rooms
Clear(room string) // Clear causes removal of all connections from the room
Send(room, event string, args ...interface{}) // Send will send an event with args to the room
SendAll(event string, args ...interface{}) // SendAll will send an event with args to all the rooms
ForEach(room string, f EachFunc) // ForEach sends data by DataFunc, if room does not exits sends nothing
Len(room string) int // Len gives number of connections in the room
Rooms(connection Conn) []string // Gives list of all the rooms if no connection given, else list of all the rooms the connection joined
AllRooms() []string // Gives list of all the rooms the connection joined
}
Broadcast is the adaptor to handle broadcasts & rooms for socket.io server API
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is client for socket.io server
func NewClient ¶
NewClient returns a server addr like http://asd.com:8080/{$namespace}
func (*Client) Close ¶
Close closes the connection as Conn.Close does. The drain deadline is the PingTimeout of the Options passed to NewClient, not the server's value.
func (*Client) OnDisconnect ¶
OnDisconnect set a handler function f to handle disconnect event for namespace.
type Conn ¶
type Conn interface {
// Close closes the connection and returns nil; only the first close, by Close or by the library,
// has an effect. Close runs OnDisconnect for every connected namespace, leaves its rooms and
// returns without waiting. The packets queued until then, Emits from OnDisconnect included, are
// written in the background; an Emit that finds the queue full, or comes later, is dropped without
// a report. Then, or engineio.Options.PingTimeout (one minute if not positive) after Close
// started, the rest is discarded and the engine.io connection is closed; Server.Count counts the
// session until then. Incoming packets are no longer dispatched, and a read or write failure ends
// the drain at once. The library closes a connection on a read, decode, dispatch or encode error
// (an encode error used to leave it open), a peer close, a ping timeout, an overflow (see
// ErrWriteBufferFull) or a failed connect, discarding the queue at once. Other than an overflow,
// the error is reported to OnError before the close's effects run, so Emits from OnError still
// queue; a failed connect is reported to root OnError with a nil Conn. Failures during a close are
// not reported.
Close() error
Namespace
// ID returns session id
ID() string
URL() url.URL
LocalAddr() net.Addr
RemoteAddr() net.Addr
RemoteHeader() http.Header
}
Conn is a connection in go-socket.io
type Namespace ¶
type Namespace interface {
// Context of this connection. You can save one context for one
// connection, and share it between all handlers. The handlers
// are called in one goroutine, so no need to lock context if it
// only accessed in one connection.
Context() interface{}
SetContext(ctx interface{})
Namespace() string
// Emit sends eventName with arguments v to the client. If the last element of v
// is a func, it is not sent but registered as the acknowledgement callback: the
// client's ACK arguments are decoded into its parameters and it is called on the
// read goroutine of the connection. Emit never blocks: it queues the packet, and Emits
// from OnConnect are written once the writer starts. A queue already holding
// engineio.Options.WriteBufferSize packets not yet started drops the packet and every
// later one and closes the connection (see ErrWriteBufferFull). Once a close started,
// Emit drops the packet without a report, except that Close still queues packets until
// the OnDisconnect calls it runs have returned (see Conn.Close).
Emit(eventName string, v ...interface{})
Join(room string)
Leave(room string)
LeaveAll()
Rooms() []string
}
Namespace describes a communication channel that allows you to split the logic of your application over a single shared connection.
type RedisAdapterOptions ¶
type RedisAdapterOptions struct {
// deprecated. Usage Addr options
Host string
// deprecated. Usage Addr options
Port string
Addr string
Prefix string
Network string
Password string
// DB : specifies the database to select when dialing a connection.
DB int
}
RedisAdapterOptions is configuration to create new adapter
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is a go-socket.io server.
func (*Server) Adapter ¶
func (s *Server) Adapter(opts *RedisAdapterOptions) (bool, error)
Adapter sets the Redis broadcast adapter for the namespaces registered after it. A namespace builds its Redis broadcast when its first handler is registered; its two Redis connections must be dialled, AUTH and SELECT included, within 10 seconds. If that fails, the namespace keeps a no-op broadcast and the error, which names the namespace and wraps the Redis error; registering more handlers does not retry. Serve, if called before Close, returns the first such error recorded before it was called (see Serve). The Server room methods of that namespace do nothing (RoomLen returns -1, Rooms nil, the others false; ForEach does not call f). A connection to it fails before OnConnect: for the root namespace the error goes to root OnError with a nil Conn and nothing is written; for another namespace it goes to that namespace's OnError, whose Conn has no rooms, and the connection closes as on a dispatch error.
A namespace's Redis broadcast sends its subscription commands when it is built, and handler registration returns without waiting until Redis has registered that subscription. Only once Redis has registered it does the namespace on this instance receive the broadcasts and the ClearRoom, RoomLen and Rooms requests that other instances publish, and only then do their RoomLen and Rooms count it. Its own RoomLen and Rooms can miss its local connections until then too, because this instance answers its own requests through Redis. When the subscriber connection is lost, the broadcast reopens the subscription after a delay that grows while attempts fail, and the same holds again until Redis has registered the reopened subscription.
func (*Server) BroadcastToNamespace ¶
BroadcastToNamespace broadcasts given event & args to all the connections in the same namespace.
func (*Server) BroadcastToRoom ¶
BroadcastToRoom broadcasts given event & args to all the connections in the room.
func (*Server) Close ¶
Close closes the engine.io server, so Serve returns nil, and stops the Redis connections of every namespace. It does not close the sessions already open, but their broadcasts no longer reach other instances. Close waits for a handler registration that is dialling Redis, up to the 10 seconds that dial may take. With Adapter set, a namespace registered after Close has no broadcast, as if its construction failed, but Serve does not return that error.
func (*Server) LeaveAllRooms ¶
LeaveAllRooms leaves the given connection from all rooms.
func (*Server) OnDisconnect ¶
OnDisconnect set a handler function f to handle disconnect event for namespace.
func (*Server) OnEvent ¶
OnEvent sets the handler f for event in namespace.
f must be a func whose first parameter is Conn; the remaining parameters are decoded from the event arguments. If f returns values, or the client asked for an acknowledgement, the return values are sent back to the client as the ACK payload. f is called on the read goroutine of the connection, so a blocking f delays only that client. OnEvent panics if f is not a func or its first parameter is not Conn.
func (*Server) Remove ¶
Remove session from sessions pool. Fixed the sessions map leak(connections, mem).
func (*Server) RoomLen ¶
RoomLen returns the number of connections in room of namespace, or -1 when the namespace has no handler, its Redis broadcast could not be created (see Adapter), it was registered after Close with Adapter set (see Close) or a Redis command fails.
For a namespace registered after Adapter, RoomLen publishes a request that every instance subscribed to the namespace, this one included, answers through Redis with its own count, and returns the sum of the answers. It returns when an answer brings the number of answers to the number of subscribers that Redis counted before the request, and otherwise after 5 seconds with the answers received by then. It waits the full 5 seconds when this instance has not yet registered its subscription (see Adapter), because the answers do not reach it, or when an instance that Redis counts does not answer. An instance that has not registered its subscription is not counted and does not receive the request, so RoomLen returns without its connections. An instance that registers between that count and the request answers without being counted, so RoomLen can return before a counted instance has answered. In each of these cases RoomLen can return fewer connections than the room has.
func (*Server) Rooms ¶
Rooms returns the rooms of namespace that have connections, or nil when the namespace has no handler, its Redis broadcast could not be created (see Adapter) or it was registered after Close with Adapter set (see Close).
For a namespace registered after Adapter, Rooms publishes a request that every instance subscribed to the namespace, this one included, answers through Redis with its own rooms, and returns the union of the answers, or an empty list when publishing the request fails. It returns when an answer brings the number of answers to the number of subscribers that Redis counted before the request, and otherwise after 5 seconds with the answers received by then. It waits the full 5 seconds when this instance has not yet registered its subscription (see Adapter), because the answers do not reach it, when an instance that Redis counts does not answer, or when Redis cannot report that count. An instance that has not registered its subscription is not counted and does not receive the request, so Rooms returns without its rooms. An instance that registers between that count and the request answers without being counted, so Rooms can return before a counted instance has answered. In each of these cases Rooms can omit rooms that have connections.
func (*Server) Serve ¶
Serve accepts and serves connections until Close is called, then returns nil. If a namespace's Redis broadcast could not be created before Serve was called (see Adapter) and Close has not been called, Serve returns that error at once without accepting a connection. The engine.io server then still completes handshakes, which nobody serves, until Close is called.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
_examples
|
|
|
client
command
Command client joins the chat served by any of the other examples with the experimental Go client: it adds a user, sends one message, prints every chat event it receives for a second and closes.
|
Command client joins the chat served by any of the other examples with the experimental Go client: it adds a user, sends one message, prints every chat event it receives for a second and closes. |
|
_examples
command
|
|
|
internal
Package internal holds what the engineio packages share without exporting it.
|
Package internal holds what the engineio packages share without exporting it. |
|
Package logger holds the log level control shared by every package of the library and the fallback logger for packages that cannot reach engineio.Options.Logger.
|
Package logger holds the log level control shared by every package of the library and the fallback logger for packages that cannot reach engineio.Options.Logger. |