Backpack.tf WebSocket Relay

A Node.js WebSocket relay service that solves the "one connection per IP" limitation of the Backpack.tf WebSocket API. This service maintains a single connection to Backpack.tf and relays messages to multiple local clients.

🎯 Purpose

Backpack.tf's WebSocket API only allows one connection per IP address. This relay service:

• Maintains a single connection to wss://ws.backpack.tf/events
• Allows multiple local services to connect to the relay
• Broadcasts all Backpack.tf messages to connected local clients
• Provides health monitoring and connection management

🚀 Quick Start

Installation

npm install

Configuration

Create a .env file (optional):

PORT=3001
BACKPACK_WS_URL=wss://ws.backpack.tf/events
LOG_LEVEL=INFO

Running the Service

# Development mode with auto-restart
npm run dev

# Production mode
npm start

📡 API Endpoints

Endpoint	Method	Description
/	GET	Service information and available endpoints
/health	GET	Simple health check (200/503)
/status	GET	Detailed service status and statistics
/api/clients	GET	Connected clients information
ws://localhost:3001/relay	WebSocket	Client connection endpoint

🔌 WebSocket Usage

Connecting to the Relay

const WebSocket = require('ws');

const ws = new WebSocket('ws://localhost:3001/relay');

ws.on('open', () => {
  console.log('Connected to Backpack.tf relay');
});

ws.on('message', (data) => {
  const message = JSON.parse(data);
  
  // Handle different message types
  switch (message.type) {
    case 'relay_status':
      console.log('Relay status:', message);
      break;
    case 'backpack_connected':
      console.log('Backpack.tf connected');
      break;
    case 'backpack_disconnected':
      console.log('Backpack.tf disconnected');
      break;
    default:
      // Regular Backpack.tf messages
      console.log('Backpack.tf message:', message);
  }
});

Message Types

The relay sends several types of messages:

Relay Control Messages

• relay_status - Initial connection status
• backpack_connected - Backpack.tf connection established
• backpack_disconnected - Backpack.tf connection lost
• backpack_error - Backpack.tf connection error

Backpack.tf Messages

All original Backpack.tf WebSocket messages are relayed unchanged.

Heartbeat/Ping

// Send ping to maintain connection
ws.send(JSON.stringify({ type: 'ping' }));

// Server responds with pong
ws.on('message', (data) => {
  const message = JSON.parse(data);
  if (message.type === 'pong') {
    console.log('Heartbeat acknowledged');
  }
});

🔧 Configuration

Environment Variables

Variable	Default	Description
PORT	3001	HTTP server port
BACKPACK_WS_URL	wss://ws.backpack.tf/events	Backpack.tf WebSocket URL
LOG_LEVEL	INFO	Logging level (ERROR, WARN, INFO, DEBUG)

Features

• Automatic Reconnection: Reconnects to Backpack.tf with exponential backoff
• Client Management: Tracks connected clients with heartbeat monitoring
• Health Monitoring: HTTP endpoints for service health and status
• Graceful Shutdown: Properly closes all connections on shutdown
• Comprehensive Logging: Structured logging with configurable levels

📊 Monitoring

Health Check

curl http://localhost:3001/health

Response:

{
  "healthy": true,
  "backpackConnected": true,
  "connectedClients": 3,
  "uptime": 123456,
  "messagesRelayed": 4567
}

Detailed Status

curl http://localhost:3001/status

Client Information

curl http://localhost:3001/api/clients

🛠 Integration Examples

Replacing Direct Backpack.tf Connection

Before (direct connection):

const ws = new WebSocket('wss://ws.backpack.tf/events');

After (via relay):

const ws = new WebSocket('ws://localhost:3001/relay');

Multiple Services

You can now run multiple services that need Backpack.tf data:

• TF2 Spell Handler
• Price monitoring service
• Trading bot
• Analytics service

All connecting to the same relay without IP conflicts.

🚀 Deployment

Local Development

npm run dev

Production

npm start

Docker (Future Enhancement)

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY src/ ./src/
EXPOSE 3001
CMD ["npm", "start"]

📝 Logging

The service provides structured logging with timestamps:

[2025-09-18T10:30:00.000Z] [INFO] 🚀 Backpack.tf WebSocket Relay Server running on port 3001
[2025-09-18T10:30:01.000Z] [INFO] ✅ Connected to Backpack.tf WebSocket
[2025-09-18T10:30:05.000Z] [INFO] 📱 Client 1 connected from ::1
[2025-09-18T10:30:10.000Z] [DEBUG] 📨 Relayed message type: listing to 1 clients

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Troubleshooting

Common Issues

Connection Refused

• Ensure the relay service is running on the correct port
• Check firewall settings

No Messages Received

• Verify Backpack.tf WebSocket connection status via /status endpoint
• Check if the service has proper internet connectivity

Client Disconnections

• The relay implements heartbeat monitoring (30s intervals)
• Ensure clients respond to ping messages

Support

For issues and questions:

1. Check the logs for error messages
2. Verify service status via /health endpoint
3. Review the detailed status at /status
4. Check network connectivity to Backpack.tf