README.md

id	websocket

Websocket

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

Compatible with Fiber v3.

Go version support

We only support the latest two versions of Go. Visit https://go.dev/doc/devel/release for more information.

Install

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

Signatures

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

Config

Property	Type	Description	Default
Next	func(fiber.Ctx) bool	Defines a function to skip this middleware when it returns true.	nil
HandshakeTimeout	time.Duration	HandshakeTimeout specifies the duration for the handshake to complete.	0 (No timeout)
Subprotocols	[]string	Subprotocols specifies the client's requested subprotocols.	nil
Origins	[]string	Allowed Origins based on the Origin header. If empty, everything is allowed.	nil
AllowEmptyOrigin	bool	Allows connections without an Origin header when Origins is configured. Useful for non-browser clients.	false
ReadBufferSize	int	ReadBufferSize specifies the I/O buffer size in bytes for incoming messages.	0 (Use default size)
WriteBufferSize	int	WriteBufferSize specifies the I/O buffer size in bytes for outgoing messages.	0 (Use default size)
WriteBufferPool	websocket.BufferPool	WriteBufferPool is a pool of buffers for write operations.	nil
EnableCompression	bool	EnableCompression specifies if the client should attempt to negotiate per message compression (RFC 7692).	false
RecoverHandler	func(*websocket.Conn)	RecoverHandler is a panic handler function that recovers from panics.	defaultRecover

Example

package main

import (
    "log"

    "github.com/gofiber/fiber/v3"
    "github.com/gofiber/contrib/v3/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 does not work with websocket middleware, please use config.RecoverHandler to add recover handler to websocket endpoints. By default, config RecoverHandler 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))

Note for WebSocket subprotocols

The config Subprotocols only helps you negotiate subprotocols and sets a Sec-Websocket-Protocol header if it has a suitable subprotocol. For more about negotiates process, check the comment for Subprotocols in fasthttp.Upgrader .

All connections will be sent to the handler function no matter whether the subprotocol negotiation is successful or not. You can get the selected subprotocol from conn.Subprotocol().

If a connection includes the Sec-Websocket-Protocol header in the request but the protocol negotiation fails, the browser will immediately disconnect the connection after receiving the upgrade response.