Gorilla WebSocket — Production-Grade WebSocket Library for Go

Introduction

Gorilla WebSocket is the most widely used WebSocket package in the Go ecosystem. It provides a complete and tested implementation of the RFC 6455 WebSocket protocol, handling connection upgrades, message framing, ping/pong, and close handshakes correctly so developers can focus on application-level messaging.

What Gorilla WebSocket Does

• Implements full RFC 6455 WebSocket protocol including extensions
• Handles HTTP-to-WebSocket upgrade with origin checking and subprotocol negotiation
• Supports text and binary message types with streaming reader/writer interfaces
• Manages ping/pong frames and connection health automatically
• Provides concurrent-safe write with configurable buffer sizes

Architecture Overview

The library centers on the Conn type, created by upgrading an HTTP connection via the Upgrader. Once upgraded, Conn provides ReadMessage/WriteMessage for simple use cases and NextReader/NextWriter for streaming large messages. The design keeps the framing protocol internal and exposes clean message-level abstractions. Connection lifecycle is managed through close handlers and deadline settings.

Self-Hosting & Configuration

• Install: go get github.com/gorilla/websocket
• Create an Upgrader with CheckOrigin function for security
• Call Upgrade() in your HTTP handler to obtain a *websocket.Conn
• Set read/write deadlines and buffer sizes via Upgrader or Conn methods
• Use SetPingHandler/SetPongHandler for custom keep-alive logic

Key Features

• Passes the Autobahn WebSocket compliance test suite completely
• Supports compression via per-message deflate extension (RFC 7692)
• Provides both simple message API and streaming io.Reader/io.Writer interface
• Works seamlessly with net/http, Gin, Echo, Chi, and other Go routers
• Minimal dependencies with zero CGO requirements

Comparison with Similar Tools

• nhooyr/websocket — newer alternative with context support; Gorilla has broader ecosystem adoption and battle-testing
• gobwas/ws — zero-allocation focus for extreme performance; Gorilla offers simpler API for typical use cases
• net/websocket (x/net) — deprecated and incomplete; Gorilla is the recommended replacement
• Centrifugo — full real-time server; Gorilla is a low-level library you build upon
• Socket.IO (Go) — higher-level protocol with rooms/namespaces; Gorilla is raw WebSocket

FAQ

Q: Is Gorilla WebSocket still maintained? A: The repository is in maintenance mode with security fixes. The API is stable and production-ready.

Q: Is it safe to write from multiple goroutines? A: No. Concurrent writes require a mutex or channel. Reads and writes can happen concurrently on separate goroutines.

Q: How do I handle connection drops? A: Set read deadlines and use ping/pong handlers. When ReadMessage returns an error, the connection is dead.

Q: Can I use it with TLS? A: Yes. Run your HTTP server with TLS (wss://) and Gorilla handles the upgraded connection transparently.

Sources

• https://github.com/gorilla/websocket
• https://pkg.go.dev/github.com/gorilla/websocket