# gorilla/websocket architecture

> Architecture diagram of the GitHub repository gorilla/websocket, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gorilla/websocket
- Repository: https://github.com/gorilla/websocket

## Overview

Gorilla WebSocket is a Go implementation of RFC 6455. Applications initiate client connections with a Dialer or upgrade HTTP requests with an Upgrader; the resulting Conn reads and writes WebSocket messages over the network. Conn also supports JSON, joined-message readers, prepared messages, control frames, and negotiated per-message compression. The excerpts show the server-to-connection handoff and helpers delegating to Conn. Client-side construction and some internal helper wiring are only partially excerpted, so those links are omitted rather than inferred.

Main entry points: [`conn.go`](https://github.com/gorilla/websocket/blob/main/conn.go) (WebSocket Conn), [`server.go`](https://github.com/gorilla/websocket/blob/main/server.go) (HTTP Upgrader), [`prepared.go`](https://github.com/gorilla/websocket/blob/main/prepared.go) (Prepared Messages), [`json.go`](https://github.com/gorilla/websocket/blob/main/json.go) (JSON Messages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_handshake["Connection Setup"]
  node_client["Client Dialer<br/>[client.go]"]
  node_server["HTTP Upgrader<br/>[server.go]"]
  node_proxy["Proxy Dialing<br/>[proxy.go]"]
end

subgraph group_protocol["WebSocket Runtime"]
  node_conn["WebSocket Conn<br/>[conn.go]"]
  node_handshakeutil["Handshake Helpers<br/>[util.go]"]
  node_mask["Frame Masking<br/>[mask.go]"]
  node_compression["Message Compression<br/>[compression.go]"]
end

subgraph group_message["Message Features"]
  node_prepared["Prepared Messages<br/>[prepared.go]"]
  node_json["JSON Messages<br/>[json.go]"]
  node_join["Joined Messages<br/>[join.go]"]
end

node_peer(("WebSocket Peer"))

node_peer -->|"requests connection"| node_client
node_peer -->|"requests upgrade"| node_server
node_server -->|"creates connection"| node_conn
node_prepared -->|"builds frames with"| node_conn
node_json -->|"reads and writes via"| node_conn
node_join -->|"reads messages from"| node_conn
node_conn -->|"supports compression"| node_compression

click node_client "https://github.com/gorilla/websocket/blob/main/client.go"
click node_server "https://github.com/gorilla/websocket/blob/main/server.go"
click node_conn "https://github.com/gorilla/websocket/blob/main/conn.go"
click node_handshakeutil "https://github.com/gorilla/websocket/blob/main/util.go"
click node_mask "https://github.com/gorilla/websocket/blob/main/mask.go"
click node_compression "https://github.com/gorilla/websocket/blob/main/compression.go"
click node_proxy "https://github.com/gorilla/websocket/blob/main/proxy.go"
click node_prepared "https://github.com/gorilla/websocket/blob/main/prepared.go"
click node_json "https://github.com/gorilla/websocket/blob/main/json.go"
click node_join "https://github.com/gorilla/websocket/blob/main/join.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_server,node_proxy toneBlue
class node_conn,node_handshakeutil,node_mask,node_compression toneAmber
class node_prepared,node_json,node_join toneMint
class node_peer toneIndigo
```

## Components

### Connection Setup

- [Client Dialer](https://github.com/gorilla/websocket/blob/main/client.go): `client.go`
- [HTTP Upgrader](https://github.com/gorilla/websocket/blob/main/server.go): `server.go`
- [Proxy Dialing](https://github.com/gorilla/websocket/blob/main/proxy.go): `proxy.go`

### WebSocket Runtime

- [WebSocket Conn](https://github.com/gorilla/websocket/blob/main/conn.go): `conn.go`
- [Handshake Helpers](https://github.com/gorilla/websocket/blob/main/util.go): `util.go`
- [Frame Masking](https://github.com/gorilla/websocket/blob/main/mask.go): `mask.go`
- [Message Compression](https://github.com/gorilla/websocket/blob/main/compression.go): `compression.go`

### Message Features

- [Prepared Messages](https://github.com/gorilla/websocket/blob/main/prepared.go): `prepared.go`
- [JSON Messages](https://github.com/gorilla/websocket/blob/main/json.go): `json.go`
- [Joined Messages](https://github.com/gorilla/websocket/blob/main/join.go): `join.go`

### Other components

- **WebSocket Peer**

## Connections

- WebSocket Peer → Client Dialer: requests connection (evidence: `client.go`)
- WebSocket Peer → HTTP Upgrader: requests upgrade (evidence: `server.go`)
- HTTP Upgrader → WebSocket Conn: creates connection (evidence: `server.go`)
- Prepared Messages → WebSocket Conn: builds frames with (evidence: `prepared.go`)
- JSON Messages → WebSocket Conn: reads and writes via (evidence: `json.go`)
- Joined Messages → WebSocket Conn: reads messages from (evidence: `join.go`)
- WebSocket Conn → Message Compression: supports compression
