@callowayisweird/source-rcon

Production-grade Source Engine RCON client for Node.js and Bun. Zero runtime dependencies, full TypeScript support.

Install

npm install @callowayisweird/source-rcon

Usage

Basic Connection

import { Rcon } from '@callowayisweird/source-rcon'

const rcon = new Rcon({
  host: '127.0.0.1',
  port: 27015,
  password: 'your_rcon_password',
})

await rcon.connect()

const status = await rcon.execute('status')
console.log(status)

await rcon.disconnect()

Events

const rcon = new Rcon({
  host: '127.0.0.1',
  port: 27015,
  password: 'secret',
})

rcon.on('connect', () => console.log('Connected'))
rcon.on('disconnect', () => console.log('Disconnected'))
rcon.on('error', (err) => console.error('Error:', err))

await rcon.connect()

Auto-Reconnection

const rcon = new Rcon({
  host: '127.0.0.1',
  port: 27015,
  password: 'secret',
  autoReconnect: true,
  maxReconnectAttempts: 5,
  reconnectDelay: 3000,
})

rcon.on('reconnecting', (attempt) => {
  console.log(`Reconnecting... attempt ${attempt}`)
})

await rcon.connect()

Multi-Server Pool

import { RconPool } from '@callowayisweird/source-rcon'

const pool = new RconPool([
  { host: '10.0.0.1', port: 27015, password: 'pass1' },
  { host: '10.0.0.2', port: 27015, password: 'pass2' },
  { host: '10.0.0.3', port: 27015, password: 'pass3' },
])

await pool.connectAll()

// Execute on a specific server
const status = await pool.execute('10.0.0.1:27015', 'status')

// Execute on all servers
const results = await pool.executeAll('status')
for (const [server, response] of results) {
  console.log(`${server}: ${response}`)
}

await pool.disconnectAll()

Permission-Gated RCON

import { Rcon, GatedRcon } from '@callowayisweird/source-rcon'

const rcon = new Rcon({
  host: '127.0.0.1',
  port: 27015,
  password: 'secret',
})

await rcon.connect()

const gated = new GatedRcon(rcon, {
  allowedUsers: ['STEAM_0:1:12345678', 'STEAM_0:1:87654321'],
  permissions: {
    'STEAM_0:1:12345678': ['say *', 'status', 'changelevel *'], // admin
    'STEAM_0:1:87654321': ['say *', 'status'],                   // moderator
  },
  rateLimit: {
    windowMs: 60000,  // 1 minute
    maxCommands: 10,   // max 10 commands per minute
  },
  onExecute: (steamId, command, response) => {
    console.log(`[RCON] ${steamId} executed: ${command}`)
  },
  onBlocked: (steamId, command, reason) => {
    console.warn(`[RCON] Blocked ${steamId}: ${command} (${reason})`)
  },
})

// Will succeed for allowed users with matching permissions
await gated.execute('STEAM_0:1:12345678', 'say Hello everyone!')

// Will throw PermissionDeniedError
await gated.execute('STEAM_0:1:87654321', 'changelevel gm_flatgrass')

Error Handling

import {
  Rcon,
  AuthFailedError,
  ConnectionRefusedError,
  TimeoutError,
  DisconnectedError,
} from '@callowayisweird/source-rcon'

const rcon = new Rcon({
  host: '127.0.0.1',
  port: 27015,
  password: 'secret',
  timeout: 5000,
})

try {
  await rcon.connect()
} catch (err) {
  if (err instanceof AuthFailedError) {
    console.error('Wrong RCON password')
  } else if (err instanceof ConnectionRefusedError) {
    console.error('Server refused connection')
  } else if (err instanceof TimeoutError) {
    console.error('Connection timed out')
  }
}

try {
  await rcon.execute('status')
} catch (err) {
  if (err instanceof DisconnectedError) {
    console.error('Not connected to server')
  } else if (err instanceof TimeoutError) {
    console.error('Command timed out')
  }
}

API Reference

Rcon

Method	Description
new Rcon(options)	Create a new RCON client
connect()	Connect and authenticate
execute(command)	Execute a command (queued, sequential)
disconnect()	Disconnect from the server
isConnected	Whether the client is authenticated

RconOptions

Option	Type	Default	Description
host	string	required	Server hostname or IP
port	number	required	Server RCON port
password	string	required	RCON password
timeout	number	5000	Timeout in milliseconds
autoReconnect	boolean	false	Auto-reconnect on disconnect
maxReconnectAttempts	number	5	Max reconnection attempts
reconnectDelay	number	3000	Delay between reconnect attempts (ms)

Events

Event	Arguments	Description
connect	none	Successfully connected and authenticated
disconnect	none	Disconnected from server
error	Error	An error occurred
reconnecting	number	Attempting to reconnect (attempt number)

RconPool

Method	Description
new RconPool(servers)	Create pool from array of server options
connectAll()	Connect to all servers
execute(key, command)	Execute on a specific server (host:port)
executeAll(command)	Execute on all servers
disconnectAll()	Disconnect all servers
get(key)	Get the Rcon instance for a server
size	Number of servers in the pool

GatedRcon

Method	Description
new GatedRcon(rcon, options)	Create gated wrapper around an Rcon instance
execute(steamId, command)	Execute if permitted, throws PermissionDeniedError if not

Errors

Error	Code	Description
RconError	varies	Base error class
AuthFailedError	AUTH_FAILED	Wrong RCON password
ConnectionError	CONNECTION_FAILED	Cannot connect to server
ConnectionRefusedError	CONNECTION_REFUSED	Connection actively refused
TimeoutError	TIMEOUT	Operation timed out
DisconnectedError	DISCONNECTED	Not connected to server
BannedError	BANNED	IP banned after failed auth attempts
PermissionDeniedError	PERMISSION_DENIED	GatedRcon blocked the command

License

MIT