# Gorilla WebSocket — Production-Grade WebSocket Library for Go

> A well-tested, complete implementation of the WebSocket protocol for Go that passes the Autobahn test suite and powers real-time applications at scale.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# Gorilla WebSocket — Production-Grade WebSocket Library for Go

## Quick Use
```bash
go get github.com/gorilla/websocket
```
```go
upgrader := websocket.Upgrader{}
func handler(w http.ResponseWriter, r *http.Request) {
    conn, _ := upgrader.Upgrade(w, r, nil)
    defer conn.Close()
    for {
        _, msg, _ := conn.ReadMessage()
        conn.WriteMessage(websocket.TextMessage, msg)
    }
}
```

## 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

---
Source: https://tokrepo.com/en/workflows/gorilla-websocket-production-grade-websocket-library-go-94abdd1a
Author: AI Open Source