# Configurable WebSocket Transport Parameters and Rate Limits in TREK

> Learn about TREK's five tunable WebSocket settings for payload size, origin filtering, and message throttling. Configure WebSocket transport parameters and rate limits via environment variables or compile-time constants for opt...

- Repository: [Maurice/TREK](https://github.com/mauriceboe/TREK)
- Tags: how-to-guide
- Published: 2026-07-01

---

**TREK exposes five tunable WebSocket settings—including payload size, origin filtering, and per-connection message throttling—through environment variables and compile-time constants in [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts).**

TREK’s real-time communication layer is built on the `ws` library, with transport behavior and security constraints centralized in a single module. Understanding these **configurable WebSocket transport parameters and rate limits** allows operators to harden deployments against abuse or scale throughput for high-traffic scenarios.

---

## WebSocket Transport Parameters

The `setupWebSocket` function in [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts) initializes the server with a concise set of transport options that govern how connections are established and maintained.

### Connection Path and Payload Size

By default, the server mounts the WebSocket endpoint at `/ws` and caps individual message size at **64 KB**. These values are passed directly to the underlying `ws` constructor.

- **`path`**: Fixed at `/ws` (line 40).
- **`maxPayload`**: Set to `64 * 1024` bytes (line 41).

To change the payload limit, edit the `maxPayload` option in `setupWebSocket`:

```typescript
// server/src/websocket.ts
const wss = new WebSocketServer({
  path: '/ws',
  maxPayload: 128 * 1024, // Increase to 128 KB
  // ... other options
});

```

### Origin Validation

TREK supports strict origin whitelisting via the `ALLOWED_ORIGINS` environment variable. When this variable is set to a comma-separated list of origins, the server validates the `Origin` header against the list inside the `verifyClient` callback (lines 33–46).

If the header does not match an allowed entry, the handshake is rejected before the connection upgrades.

```bash

# .env

ALLOWED_ORIGINS=https://app.trek.io,https://admin.trek.io

```

When `ALLOWED_ORIGINS` is omitted, the server accepts connections from any origin.

### Heartbeat Keep-Alive

To detect stale connections, the server emits an automatic **ping every 30 seconds**. The interval is controlled by the hard-coded constant `HEARTBEAT_INTERVAL` defined near line 49.

```typescript
// server/src/websocket.ts (near line 49)
const HEARTBEAT_INTERVAL = 30000; // milliseconds

```

There is no runtime toggle for this value; it requires a source modification and redeployment.

---

## Rate Limiting and Per-Connection Throttling

TREK implements a sliding-window rate limiter to prevent individual sockets from flooding the broadcast layer. The logic resides inside the `message` event handler and references two constants declared at the top of [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts):

- **`WS_MSG_LIMIT`**: Maximum messages allowed within the window (default **30**).
- **`WS_MSG_WINDOW`**: Time window in milliseconds (default **10,000**).

When a client exceeds 30 messages in a 10-second window, the server emits an error payload to that specific socket and silently discards further inbound messages until the window slides forward.

These thresholds are suited for standard trip-update traffic but can be adjusted for high-frequency telemetry:

```typescript
// server/src/websocket.ts (lines 27-28)
const WS_MSG_LIMIT = 100;    // Allow 100 messages
const WS_MSG_WINDOW = 5000;  // Per 5 seconds

```

---

## Practical Configuration Examples

### Restricting Origins via Environment Variable

Deploy the server with a strict origin policy to prevent unauthorized browser clients from connecting:

```bash
export ALLOWED_ORIGINS=https://trek.example.com
npm start

```

### Tuning Rate Limits for High-Traffic Deployments

For fleet-tracking scenarios that emit frequent GPS updates, increase the constants in the source:

```typescript
// server/src/websocket.ts
const WS_MSG_LIMIT = 200;
const WS_MSG_WINDOW = 10000;

```

### Client Connection Handling

Clients receive a welcome payload containing their assigned socket ID upon successful connection:

```javascript
const ws = new WebSocket('wss://api.trek.app/ws?token=' + jwtToken);

ws.addEventListener('message', (event) => {
  const payload = JSON.parse(event.data);
  if (payload.type === 'welcome') {
    console.log('Connected with socket ID:', payload.socketId);
  }
});

```

### Broadcasting with Room Isolation

Server-side code can emit events to all participants in a specific trip room while excluding the originating socket to prevent echo:

```typescript
import { broadcast } from './websocket';

broadcast(tripId, 'tripUpdated', { updatedAt: Date.now() }, originatingSocketId);

```

---

## Summary

- **Path and payload**: The endpoint is fixed at `/ws` with a 64 KB default payload cap, adjustable in `setupWebSocket`.
- **Origin control**: Set `ALLOWED_ORIGINS` to a comma-separated list to enforce CORS-style validation during the handshake.
- **Heartbeat**: A 30-second ping interval keeps connections alive; change `HEARTBEAT_INTERVAL` in the source if needed.
- **Rate limiting**: The defaults of 30 messages per 10 seconds (configured via `WS_MSG_LIMIT` and `WS_MSG_WINDOW`) throttle abusive clients without affecting normal usage.
- **Implementation location**: All parameters live in [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts), making the real-time layer transparent and auditable.

---

## Frequently Asked Questions

### How do I restrict which domains can connect to the TREK WebSocket server?

Set the `ALLOWED_ORIGINS` environment variable to a comma-separated list of permitted origins before starting the server. The `verifyClient` logic inside `setupWebSocket` (lines 33–46) compares the incoming `Origin` header against this list and aborts the handshake if no match is found.

### What happens when a client exceeds the rate limit?

When a socket sends more than `WS_MSG_LIMIT` messages within `WS_MSG_WINDOW` milliseconds, the server transmits an error payload to that client and stops processing further messages from the socket until the time window resets. Other connections in the same room remain unaffected.

### Can I change the heartbeat interval without rebuilding the application?

No. The `HEARTBEAT_INTERVAL` constant (default 30 seconds) is hard-coded at line 49 of [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts). Adjusting the keep-alive frequency requires editing the constant and recompiling or restarting the server.

### Where are the WebSocket rate limit constants defined?

The per-connection rate limits are defined as constants at the top of [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts): `WS_MSG_LIMIT` (default 30) on line 27 and `WS_MSG_WINDOW` (default 10000 ms) on line 28. These values are consumed by the message handler to enforce the sliding-window throttle.