socketio

README

id: socketio

Socket.io

WebSocket wrapper for Fiber with events support and inspired by Socket.io

Note: Requires Go 1.20 and above

Install

go get -u github.com/gofiber/fiber/v2
go get -u github.com/gofiber/contrib/socketio

Signatures

// Initialize new socketio in the callback this will
// execute a callback that expects kws *Websocket Object
// and optional config websocket.Config
func New(callback func(kws *Websocket), config ...websocket.Config) func(*fiber.Ctx) error

// Add listener callback for an event into the listeners list
func On(event string, callback func(payload *EventPayload))

// Emit the message to a specific socket uuids list
// Ignores all errors
func EmitToList(uuids []string, message []byte)

// Emit to a specific socket connection
func EmitTo(uuid string, message []byte) error

// Broadcast to all the active connections
// except avoid broadcasting the message to itself
func Broadcast(message []byte)

// Fire custom event on all connections
func Fire(event string, data []byte) 

Example

package main

import (
    "encoding/json"
    "fmt"
    "log"

    "github.com/gofiber/contrib/socketio"
    "github.com/gofiber/contrib/websocket"
    "github.com/gofiber/fiber/v2"
)

// MessageObject Basic chat message object
type MessageObject struct {
    Data  string `json:"data"`
    From  string `json:"from"`
    Event string `json:"event"`
    To    string `json:"to"`
}

func main() {

    // The key for the map is message.to
    clients := make(map[string]string)

    // Start a new Fiber application
    app := fiber.New()

    // Setup the middleware to retrieve the data sent in first GET request
    app.Use(func(c *fiber.Ctx) error {
        // IsWebSocketUpgrade returns true if the client
        // requested upgrade to the WebSocket protocol.
        if websocket.IsWebSocketUpgrade(c) {
            c.Locals("allowed", true)
            return c.Next()
        }
        return fiber.ErrUpgradeRequired
    })

    // Multiple event handling supported
    socketio.On(socketio.EventConnect, func(ep *socketio.EventPayload) {
        fmt.Printf("Connection event 1 - User: %s", ep.Kws.GetStringAttribute("user_id"))
    })

    // Custom event handling supported
    socketio.On("CUSTOM_EVENT", func(ep *socketio.EventPayload) {
        fmt.Printf("Custom event - User: %s", ep.Kws.GetStringAttribute("user_id"))
        // --->

        // DO YOUR BUSINESS HERE

        // --->
    })

    // On message event
    socketio.On(socketio.EventMessage, func(ep *socketio.EventPayload) {

        fmt.Printf("Message event - User: %s - Message: %s", ep.Kws.GetStringAttribute("user_id"), string(ep.Data))

        message := MessageObject{}

        // Unmarshal the json message
        // {
        //  "from": "<user-id>",
        //  "to": "<recipient-user-id>",
        //  "event": "CUSTOM_EVENT",
        //  "data": "hello"
        //}
        err := json.Unmarshal(ep.Data, &message)
        if err != nil {
            fmt.Println(err)
            return
        }

        // Fire custom event based on some
        // business logic
        if message.Event != "" {
            ep.Kws.Fire(message.Event, []byte(message.Data))
        }

        // Emit the message directly to specified user
        err = ep.Kws.EmitTo(clients[message.To], ep.Data, socketio.TextMessage)
        if err != nil {
            fmt.Println(err)
        }
    })

    // On disconnect event
    socketio.On(socketio.EventDisconnect, func(ep *socketio.EventPayload) {
        // Remove the user from the local clients
        delete(clients, ep.Kws.GetStringAttribute("user_id"))
        fmt.Printf("Disconnection event - User: %s", ep.Kws.GetStringAttribute("user_id"))
    })

    // On close event
    // This event is called when the server disconnects the user actively with .Close() method
    socketio.On(socketio.EventClose, func(ep *socketio.EventPayload) {
        // Remove the user from the local clients
        delete(clients, ep.Kws.GetStringAttribute("user_id"))
        fmt.Printf("Close event - User: %s", ep.Kws.GetStringAttribute("user_id"))
    })

    // On error event
    socketio.On(socketio.EventError, func(ep *socketio.EventPayload) {
        fmt.Printf("Error event - User: %s", ep.Kws.GetStringAttribute("user_id"))
    })

    app.Get("/ws/:id", socketio.New(func(kws *socketio.Websocket) {

        // Retrieve the user id from endpoint
        userId := kws.Params("id")

        // Add the connection to the list of the connected clients
        // The UUID is generated randomly and is the key that allow
        // socketio to manage Emit/EmitTo/Broadcast
        clients[userId] = kws.UUID

        // Every websocket connection has an optional session key => value storage
        kws.SetAttribute("user_id", userId)

        //Broadcast to all the connected users the newcomer
        kws.Broadcast([]byte(fmt.Sprintf("New user connected: %s and UUID: %s", userId, kws.UUID)), true, socketio.TextMessage)
        //Write welcome message
        kws.Emit([]byte(fmt.Sprintf("Hello user: %s with UUID: %s", userId, kws.UUID)), socketio.TextMessage)
    }))

    log.Fatal(app.Listen(":3000"))
}

