Skip to main content
Version: fiberi18n_v1.x.x

Websocket

Release Discord Test Security Linter

Based on Fasthttp WebSocket for Fiber with available *fiber.Ctx methods like Locals, Params, Query and Cookies.

Note: Requires Go 1.18 and above

Install

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

Signatures

func New(handler func(*websocket.Conn), config ...websocket.Config) fiber.Handler {

Config

PropertyTypeDescriptionDefault
Filterfunc(*fiber.Ctx) boolDefines a function to skip middleware.nil
HandshakeTimeouttime.DurationHandshakeTimeout specifies the duration for the handshake to complete.0 (No timeout)
Subprotocols[]stringSubprotocols specifies the client's requested subprotocols.nil
Origins[]stringAllowed Origins based on the Origin header. If empty, everything is allowed.nil
ReadBufferSizeintReadBufferSize specifies the I/O buffer size in bytes for incoming messages.0 (Use default size)
WriteBufferSizeintWriteBufferSize specifies the I/O buffer size in bytes for outgoing messages.0 (Use default size)
WriteBufferPoolwebsocket.BufferPoolWriteBufferPool is a pool of buffers for write operations.nil
EnableCompressionboolEnableCompression specifies if the client should attempt to negotiate per message compression (RFC 7692).false
RecoverHandlerfunc(*websocket.Conn) voidRecoverHandler is a panic handler function that recovers from panics.defaultRecover

Example

package main

import (
"log"

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

func main() {
app := fiber.New()

app.Use("/ws", 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
})

app.Get("/ws/:id", websocket.New(func(c *websocket.Conn) {
// c.Locals is added to the *websocket.Conn
log.Println(c.Locals("allowed")) // true
log.Println(c.Params("id")) // 123
log.Println(c.Query("v")) // 1.0
log.Println(c.Cookies("session")) // ""

// websocket.Conn bindings https://pkg.go.dev/github.com/fasthttp/websocket?tab=doc#pkg-index
var (
mt int
msg []byte
err error
)
for {
if mt, msg, err = c.ReadMessage(); err != nil {
log.Println("read:", err)
break
}
log.Printf("recv: %s", msg)

if err = c.WriteMessage(mt, msg); err != nil {
log.Println("write:", err)
break
}
}

}))

log.Fatal(app.Listen(":3000"))
// Access the websocket server: ws://localhost:3000/ws/123?v=1.0
// https://www.websocket.org/echo.html
}

Note with cache middleware

If you get the error websocket: bad handshake when using the cache middleware, please use config.Next to skip websocket path.

app := fiber.New()
app.Use(cache.New(cache.Config{
Next: func(c *fiber.Ctx) bool {
return strings.Contains(c.Route().Path, "/ws")
},
}))

app.Get("/ws/:id", websocket.New(func(c *websocket.Conn) {}))

Note with recover middleware

For internal implementation reasons, currently recover middleware is not work with websocket middleware, please use config.RecoverHandler to add recover handler to websocket endpoints. By default, config RecoverHandler is recovers from panic and writes stack trace to stderr, also returns a response that contains panic message in error field.

app := fiber.New()

app.Use(cache.New(cache.Config{
Next: func(c *fiber.Ctx) bool {
return strings.Contains(c.Route().Path, "/ws")
},
}))

cfg := Config{
RecoverHandler: func(conn *Conn) {
if err := recover(); err != nil {
conn.WriteJSON(fiber.Map{"customError": "error occurred"})
}
},
}

app.Get("/ws/:id", websocket.New(func(c *websocket.Conn) {}, cfg))