websocket

Documentation

Overview

Package websocket provides WebSocket support for zerohttp.

This package defines interfaces for WebSocket connections and upgraders. Users bring their own WebSocket library (e.g., github.com/gorilla/websocket) by implementing the Connection and Upgrader interfaces.

Usage

Configure zerohttp with your WebSocket upgrader:

import (
    zh "github.com/alexferl/zerohttp"
    "github.com/alexferl/zerohttp/extensions/websocket"
    gorillaws "github.com/gorilla/websocket"
)

// Create an adapter for gorilla/websocket
type GorillaUpgrader struct {
    upgrader gorillaws.Upgrader
}

func (u *GorillaUpgrader) Upgrade(w http.ResponseWriter, r *http.Request) (websocket.Connection, error) {
    conn, err := u.upgrader.Upgrade(w, r, nil)
    // Wrap conn in a type that implements websocket.Connection...
}

app := zh.New(zh.Config{
    WebSocketUpgrader: &GorillaUpgrader{},
})

app.GET("/ws", zh.HandlerFunc(func(w http.ResponseWriter, r *http.Request) error {
    conn, err := app.WebSocketUpgrader().Upgrade(w, r)
    if err != nil {
        return err
    }
    defer conn.Close()

    // Handle WebSocket connection
    for {
        mt, msg, err := conn.ReadMessage()
        if err != nil {
            return err
        }
        // Process message...
    }
}))

Close Codes

The package provides RFC 6455 standard close codes:

websocket.CloseNormalClosure      // 1000 - Normal closure
websocket.CloseGoingAway          // 1001 - Endpoint going away
websocket.CloseProtocolError      // 1002 - Protocol error
websocket.CloseUnsupportedData    // 1003 - Unsupported data
websocket.CloseMessageTooBig      // 1009 - Message too big
websocket.CloseInternalServerErr  // 1011 - Server error

Use IsCloseError to check for specific close codes:

if websocket.IsCloseError(err, websocket.CloseNormalClosure, websocket.CloseGoingAway) {
    // Client disconnected normally
}

Index

• func IsCloseError(err error, codes ...int) bool
• func IsUnexpectedCloseError(err error, expectedCodes ...int) bool
• type CloseCode
• type CloseError
  • func (e *CloseError) Error() string
• type Connection
• type MessageType
• type Upgrader

Functions

func IsCloseError

func IsCloseError(err error, codes ...int) bool

IsCloseError returns true if the error is a WebSocket close error with one of the specified codes.

func IsUnexpectedCloseError

func IsUnexpectedCloseError(err error, expectedCodes ...int) bool

IsUnexpectedCloseError returns true if the error is a close error with a code not in the expected list.

Types

type CloseCode

type CloseCode int

CloseCode represents a WebSocket close code as defined in RFC 6455.

const (
	CloseNormalClosure           CloseCode = 1000
	CloseGoingAway               CloseCode = 1001
	CloseProtocolError           CloseCode = 1002
	CloseUnsupportedData         CloseCode = 1003
	CloseNoStatusReceived        CloseCode = 1005
	CloseAbnormalClosure         CloseCode = 1006
	CloseInvalidFramePayloadData CloseCode = 1007
	ClosePolicyViolation         CloseCode = 1008
	CloseMessageTooBig           CloseCode = 1009
	CloseMandatoryExtension      CloseCode = 1010
	CloseInternalServerErr       CloseCode = 1011
	CloseServiceRestart          CloseCode = 1012
	CloseTryAgainLater           CloseCode = 1013
	CloseBadGateway              CloseCode = 1014
	CloseTLSHandshake            CloseCode = 1015
)

WebSocket close code constants.

type CloseError

type CloseError struct {
	Code   int
	Reason string
}

CloseError represents a WebSocket close error.

func (*CloseError) Error

func (e *CloseError) Error() string

Error implements the error interface.

type Connection

type Connection interface {
	// ReadMessage reads a message from the connection.
	// Returns message type (text=1, binary=2), payload, and error.
	ReadMessage() (int, []byte, error)

	// WriteMessage writes a message to the connection.
	// messageType is 1 for text, 2 for binary.
	WriteMessage(messageType int, data []byte) error

	// Close closes the connection gracefully.
	Close() error

	// RemoteAddr returns the remote network address.
	RemoteAddr() net.Addr
}

Connection represents a WebSocket connection. This is a minimal interface that can be implemented by wrapping any WebSocket library (e.g., gorilla/websocket, nhooyr/websocket).

type MessageType

type MessageType int

MessageType represents the type of WebSocket message.

const (
	TextMessage   MessageType = 1
	BinaryMessage MessageType = 2
	CloseMessage  MessageType = 8
	PingMessage   MessageType = 9
	PongMessage   MessageType = 10
)

WebSocket message type constants as defined in RFC 6455.

type Upgrader

type Upgrader interface {
	// Upgrade upgrades the HTTP connection to WebSocket.
	// The implementation is responsible for the RFC 6455 handshake
	// and returning a Connection.
	Upgrade(w http.ResponseWriter, r *http.Request) (Connection, error)
}

Upgrader handles upgrading HTTP connections to WebSocket. Users provide their own implementation using their preferred WebSocket library.