# faye/websocket-driver-ruby architecture

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

- Interactive diagram: https://gitdiagram.com/faye/websocket-driver-ruby
- Repository: https://github.com/faye/websocket-driver-ruby

## Overview

websocket-driver is a Ruby WebSocket protocol engine that separates protocol handling from TCP I/O. A consumer creates a client or server driver, supplies incoming stream bytes to it, and writes its output to the socket. Server drivers parse HTTP requests and select a protocol; client drivers perform and validate the handshake. Once open, protocol drivers encode and parse frames, reassemble messages, handle control frames and emit events. The tree and README support these capabilities; several internal protocol modules were not sampled, so their detailed wiring is omitted where uncertain.

Main entry points: [`lib/websocket/driver/client.rb`](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/client.rb) (Client Driver), [`lib/websocket/driver/server.rb`](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/server.rb) (Server Driver), [`lib/websocket/driver/hybi.rb`](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/hybi.rb) (Hybi Protocol), [`lib/websocket/driver.rb`](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver.rb) (Rack Selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Driver API"]
  node_factory["Driver Factory<br/>[driver.rb]"]
  node_server["Server Driver<br/>[server.rb]"]
  node_client["Client Driver<br/>[client.rb]"]
  node_rack_select["Rack Selection<br/>[driver.rb]"]
  node_proxy["HTTP Proxy<br/>[proxy.rb]"]
end

subgraph group_http["HTTP Handshake"]
  node_http_request["Request Parser<br/>[request.rb]"]
  node_http_response["Response Parser<br/>[response.rb]"]
  node_http_headers["HTTP Headers<br/>[headers.rb]"]
  node_driver_headers["Driver Headers<br/>[headers.rb]"]
end

subgraph group_protocol["WebSocket Protocols"]
  node_draft75["Draft 75<br/>[draft75.rb]"]
  node_draft76["Draft 76<br/>[draft76.rb]"]
  node_hybi["Hybi Protocol<br/>[hybi.rb]"]
  node_frames["Frame Codec<br/>[frame.rb]"]
  node_messages["Message Assembly<br/>[message.rb]"]
  node_mask["Payload Masking<br/>[mask.rb]"]
  node_extensions["Extensions"]
end

subgraph group_runtime["Stream Runtime"]
  node_reader["Stream Reader<br/>[stream_reader.rb]"]
  node_events["Event Emitter<br/>[event_emitter.rb]"]
end

node_consumer(("Application"))
node_socket(("TCP Socket"))

node_consumer -->|"creates driver"| node_factory
node_factory -->|"creates client"| node_client
node_factory -->|"creates server"| node_server
node_factory -->|"selects protocol"| node_rack_select
node_server -->|"parses request"| node_http_request
node_server -->|"selects protocol"| node_rack_select
node_rack_select -->|"selects RFC"| node_hybi
node_rack_select -->|"selects draft"| node_draft75
node_rack_select -->|"selects draft"| node_draft76
node_client -->|"parses response"| node_http_response
node_http_request -->|"parses headers"| node_http_headers
node_http_response -->|"parses headers"| node_http_headers
node_server -->|"sets headers"| node_driver_headers
node_client -->|"sets headers"| node_driver_headers
node_client -->|"creates proxy"| node_proxy
node_proxy -->|"writes CONNECT"| node_socket
node_client -->|"writes handshake"| node_socket
node_server -->|"writes response"| node_socket
node_socket -->|"supplies bytes"| node_server
node_socket -->|"supplies bytes"| node_client
node_client -->|"uses protocol"| node_hybi
node_hybi -->|"encodes frames"| node_frames
node_hybi -->|"assembles messages"| node_messages
node_frames -->|"masks payload"| node_mask
node_hybi -.->|"negotiates extensions"| node_extensions
node_hybi -->|"buffers stream"| node_reader
node_server -->|"emits events"| node_events
node_client -->|"emits events"| node_events
node_hybi -->|"emits events"| node_events
node_consumer -->|"provides I/O"| node_socket

click node_factory "https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver.rb"
click node_server "https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/server.rb"
click node_client "https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/client.rb"
click node_rack_select "https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver.rb"
click node_proxy "https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/proxy.rb"
click node_http_request "https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/http/request.rb"
click node_http_response "https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/http/response.rb"
click node_http_headers "https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/http/headers.rb"
click node_driver_headers "https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/headers.rb"
click node_draft75 "https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/draft75.rb"
click node_draft76 "https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/draft76.rb"
click node_hybi "https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/hybi.rb"
click node_frames "https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/hybi/frame.rb"
click node_messages "https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/hybi/message.rb"
click node_mask "https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/mask.rb"
click node_reader "https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/stream_reader.rb"
click node_events "https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/event_emitter.rb"

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_factory,node_server,node_client,node_rack_select,node_proxy toneBlue
class node_http_request,node_http_response,node_http_headers,node_driver_headers toneAmber
class node_draft75,node_draft76,node_hybi,node_frames,node_messages,node_mask,node_extensions toneMint
class node_reader,node_events toneRose
class node_consumer,node_socket toneIndigo
```

## Components

### Driver API

- [Driver Factory](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver.rb): `lib/websocket/driver.rb`
- [Server Driver](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/server.rb): `lib/websocket/driver/server.rb`
- [Client Driver](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/client.rb): `lib/websocket/driver/client.rb`
- [Rack Selection](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver.rb): `lib/websocket/driver.rb`
- [HTTP Proxy](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/proxy.rb): `lib/websocket/driver/proxy.rb`

### HTTP Handshake

- [Request Parser](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/http/request.rb): `lib/websocket/http/request.rb`
- [Response Parser](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/http/response.rb): `lib/websocket/http/response.rb`
- [HTTP Headers](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/http/headers.rb): `lib/websocket/http/headers.rb`
- [Driver Headers](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/headers.rb): `lib/websocket/driver/headers.rb`

### WebSocket Protocols

- [Draft 75](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/draft75.rb): `lib/websocket/driver/draft75.rb`
- [Draft 76](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/draft76.rb): `lib/websocket/driver/draft76.rb`
- [Hybi Protocol](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/hybi.rb): `lib/websocket/driver/hybi.rb`
- [Frame Codec](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/hybi/frame.rb): `lib/websocket/driver/hybi/frame.rb`
- [Message Assembly](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/hybi/message.rb): `lib/websocket/driver/hybi/message.rb`
- [Payload Masking](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/mask.rb): `lib/websocket/mask.rb`
- **Extensions**

### Stream Runtime

- [Stream Reader](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/stream_reader.rb): `lib/websocket/driver/stream_reader.rb`
- [Event Emitter](https://github.com/faye/websocket-driver-ruby/blob/main/lib/websocket/driver/event_emitter.rb): `lib/websocket/driver/event_emitter.rb`

### Other components

- **Application**
- **TCP Socket**

## Connections

- Application → Driver Factory: creates driver
- Driver Factory → Client Driver: creates client
- Driver Factory → Server Driver: creates server
- Driver Factory → Rack Selection: selects protocol
- Server Driver → Request Parser: parses request
- Server Driver → Rack Selection: selects protocol
- Rack Selection → Hybi Protocol: selects RFC
- Rack Selection → Draft 75: selects draft
- Rack Selection → Draft 76: selects draft
- Client Driver → Response Parser: parses response
- Request Parser → HTTP Headers: parses headers
- Response Parser → HTTP Headers: parses headers
- Server Driver → Driver Headers: sets headers
- Client Driver → Driver Headers: sets headers
- Client Driver → HTTP Proxy: creates proxy
- HTTP Proxy → TCP Socket: writes CONNECT
- Client Driver → TCP Socket: writes handshake
- Server Driver → TCP Socket: writes response
- TCP Socket → Server Driver: supplies bytes
- TCP Socket → Client Driver: supplies bytes
- Client Driver → Hybi Protocol: uses protocol
- Hybi Protocol → Frame Codec: encodes frames
- Hybi Protocol → Message Assembly: assembles messages
- Frame Codec → Payload Masking: masks payload
- Hybi Protocol → Extensions: negotiates extensions
- Hybi Protocol → Stream Reader: buffers stream
- Server Driver → Event Emitter: emits events
- Client Driver → Event Emitter: emits events
- Hybi Protocol → Event Emitter: emits events
- Application → TCP Socket: provides I/O