---

Supported events

Const	Event	Description
EventMessage	message	Fired when a Text/Binary message is received
EventPing	ping	More details here
EventPong	pong	Refer to ping description
EventDisconnect	disconnect	Fired on disconnection. The error provided in disconnection event as defined in RFC 6455, section 11.7.
EventConnect	connect	Fired on first connection
EventClose	close	Fired when the connection is actively closed from the server. Different from client disconnection
EventError	error	Fired when some error appears useful also for debugging websockets

Event Payload object

Variable	Type	Description
Kws	*Websocket	The connection object
Name	string	The name of the event
SocketUUID	string	Unique connection UUID
SocketAttributes	map[string]string	Optional websocket attributes
Error	error	(optional) Fired from disconnection or error events
Data	[]byte	Data used on Message and on Error event, contains the payload for custom events

Socket instance functions

Name	Type	Description
SetAttribute	void	Set a specific attribute for the specific socket connection
GetUUID	string	Get socket connection UUID
SetUUID	error	Set socket connection UUID
GetAttribute	string	Get a specific attribute from the socket attributes
EmitToList	void	Emit the message to a specific socket uuids list
EmitTo	error	Emit to a specific socket connection
Broadcast	void	Broadcast to all the active connections except broadcasting the message to itself
Fire	void	Fire custom event
Emit	void	Emit/Write the message into the given connection
Close	void	Actively close the connection from the server

Note: the FastHTTP connection can be accessed directly from the instance

kws.Conn

Documentation

Index

• Constants
• Variables
• func Broadcast(message []byte, mType ...int)
• func EmitTo(uuid string, message []byte, mType ...int) error
• func EmitToList(uuids []string, message []byte, mType ...int)
• func Fire(event string, data []byte)
• func New(callback func(kws *Websocket), config ...websocket.Config) func(*fiber.Ctx) error
• func On(event string, callback eventCallback)
• type EventPayload
• type Websocket
  • func (kws *Websocket) Broadcast(message []byte, except bool, mType ...int)
  • func (kws *Websocket) Close()
  • func (kws *Websocket) Emit(message []byte, mType ...int)
  • func (kws *Websocket) EmitTo(uuid string, message []byte, mType ...int) error
  • func (kws *Websocket) EmitToList(uuids []string, message []byte, mType ...int)
  • func (kws *Websocket) Fire(event string, data []byte)
  • func (kws *Websocket) GetAttribute(key string) interface{}
  • func (kws *Websocket) GetIntAttribute(key string) int
  • func (kws *Websocket) GetStringAttribute(key string) string
  • func (kws *Websocket) GetUUID() string
  • func (kws *Websocket) IsAlive() bool
  • func (kws *Websocket) SetAttribute(key string, attribute interface{})
  • func (kws *Websocket) SetUUID(uuid string) error

Constants

const (
	// TextMessage denotes a text data message. The text message payload is
	// interpreted as UTF-8 encoded text data.
	TextMessage = 1
	// BinaryMessage denotes a binary data message.
	BinaryMessage = 2
	// CloseMessage denotes a close control message. The optional message
	// payload contains a numeric code and text. Use the FormatCloseMessage
	// function to format a close message payload.
	CloseMessage = 8
	// PingMessage denotes a ping control message. The optional message payload
	// is UTF-8 encoded text.
	PingMessage = 9
	// PongMessage denotes a pong control message. The optional message payload
	// is UTF-8 encoded text.
	PongMessage = 10
)

Source @url:https://github.com/gorilla/websocket/blob/master/conn.go#L61 The message types are defined in RFC 6455, section 11.8.

const (
	// EventMessage Fired when a Text/Binary message is received
	EventMessage = "message"
	// EventPing More details here:
	// @url https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#Pings_and_Pongs_The_Heartbeat_of_WebSockets
	EventPing = "ping"
	EventPong = "pong"
	// EventDisconnect Fired on disconnection
	// The error provided in disconnection event
	// is defined in RFC 6455, section 11.7.
	// @url https://github.com/gofiber/websocket/blob/cd4720c435de415b864d975a9ca23a47eaf081ef/websocket.go#L192
	EventDisconnect = "disconnect"
	// EventConnect Fired on first connection
	EventConnect = "connect"
	// EventClose Fired when the connection is actively closed from the server
	EventClose = "close"
	// EventError Fired when some error appears useful also for debugging websockets
	EventError = "error"
)

