https://github.com/ratopi/websocket-cowboy-experiments
WebSocketCowboyGunExperiments
https://github.com/ratopi/websocket-cowboy-experiments
cowboy erlang gun websocket
Last synced: 4 days ago
JSON representation
WebSocketCowboyGunExperiments
- Host: GitHub
- URL: https://github.com/ratopi/websocket-cowboy-experiments
- Owner: ratopi
- License: mit
- Created: 2025-06-04T22:08:29.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2026-03-07T15:35:37.000Z (4 months ago)
- Last Synced: 2026-03-07T21:46:55.862Z (4 months ago)
- Topics: cowboy, erlang, gun, websocket
- Language: Erlang
- Homepage:
- Size: 13.7 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# WebSocket-Cowboy-Gun-Experiments
A minimal Erlang/OTP playground for WebSocket communication using [Cowboy](https://github.com/ninenines/cowboy) (server) and [Gun](https://github.com/ninenines/gun) (client).
## What is this?
This project demonstrates how to set up a WebSocket server and client in Erlang using the Cowboy/Gun ecosystem from Nine Nines. It consists of two independent OTP applications:
- **`wss/`** – WebSocket **server** built with Cowboy. Accepts WebSocket connections on `/ws`, sends a welcome message, echoes text frames back, and handles ping/pong.
- **`wsc/`** – WebSocket **client** built with Gun. Connects to the server asynchronously, sends periodic pings, and logs received messages.
## Prerequisites
- Erlang/OTP 25+
- [rebar3](https://rebar3.org/)
## Usage
**1. Start the server:**
```sh
cd wss
rebar3 shell
```
The server listens on port `10101` by default (configurable via `application:set_env(wss, port, 12345)`).
**2. Start the client** (in a separate shell):
```sh
cd wsc
rebar3 shell
```
The client connects to `localhost:10101` by default. Host and port are configurable:
```erlang
application:set_env(wsc, host, "example.com").
application:set_env(wsc, port, 12345).
```
## Configuration
Both apps read their settings from the OTP application environment:
| App | Key | Default | Description |
|-------|--------|---------------|----------------------------|
| `wss` | `port` | `10101` | Server listen port |
| `wsc` | `host` | `"localhost"` | Server hostname to connect |
| `wsc` | `port` | `10101` | Server port to connect |
## Project Structure
```
├── wss/ WebSocket server (Cowboy)
│ └── src/
│ ├── wss_app.erl Application entry point
│ ├── wss_sup.erl Supervisor
│ ├── wss_cowboy.erl Cowboy listener setup
│ └── wss_ws.erl WebSocket handler
│
├── wsc/ WebSocket client (Gun)
│ └── src/
│ ├── wsc_app.erl Application entry point
│ ├── wsc_sup.erl Supervisor
│ └── wsc_client.erl gen_server with async WebSocket client
```
## License
MIT