README.md

Eimspyr

Eimspyr is a Node.js library written in TypeScript. It queries information from a running Source Dedicated Server (SRCDS) using UDP/IP packets.

Installation

npm i eimspyr

Usage

Example values for properties address & port must be replaced with the remote server to be queried.

JavaScript

import { infoQuery } from 'eimspyr'

const response = await infoQuery({
  address: '127.0.0.1',
  port: 12345,
})

TypeScript

import type { InfoQuery, InfoQueryOptions } from 'eimspyr'
import { infoQuery } from 'eimspyr'

const destination: InfoQueryOptions = {
  address: '127.0.0.1',
  port: 12345,
}

const response: InfoQuery = await infoQuery(destination)

Types reference

Built-in type definitions are available for supported IDEs and editors, including for non-TypeScript users.

Importing types with TypeScript is optional and suggested for type safety and readability.

Imports

import type { InfoQuery, InfoQueryOptions } from 'eimspyr'

Request

InfoQueryOptions is the input parameter for infoQuery.

type InfoQueryOptions = {
  address: string
  port: number
  portTolerance?: number
  timeout?: number
}

Port error tolerance

Queries that are inaccurate by up to 1 port number are allowed by default. This is useful for situations where interchangeable RCON and query ports are desired for convenience. Regardless of the inaccuracy of the provided port number, the true port of the request is included in the InfoQuery response at request.port.

For example, Valheim's joinable in-game port (RCON) is 1 less than the query port number (i.e.: rcon: 999 and query: 1000). It is usually not possible to query RCON ports without manually incrementing to find the query port number, but this incrementing is solved automatically by default, allowing all ports seen in-game and in the Steam server browser to be "queried" as-is.

Provide a number to the optional portTolerance property to change the port offset, which should equal the known distance commonly found between a game's RCON and query ports (usually 1).

Set to 0 for best performance.

Timeout

Queries time out at 3000 milliseconds (3 seconds) by default. This duration can be shortened or extended by providing a replacement number in milliseconds to the optional timeout property.

If the timeout occurs before the query completes, a RangeError is thrown.

Learn more about async error handling.

Response

Specification: SRCDS server queries

The InfoQuery response object is JSON-serializable. Multiple fields are conditional to the value of extraDataFlag.

type InfoQuery = {
  antiCheat: boolean
  appID?: string
  bots: number
  extraDataFlag: number
  folder: string
  game: string
  keywords?: string
  map: string
  operatingSystem: 'Linux' | 'macOS' | 'Windows'
  passwordRequired: boolean
  platformID?: string
  players: number
  playersMax: number
  port?: number
  protocolVersion: number
  request: {
    address: string
    port: number
    timeout: number
  }
  response: {
    address: string
    challenge?: number
    family: string
    latency: {
      maximum: number
      median: number
      minimum: number
      total: number
    }
    messages: [
      {
        latency: number
        message: Buffer
        size: number
      }
    ]
    packetSplit: boolean
    port: number
    reflectionHardened: boolean
    type: 'A2S_INFO'
  }
  serverName: string
  serverType: 'dedicated' | 'local' | 'proxy'
  serverVersion: string
  spectatorName?: number
  spectatorPort?: number
}

Compatibility

A2S_INFO single-packet query responses are supported. Multi-packet responses are not supported.

Responses are supported from servers both hardened and vulnerable against reflection attacks (est. Dec. 2020). This status can be read from response.reflectionHardened.

Environment

node:buffer and node:dgram are Node.js dependencies that are incompatible with a browser environment, unless integrated with an API (see also: Next.js API route handler).

Games tested

• Valheim (2021)

Other games are likely compatible but have yet to be tested. For querying unsupported games in Node.js, try node-GameDig (est. 2013).

Use cases

• Functions as a service (FaaS)
• REST API routes
• Web applications

Next.js API route handler

• Vercel | Next.js API routes

import { infoQuery } from 'eimspyr'

export default async function handler(req, res) {
  res.status(200).json(
    await infoQuery({
      address: '127.0.0.1',
      port: 12345,
    })
  )
}