Supported event list

Variables

var (
	// ErrorInvalidConnection The addressed Conn connection is not available anymore
	// error data is the uuid of that connection
	ErrorInvalidConnection = errors.New("message cannot be delivered invalid/gone connection")
	// ErrorUUIDDuplication The UUID already exists in the pool
	ErrorUUIDDuplication = errors.New("UUID already exists in the available connections pool")
)

var (
	PongTimeout = 1 * time.Second
	// RetrySendTimeout retry after 20 ms if there is an error
	RetrySendTimeout = 20 * time.Millisecond
	//MaxSendRetry define max retries if there are socket issues
	MaxSendRetry = 5
	// ReadTimeout Instead of reading in a for loop, try to avoid full CPU load taking some pause
	ReadTimeout = 10 * time.Millisecond
)

Functions

func Broadcast

func Broadcast(message []byte, mType ...int)

Broadcast to all the active connections

func EmitTo

func EmitTo(uuid string, message []byte, mType ...int) error

EmitTo Emit to a specific socket connection

func EmitToList

func EmitToList(uuids []string, message []byte, mType ...int)

EmitToList Emit the message to a specific socket uuids list Ignores all errors

func Fire

func Fire(event string, data []byte)

Fire custom event on all connections

func New

func New(callback func(kws *Websocket), config ...websocket.Config) func(*fiber.Ctx) error

func On

func On(event string, callback eventCallback)

On Add listener callback for an event into the listeners list

Types

type EventPayload

type EventPayload struct {
	// The connection object
	Kws *Websocket
	// The name of the event
	Name string
	// Unique connection UUID
	SocketUUID string
	// Optional websocket attributes
	SocketAttributes map[string]any
	// Optional error when are fired events like
	// - Disconnect
	// - Error
	Error error
	// Data is used on Message and on Error event
	Data []byte
}

EventPayload Event Payload is the object that stores all the information about the event and the connection

type Websocket

type Websocket struct {

	// The Fiber.Websocket connection
	Conn *websocket.Conn

	// Unique id of the connection
	UUID string
	// Wrap Fiber Locals function
	Locals func(key string) interface{}
	// Wrap Fiber Params function
	Params func(key string, defaultValue ...string) string
	// Wrap Fiber Query function
	Query func(key string, defaultValue ...string) string
	// Wrap Fiber Cookies function
	Cookies func(key string, defaultValue ...string) string
	// contains filtered or unexported fields
}

func (*Websocket) Broadcast

func (kws *Websocket) Broadcast(message []byte, except bool, mType ...int)

Broadcast to all the active connections except avoid broadcasting the message to itself

func (*Websocket) Close

func (kws *Websocket) Close()

Close Actively close the connection from the server

func (*Websocket) Emit

func (kws *Websocket) Emit(message []byte, mType ...int)

Emit /Write the message into the given connection

func (*Websocket) EmitTo

func (kws *Websocket) EmitTo(uuid string, message []byte, mType ...int) error

EmitTo Emit to a specific socket connection

func (*Websocket) EmitToList

func (kws *Websocket) EmitToList(uuids []string, message []byte, mType ...int)

EmitToList Emit the message to a specific socket uuids list

func (*Websocket) Fire

func (kws *Websocket) Fire(event string, data []byte)

Fire custom event

func (*Websocket) GetAttribute

func (kws *Websocket) GetAttribute(key string) interface{}

GetAttribute Get a specific attribute from the socket attributes

func (*Websocket) GetIntAttribute

func (kws *Websocket) GetIntAttribute(key string) int

GetIntAttribute Convenience method to retrieve an attribute as an int. Will panic if attribute is not an int.

func (*Websocket) GetStringAttribute

func (kws *Websocket) GetStringAttribute(key string) string

GetStringAttribute Convenience method to retrieve an attribute as a string.

func (*Websocket) GetUUID

func (kws *Websocket) GetUUID() string

func (*Websocket) IsAlive

func (kws *Websocket) IsAlive() bool

func (*Websocket) SetAttribute

func (kws *Websocket) SetAttribute(key string, attribute interface{})

SetAttribute Set a specific attribute for the specific socket connection

func (*Websocket) SetUUID

func (kws *Websocket) SetUUID(uuid string) error