Eimspyr

!npm
!GitHub
!npm type definitions
!node-current
!size repository
!size minified
!size minzip

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

Installation

``Shell
npm i eimspyr
`

Usage

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

$3

`javascript
import { infoQuery } from 'eimspyr'

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

$3

`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.

$3

`typescript
import type { InfoQuery, InfoQueryOptions } from 'eimspyr'
`

$3

InfoQueryOptions is the input parameter for infoQuery.

`typescript
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.

$3

Specification: _SRCDS server queries_

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

`typescript
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.

$3

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_).

$3

- 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

$3

- Vercel | Next.js API routes

`javascript
import { infoQuery } from 'eimspyr'

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