ws

Documentation

Overview

Package ws provides a typed WebSocket hub with rooms and JSON broadcast on top of github.com/gofiber/contrib/websocket. A hub is in-memory by default; WithRedis bridges broadcasts across replicas via Redis pub/sub.

Index

• Variables
• type Conn
  • func (c *Conn[T]) Close()
  • func (c *Conn[T]) Join(room string)
  • func (c *Conn[T]) Leave(room string)
  • func (c *Conn[T]) Locals(key string) any
  • func (c *Conn[T]) Params(key string, def ...string) string
  • func (c *Conn[T]) Query(key string, def ...string) string
  • func (c *Conn[T]) Rooms() []string
  • func (c *Conn[T]) Send(msg T) error
• type Handler
• type Hub
  • func NewHub[T any](opts ...Option) *Hub[T]
  • func (h *Hub[T]) BackplaneErr() error
  • func (h *Hub[T]) Broadcast(msg T)
  • func (h *Hub[T]) Close() error
  • func (h *Hub[T]) Count() int
  • func (h *Hub[T]) Handle(cfg Handler[T]) fiber.Handler
  • func (h *Hub[T]) ToRoom(room string, msg T)
• type Option
  • func WithPingInterval(d time.Duration) Option
  • func WithRedis(r *redis.Redis, channel string) Option
  • func WithSendBuffer(n int) Option

Examples

• Hub

Variables

var ErrClosed = errors.New("ws: connection closed")

ErrClosed is returned when sending on a closed connection.

var ErrSlowClient = errors.New("ws: slow client dropped")

ErrSlowClient is returned when a connection's send buffer is full; the connection is closed and dropped.

Types

type Conn

type Conn[T any] struct {
	// contains filtered or unexported fields
}

Conn is one client connection carrying messages of type T.

func (*Conn[T]) Close

func (c *Conn[T]) Close()

Close shuts down the connection. Safe to call multiple times.

func (*Conn[T]) Join

func (c *Conn[T]) Join(room string)

Join adds the connection to a room for ToRoom fanout.

func (*Conn[T]) Leave

func (c *Conn[T]) Leave(room string)

Leave removes the connection from a room.

func (*Conn[T]) Locals

func (c *Conn[T]) Locals(key string) any

Locals returns a value stored on the request before upgrade.

func (*Conn[T]) Params

func (c *Conn[T]) Params(key string, def ...string) string

Params returns a route parameter captured at upgrade.

func (*Conn[T]) Query

func (c *Conn[T]) Query(key string, def ...string) string

Query returns a query-string value captured at upgrade.

func (*Conn[T]) Rooms

func (c *Conn[T]) Rooms() []string

Rooms returns the rooms the connection currently belongs to.

func (*Conn[T]) Send

func (c *Conn[T]) Send(msg T) error

Send JSON-encodes msg and enqueues it to this connection.

type Handler

type Handler[T any] struct {
	OnConnect    func(c *Conn[T]) error // return non-nil to reject the connection
	OnMessage    func(c *Conn[T], msg T)
	OnDisconnect func(c *Conn[T])
}

Handler holds per-connection lifecycle callbacks (all optional).

type Hub

type Hub[T any] struct {
	// contains filtered or unexported fields
}

Hub tracks connections and rooms for messages of type T.

Example

package main

import (
	"github.com/gofiber/fiber/v2"
	"github.com/rahmadafandi/fibr/ws"
)

type message struct {
	Text string `json:"text"`
}

func main() {
	hub := ws.NewHub[message]()
	app := fiber.New()
	app.Get("/ws/:room", hub.Handle(ws.Handler[message]{
		OnConnect: func(c *ws.Conn[message]) error { c.Join(c.Params("room")); return nil },
		OnMessage: func(c *ws.Conn[message], m message) { hub.ToRoom(c.Params("room"), m) },
	}))
	_ = app
}

func NewHub

func NewHub[T any](opts ...Option) *Hub[T]

NewHub creates a hub. With WithRedis it starts a backplane subscription.

func (*Hub[T]) BackplaneErr

func (h *Hub[T]) BackplaneErr() error

BackplaneErr reports a Redis backplane subscription failure, or nil if the backplane is healthy or not configured. A hub with a failed backplane still delivers to its local connections but does not fan out across replicas.

func (*Hub[T]) Broadcast

func (h *Hub[T]) Broadcast(msg T)

Broadcast sends msg to every connection (all replicas if a backplane is set).

func (*Hub[T]) Close

func (h *Hub[T]) Close() error

Close stops the backplane (if any) and closes all local connections.

func (*Hub[T]) Count

func (h *Hub[T]) Count() int

Count returns the number of local connections.

func (*Hub[T]) Handle

func (h *Hub[T]) Handle(cfg Handler[T]) fiber.Handler

Handle returns a Fiber handler that upgrades the request and runs the connection lifecycle. Mount it on a GET route.

func (*Hub[T]) ToRoom

func (h *Hub[T]) ToRoom(room string, msg T)

ToRoom sends msg to members of room (all replicas if a backplane is set).

type Option

type Option func(*hubConfig)

Option configures a Hub.

func WithPingInterval

func WithPingInterval(d time.Duration) Option

WithPingInterval sets the keepalive ping interval (default 30s; 0 disables).

func WithRedis

func WithRedis(r *redis.Redis, channel string) Option

WithRedis enables a Redis backplane so Broadcast/ToRoom reach clients on all replicas. channel is the pub/sub channel shared by every instance.

func WithSendBuffer

func WithSendBuffer(n int) Option

WithSendBuffer sets the per-connection outbound buffer (default 16).