From 788ae176572751404379448c15f018c0030f1d27 Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Tue, 18 Aug 2026 14:08:10 +0000 Subject: [PATCH] Add UDP communication support for instances Add opt-in UDP messaging between the host and the Factorio server using the --enable-lua-udp option of Factorio 2.0.59+. When factorio.enable_lua_udp is set the instance binds a localhost UDP socket, starts Factorio with --enable-lua-udp on factorio.lua_udp_port (random if null, like the RCON port) and tells the clusterio module the host port via clusterio_private.update_instance. Data from Factorio is sent with clusterio_api.send_udp(channel, data) in the same IPC format as send_json, so plugins receive it through the existing ipc- events. Packets not sent from the Lua UDP port are ignored, as that is the only unauthenticated way into the IPC handler. Data to Factorio is sent with the new sendUdp method on instances and instance plugins, and is dispatched in-game as on_udp_packet_received events by polling helpers.recv_udp every tick from the clusterio module. Plugins requiring UDP declare the new LuaUdp feature flag, which like SavePatching and ScriptCommands refuses to load the plugin on instances without the option enabled. Verified against a headless 2.1.17 server: send_udp and recv_udp are silent no-ops when the option is off, so a stale port in a save that is moved to an instance without UDP does no harm. The integration test matrix now starts the instance with UDP enabled on Factorio 2.0.59+ and round trips a player event over it. Closes #969 Co-Authored-By: Claude Fable 5.1 --- docs/configuration.md | 17 +++++ docs/developing-for-clusterio.md | 14 ++++ docs/writing-plugins.md | 27 ++++++- packages/host/lua/clusterio_lib/api.lua | 26 +++++-- packages/host/modules/clusterio/api.lua | 19 ++++- packages/host/modules/clusterio/impl.lua | 17 ++++- packages/host/src/BaseInstancePlugin.ts | 16 ++++ packages/host/src/Instance.ts | 22 +++++- packages/host/src/server.ts | 97 ++++++++++++++++++++++++ packages/lib/src/config/definitions.ts | 27 ++++++- packages/lib/src/plugin.ts | 2 + test/host/server.js | 65 ++++++++++++++++ test/integration/index.js | 7 +- test/integration/instance.js | 26 ++++++- test/lib/config/validators.test.js | 29 +++++++ 15 files changed, 394 insertions(+), 17 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 8bf2ed82..817c5f94 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -606,6 +606,23 @@ Like factorio.enable_save_patching, plugins that need script commands can't be l Defaults to true. +### factorio.enable_lua_udp + +Enable UDP messaging between the host and the Factorio server by passing `--enable-lua-udp` to Factorio. +This lets plugins send UDP packets to the server and receive data sent with `clusterio_api.send_udp` in-game. +Requires Factorio 2.0.59 or later. + +Defaults to false. + + +### factorio.lua_udp_port + +UDP port on localhost the Factorio server receives Lua UDP messages on when `factorio.enable_lua_udp` is enabled. +If null a random port in the dynamic range is assigned each time the instance starts. + +Defaults to null. + + ### factorio.enable_whitelist Turn on the whitelist on the server. diff --git a/docs/developing-for-clusterio.md b/docs/developing-for-clusterio.md index a311af44..39ef4be1 100644 --- a/docs/developing-for-clusterio.md +++ b/docs/developing-for-clusterio.md @@ -251,6 +251,20 @@ Parameters: - `channel`: string identifying which channel to send it on. - `data`: table that can be converted to JSON with game.table_to_json +#### clusterio_api.send_udp(channel, data) + +Send JSON data to Clusterio over the given channel using UDP instead of stdout. +Clusterio plugins receive it the same way as data sent with `send_json`. +Requires `factorio.enable_lua_udp` to be enabled on the instance and Factorio 2.0.59 or later, otherwise the data is silently dropped. +The port to send to is passed to the module with a script command on startup, so `factorio.enable_script_commands` must be enabled as well. +See the [Communicating over UDP section](writing-plugins.md#communicating-over-udp) in the Writing Plugins document for more information. + +**Note**: Delivery is not guaranteed and payloads must be less than 64 kB. + +Parameters: +- `channel`: string identifying which channel to send it on. +- `data`: table that can be converted to JSON with game.table_to_json + ### serialize library diff --git a/docs/writing-plugins.md b/docs/writing-plugins.md index a1c6cb83..4b8f704d 100644 --- a/docs/writing-plugins.md +++ b/docs/writing-plugins.md @@ -131,7 +131,7 @@ The following properties are recognized: See [Migrating Stored Data](#migrating-stored-data) **features**: - Array of features the plugin needs from the instances it is loaded on, `"SavePatching"` and/or `"ScriptCommands"`. + Array of features the plugin needs from the instances it is loaded on, any of `"SavePatching"`, `"ScriptCommands"` and `"LuaUdp"`. See [Handling Invalid Configuration](#handling-invalid-configuration) **messages**: @@ -286,7 +286,7 @@ See [Configuration System](config-system.md) for more details on how this system ### Handling Invalid Configuration -If the plugin requires save patching or script commands to function, which can be disabled to run vanilla or scenarios not compatible with Clusterio, declare it under `features` in the `plugin` export: +If the plugin requires save patching, script commands or Lua UDP to function, which can be disabled to run vanilla or scenarios not compatible with Clusterio, declare it under `features` in the `plugin` export: ```js export const plugin = { @@ -482,6 +482,29 @@ Data out from Factorio does not have the same limits as data into Factorio, RCON For `send_json` it's possible that payloads greater than 4kB are received after payloads that were sent at a later point in time. For RCON, commands longer than 50 characters may end up being executed after shorter commands sent after it. +### Communicating over UDP + +Instances can optionally exchange UDP packets with the Factorio server for low latency fire-and-forget communication, using the `--enable-lua-udp` option of Factorio 2.0.59 and later. +This is disabled by default and enabled by setting `factorio.enable_lua_udp` on the instance. +Sending data out of Factorio also needs `factorio.enable_script_commands`, as the port to send to is passed to the module with a script command on startup. +Plugins requiring it should declare the `LuaUdp` feature. +Note that UDP does not guarantee delivery or ordering, and packets should be kept well below 64 kB. + +Data out from Factorio is sent with the `send_udp` API of the Clusterio module and is delivered to plugins as the same `ipc-channel_name` events as `send_json` uses: + +```lua +clusterio_api.send_udp("my_plugin_foo", { data = 123 }) +``` + +Data into Factorio is sent with the `sendUdp` method on the plugin object and delivered in-game as `defines.events.on_udp_packet_received` events with the packet in `event.payload`. +The Clusterio module polls for received packets every tick, all modules and mods receive every packet so make sure the payload identifies your plugin. + +```js +async onStart() { + await this.sendUdp("my_plugin_foo:123"); +} +``` + ## Defining Link Messages diff --git a/packages/host/lua/clusterio_lib/api.lua b/packages/host/lua/clusterio_lib/api.lua index 6af5463b..a9242489 100644 --- a/packages/host/lua/clusterio_lib/api.lua +++ b/packages/host/lua/clusterio_lib/api.lua @@ -38,17 +38,20 @@ function api.get_instance_id() end +local function escape_channel(channel) + -- Escape bad characters. The question mark is used for separating the + -- channel name from the payload. + return channel:gsub("([\x00-\x1f?\\])", function(match) + return "\\x" .. string.format("%02x", match:byte()) + end) +end + function api.send_json(channel, data) if not remote.interfaces.clusterio_api then return end - -- Escape bad characters. The question mark is used for separating the - -- channel name from the payload. - channel = channel:gsub("([\x00-\x1f?\\])", function(match) - return "\\x" .. string.format("%02x", match:byte()) - end) - + channel = escape_channel(channel) data = compat.table_to_json(data) -- If there's more than about 4kB of data users running with the Windows @@ -64,5 +67,16 @@ function api.send_json(channel, data) end end +function api.send_udp(channel, data) + local port = call_api("get_host_udp_port") + if not port then + return -- Lua UDP is not enabled for this instance + end + + channel = escape_channel(channel) + data = compat.table_to_json(data) + helpers.send_udp(port, "\f$ipc:" .. channel .. "?j" .. data, 0) +end + return api diff --git a/packages/host/modules/clusterio/api.lua b/packages/host/modules/clusterio/api.lua index 49ffda06..8c1ad4ac 100644 --- a/packages/host/modules/clusterio/api.lua +++ b/packages/host/modules/clusterio/api.lua @@ -17,14 +17,16 @@ function api.get_instance_id() return compat.script_data.clusterio.instance_id end -function api.send_json(channel, data) - +local function escape_channel(channel) -- Escape bad characters. The question mark is used for separating the -- channel name from the payload. - channel = channel:gsub("([\x00-\x1f?\\])", function(match) + return channel:gsub("([\x00-\x1f?\\])", function(match) return "\\x" .. string.format("%02x", match:byte()) end) +end +function api.send_json(channel, data) + channel = escape_channel(channel) data = compat.table_to_json(data) -- If there's more than about 4kB of data users running with the Windows @@ -41,5 +43,16 @@ function api.send_json(channel, data) end end +function api.send_udp(channel, data) + local port = compat.script_data.clusterio.host_udp_port + if not port then + return -- Lua UDP is not enabled for this instance + end + + channel = escape_channel(channel) + data = compat.table_to_json(data) + helpers.send_udp(port, "\f$ipc:" .. channel .. "?j" .. data, 0) +end + return api diff --git a/packages/host/modules/clusterio/impl.lua b/packages/host/modules/clusterio/impl.lua index 37ecf81e..202058f6 100644 --- a/packages/host/modules/clusterio/impl.lua +++ b/packages/host/modules/clusterio/impl.lua @@ -15,13 +15,21 @@ end local impl = {} impl.events = {} -impl.events[defines.events.on_tick] = check_patch +impl.events[defines.events.on_tick] = function() + check_patch() + -- Dispatch on_udp_packet_received for packets sent by the host + local clusterio = compat.script_data.clusterio + if clusterio and clusterio.host_udp_port then + helpers.recv_udp(0) + end +end impl.events[api.events.on_server_startup] = function() if not compat.script_data.clusterio then compat.script_data.clusterio = { instance_id = nil, instance_name = nil, + host_udp_port = nil, } end @@ -74,11 +82,12 @@ end -- Internal API clusterio_private = {} -function clusterio_private.update_instance(new_id, new_name) +function clusterio_private.update_instance(new_id, new_name, host_udp_port) check_patch() local script_data = compat.script_data script_data.clusterio.instance_id = new_id script_data.clusterio.instance_name = new_name + script_data.clusterio.host_udp_port = host_udp_port script.raise_event(api.events.on_instance_updated, { instance_id = new_id, instance_name = new_name, @@ -105,6 +114,10 @@ remote.add_interface('clusterio_api', { return compat.script_data.clusterio.instance_name end, + get_host_udp_port = function() + return compat.script_data.clusterio.host_udp_port + end, + get_file_no = function() local script_data = compat.script_data script_data.clusterio_file_no = (script_data.clusterio_file_no or 0) + 1 diff --git a/packages/host/src/BaseInstancePlugin.ts b/packages/host/src/BaseInstancePlugin.ts index 457c4bbe..dd06c114 100644 --- a/packages/host/src/BaseInstancePlugin.ts +++ b/packages/host/src/BaseInstancePlugin.ts @@ -259,6 +259,22 @@ export class BaseInstancePlugin { return await this.instance.sendRcon(message, expectEmpty, this.info.name); } + /** + * Send UDP message to instance + * + * Send a UDP packet to the Factorio server, which is delivered in-game + * as an on_udp_packet_received event. Delivery is not guaranteed and + * the payload should be kept well below 64 kB. Requires the LuaUdp + * plugin feature. + * + * This should not be called before onStart or after onStop. + * + * @param message - payload of the packet to send. + */ + async sendUdp(message: string | Buffer): Promise { + await this.instance.sendUdp(message); + } + /** * Send serially ordered RCON message to instance * diff --git a/packages/host/src/Instance.ts b/packages/host/src/Instance.ts index ed43019b..0190e5ad 100644 --- a/packages/host/src/Instance.ts +++ b/packages/host/src/Instance.ts @@ -232,6 +232,8 @@ export default class Instance extends lib.Link { gamePort: this.config.get("factorio.game_port") ?? host.assignGamePort(this.id), rconPort: this.config.get("factorio.rcon_port") ?? undefined, rconPassword: this.config.get("factorio.rcon_password") ?? undefined, + enableLuaUdp: this.config.get("factorio.enable_lua_udp"), + luaUdpPort: this.config.get("factorio.lua_udp_port") ?? undefined, enableWhitelist: this.config.get("factorio.enable_whitelist"), enableAuthserverBans: this.config.get("factorio.enable_authserver_bans"), verboseLogging: this.config.get("factorio.verbose_logging"), @@ -505,6 +507,23 @@ end`.replace(/\r?\n/g, " "); } } + /** + * Send UDP message to the Factorio server + * + * Delivered in-game as an on_udp_packet_received event. Requires + * factorio.enable_lua_udp to be enabled on the instance. + * + * @param message - payload of the packet to send. + */ + async sendUdp(message: string | Buffer) { + if (!this.config.get("factorio.enable_lua_udp")) { + throw new Error( + "Attempted to send UDP message while Lua UDP is disabled. See config factorio.enable_lua_udp." + ); + } + await this.server.sendUdp(message); + } + static async listSaves(instanceId: number, savesDir: string, loadedSave: string | null) { let defaultSave = null; if (loadedSave === null) { @@ -1089,7 +1108,8 @@ end`.replace(/\r?\n/g, " "); */ async updateInstanceData() { let name = lib.escapeString(this.name); - await this.sendRcon(`/sc clusterio_private.update_instance(${this.id}, "${name}")`, true); + let hostUdpPort = this.server.hostUdpPort ?? "nil"; + await this.sendRcon(`/sc clusterio_private.update_instance(${this.id}, "${name}", ${hostUdpPort})`, true); } async updateFactorioSettings(current: Record, previous: Record) { diff --git a/packages/host/src/server.ts b/packages/host/src/server.ts index 943660be..000b6c40 100644 --- a/packages/host/src/server.ts +++ b/packages/host/src/server.ts @@ -2,6 +2,7 @@ import fs from "node:fs/promises"; import { type FSWatcher, watch as fsWatch, writeFileSync } from "node:fs"; import child_process from "child_process"; +import dgram from "dgram"; import path from "path"; import JSZip from "jszip"; import events from "events"; @@ -542,6 +543,10 @@ export interface FactorioServerOptions { rconPort?: number, /** Password use for RCON. */ rconPassword?: string, + /** Enable UDP messaging with the Factorio server. */ + enableLuaUdp?: boolean, + /** UDP port the Factorio server receives Lua UDP messages on. */ + luaUdpPort?: number, /** Turn on whitelisting. */ enableWhitelist?: boolean, /** Enable Factorio.com based multiplayer bans. */ @@ -607,6 +612,8 @@ type FactorioServerEvents = { * - autosave-fnished - invoked when the autosave finished * - save-finished - invoked when the server has finished a manual save * - exit - invoked when the sterver has exited + * - ipc- - invoked with data sent by the clusterio module in-game, + * either via stdout or via UDP when Lua UDP is enabled * @extends events.EventEmitter */ export class FactorioServer extends events.EventEmitter { @@ -618,6 +625,10 @@ export class FactorioServer extends events.EventEmitter { rconPort: number; /** Password used for RCON on the Factorio game server */ rconPassword: string; + /** Enable UDP messaging with the Factorio game server */ + enableLuaUdp: boolean; + /** UDP port the Factorio game server receives Lua UDP messages on */ + luaUdpPort: number; /** Enable player whitelist */ enableWhitelist: boolean; /** Enable Factorio.com based multiplayer bans **/ @@ -647,6 +658,7 @@ export class FactorioServer extends events.EventEmitter { _server: child_process.ChildProcessWithoutNullStreams | null = null; _rconClient: Rcon | null= null; _rconReady = false; + _udpSocket: dgram.Socket | null = null; _gameReady = false; _stripRegExp?: RegExp; _maxConcurrentCommands = 5; @@ -679,6 +691,10 @@ export class FactorioServer extends events.EventEmitter { this.rconPort = options.rconPort || randomDynamicPort(); /** Password used for RCON on the Factorio game server */ this.rconPassword = options.rconPassword as string; // init will generate one if not there + /** Enable UDP messaging with the Factorio game server */ + this.enableLuaUdp = options.enableLuaUdp || false; + /** UDP port the Factorio game server receives Lua UDP messages on */ + this.luaUdpPort = options.luaUdpPort || randomDynamicPort(); /** Enable player whitelist */ this.enableWhitelist = options.enableWhitelist || false; /** Enable Factorio.com based multiplayer bans **/ @@ -791,6 +807,57 @@ export class FactorioServer extends events.EventEmitter { } } + _handleUdpMessage(message: Buffer, rinfo: dgram.RemoteInfo) { + // Factorio sends from the socket bound to the Lua UDP port, anything + // else is some other local process. + if (rinfo.port !== this.luaUdpPort) { + this._logger.warn(`Ignoring UDP packet from unexpected source ${rinfo.address}:${rinfo.port}`); + return; + } + + if (message.subarray(0, 6).equals(Buffer.from("\f$ipc:"))) { + this._handleIpc(message).catch(err => this.emit("error", err)); + return; + } + + this._logger.warn(`Ignoring UDP packet not in IPC format: ${message.subarray(0, 100).toString("utf-8")}`); + } + + async _bindUdpSocket() { + const socket = dgram.createSocket("udp4"); + socket.on("message", (message, rinfo) => this._handleUdpMessage(message, rinfo)); + try { + await new Promise((resolve, reject) => { + socket.once("error", reject); + socket.bind(0, "127.0.0.1", () => { + socket.off("error", reject); + resolve(); + }); + }); + } catch (err) { + socket.close(); + throw err; + } + socket.on("error", err => this.emit("error", err)); + this._udpSocket = socket; + } + + _closeUdpSocket() { + if (this._udpSocket) { + this._udpSocket.close(); + this._udpSocket = null; + } + } + + /** + * UDP port on localhost the host receives Lua UDP messages on + * + * Only available while the server is running with Lua UDP enabled. + */ + get hostUdpPort(): number | undefined { + return this._udpSocket?.address().port; + } + _handleOutput(rawLine: Buffer, source: "stdout" | "stderr") { if (rawLine.subarray(0, 6).equals(Buffer.from("\f$ipc:"))) { this._handleIpc(rawLine).catch(err => this.emit("error", err)); @@ -1063,6 +1130,7 @@ export class FactorioServer extends events.EventEmitter { this._server = null; this._rconClient = null; this._rconReady = false; + this._closeUdpSocket(); this._gameReady = false; this._unexpected = []; this._killed = false; @@ -1224,6 +1292,9 @@ export class FactorioServer extends events.EventEmitter { */ async start(save: string) { this._check(["init"]); + if (this.enableLuaUdp) { + await this._bindUdpSocket(); + } this._state = "running"; try { @@ -1239,6 +1310,7 @@ export class FactorioServer extends events.EventEmitter { "--port", String(this.gamePort), "--rcon-port", String(this.rconPort), "--rcon-password", this.rconPassword, + ...(this.enableLuaUdp ? ["--enable-lua-udp", String(this.luaUdpPort)] : []), ...(this.enableWhitelist ? ["--use-server-whitelist"] : []), ...(this.enableAuthserverBans ? ["--use-authserver-bans"] : []), ...(this.verboseLogging ? ["--verbose"] : []), @@ -1276,6 +1348,9 @@ export class FactorioServer extends events.EventEmitter { */ async startScenario(scenario: string, seed?: number, mapGenSettings?: object, mapSettings?: object) { this._check(["init"]); + if (this.enableLuaUdp) { + await this._bindUdpSocket(); + } this._state = "running"; try { @@ -1297,6 +1372,7 @@ export class FactorioServer extends events.EventEmitter { "--port", String(this.gamePort), "--rcon-port", String(this.rconPort), "--rcon-password", this.rconPassword, + ...(this.enableLuaUdp ? ["--enable-lua-udp", String(this.luaUdpPort)] : []), ...(this.enableWhitelist ? ["--use-server-whitelist"] : []), ...(this.enableAuthserverBans ? ["--use-authserver-bans"] : []), ...(this.verboseLogging ? ["--verbose"] : []), @@ -1377,6 +1453,27 @@ export class FactorioServer extends events.EventEmitter { return response; } + /** + * Send UDP message to the server + * + * Sends a UDP packet to the Lua UDP port of the Factorio server, which + * is delivered in-game as an on_udp_packet_received event. Delivery is + * not guaranteed. Requires Lua UDP to be enabled. + * + * @param message - payload of the packet to send. + */ + async sendUdp(message: string | Buffer) { + this._check(["running", "stopping"]); + if (!this._udpSocket) { + throw new Error("Lua UDP is not enabled"); + } + + const socket = this._udpSocket; + await new Promise((resolve, reject) => { + socket.send(message, this.luaUdpPort, "127.0.0.1", err => (err ? reject(err) : resolve())); + }); + } + /** * Timeout in ms to wait after a shutdown is requested before killing the * process. Defaults to 0 meaning no timeout diff --git a/packages/lib/src/config/definitions.ts b/packages/lib/src/config/definitions.ts index cfed9f21..ad90b3f1 100644 --- a/packages/lib/src/config/definitions.ts +++ b/packages/lib/src/config/definitions.ts @@ -482,6 +482,8 @@ export interface InstanceConfigFields { "factorio.host_assigned_game_port": number | null; "factorio.rcon_port": number | null; "factorio.rcon_password": string | null; + "factorio.enable_lua_udp": boolean; + "factorio.lua_udp_port": number | null; "factorio.player_online_autosave_slots": number; "factorio.mod_pack_id": number | null; "factorio.enable_save_patching": boolean; @@ -606,6 +608,21 @@ export class InstanceConfig extends classes.Config { type: "string", optional: true, }, + "factorio.enable_lua_udp": { + description: + "Enable UDP messaging between the Factorio server and the host. " + + "Required by plugins using UDP. Requires Factorio 2.0.59 or later.", + restartRequired: true, // Because of the cli option "--enable-lua-udp" + type: "boolean", + initialValue: false, + }, + "factorio.lua_udp_port": { + description: "UDP port for the Factorio server to receive Lua UDP messages on, uses a random port if null", + restartRequired: true, + type: "number", + optional: true, + validator: validators.optional(validators.greaterThanEqualZero), + }, "factorio.player_online_autosave_slots": { description: "Rename autosaves where players have been online since the previous autosave into a separate " + @@ -795,7 +812,12 @@ export function addPluginFieldDefinitions( fieldDef.dependsOn.push("factorio.enable_script_commands"); } - if (scriptCommands || savePatching) { + const luaUdp = pluginInfo.features.includes("LuaUdp"); + if (luaUdp) { + fieldDef.dependsOn.push("factorio.enable_lua_udp"); + } + + if (scriptCommands || savePatching || luaUdp) { fieldDef.validator = (enabled, config) => { if (!enabled) { return; @@ -806,6 +828,9 @@ export function addPluginFieldDefinitions( if (scriptCommands && !config.get("factorio.enable_script_commands")) { throw new Error(`Plugin ${pluginInfo.name} requires script commands`); } + if (luaUdp && !config.get("factorio.enable_lua_udp")) { + throw new Error(`Plugin ${pluginInfo.name} requires Lua UDP`); + } }; } } diff --git a/packages/lib/src/plugin.ts b/packages/lib/src/plugin.ts index 9ff338ab..18d581aa 100644 --- a/packages/lib/src/plugin.ts +++ b/packages/lib/src/plugin.ts @@ -14,6 +14,8 @@ export const PluginFeatureFlags = [ "SavePatching", /** The plugin requires access to script commands over rcon */ "ScriptCommands", + /** The plugin requires UDP messaging with the Factorio server */ + "LuaUdp", ] as const; /** Used to define the plugin export in plugins */ diff --git a/test/host/server.js b/test/host/server.js index c8965ed6..75b5d9c7 100644 --- a/test/host/server.js +++ b/test/host/server.js @@ -1,4 +1,5 @@ import assert from "node:assert/strict"; +import dgram from "node:dgram"; import events from "node:events"; import fs from "node:fs/promises"; import path from "node:path"; @@ -336,6 +337,70 @@ describe("host/server", function() { }); }); + describe("Lua UDP", function() { + let udpServer; + let received; + before(async function() { + // Stand-in for the Factorio server's --enable-lua-udp socket + udpServer = dgram.createSocket("udp4"); + received = []; + udpServer.on("message", (msg, rinfo) => received.push([msg, rinfo])); + await events.once(udpServer.bind(0, "127.0.0.1"), "listening"); + }); + after(function() { + udpServer.close(); + }); + + it("should not have a host port when not running", function() { + assert.equal(server.hostUdpPort, undefined); + }); + it("should reject sendUdp when not enabled", async function() { + server._state = "running"; + try { + await assert.rejects(server.sendUdp("data"), new Error("Lua UDP is not enabled")); + } finally { + server._state = "init"; + } + }); + it("should bind a socket, send and receive ipc over UDP", async function() { + server.enableLuaUdp = true; + server.luaUdpPort = udpServer.address().port; + await server._bindUdpSocket(); + server._state = "running"; + try { + assert(server.hostUdpPort > 0, "hostUdpPort not set"); + + await server.sendUdp("hello"); + await server.sendUdp(Buffer.from("world")); + while (received.length < 2) { + await wait(1); + } + assert.equal(received[0][0].toString(), "hello"); + assert.equal(received[1][0].toString(), "world"); + assert.equal(received[0][1].port, server.hostUdpPort); + + let ipcReceived = []; + let onIpc = content => ipcReceived.push(content); + server.on("ipc-udp_channel", onIpc); + let waiter = events.once(server, "ipc-udp_channel"); + // Packets not from the Factorio server's port are ignored + let other = dgram.createSocket("udp4"); + await events.once(other.bind(0, "127.0.0.1"), "listening"); + other.send(Buffer.from('\f$ipc:udp_channel?j{"data":"bad"}'), server.hostUdpPort, "127.0.0.1"); + udpServer.send(Buffer.from('\f$ipc:udp_channel?j{"data":"spam"}'), server.hostUdpPort, "127.0.0.1"); + await waiter; + server.off("ipc-udp_channel", onIpc); + other.close(); + assert.deepEqual(ipcReceived, [{ data: "spam" }]); + } finally { + server._resetState(); + server.enableLuaUdp = false; + } + assert.equal(server._udpSocket, null); + assert.equal(server.hostUdpPort, undefined); + }); + }); + describe(".stop()", function() { it("should handle server quitting on its own during stop", async function() { server.shutdownTimeoutMs = 20; diff --git a/test/integration/index.js b/test/integration/index.js index 5793a5d3..ccb977e7 100644 --- a/test/integration/index.js +++ b/test/integration/index.js @@ -138,6 +138,10 @@ export function hasFactorio() { return haveFactorioInstall; } +export function getFactorioVersion() { + return latestFactorioVersion; +} + export async function get(urlPath) { const url = new URL("https://localhost:4443"); url.pathname = urlPath; @@ -170,6 +174,7 @@ let controllerProcess; let hostProcess; let control; let haveFactorioInstall; +let latestFactorioVersion; const baseHostConfig = loadJSON("config-host.json"); @@ -356,7 +361,7 @@ before(async function() { controllerProcess = await spawnNode("controller:", "../../packages/controller run", /Started controller/); const factorioVersions = (await _listFactorioVersions(factorioDir)).versions; - const latestFactorioVersion = [...factorioVersions.values()] + latestFactorioVersion = [...factorioVersions.values()] .sort((a, b) => lib.integerFullVersion(b) - lib.integerFullVersion(a))[0]; haveFactorioInstall = factorioVersions.size > 0; diff --git a/test/integration/instance.js b/test/integration/instance.js index b46529a1..56d75e72 100644 --- a/test/integration/instance.js +++ b/test/integration/instance.js @@ -6,7 +6,7 @@ import fs from "node:fs/promises"; import { slowTest, testMatrix } from "../common.js"; import { execCtl, execCtlProcess, sendRcon, getControl, - requiresFactorio, hasFactorio, instancesDir, + requiresFactorio, hasFactorio, getFactorioVersion, instancesDir, } from "./index.js"; const instId = 48; @@ -21,6 +21,11 @@ const requireApi = [ "or package.loaded['__level__/modules/clusterio/api.lua']", // 2.0.0 ].join(" "); +// --enable-lua-udp was added in Factorio 2.0.59 +function hasLuaUdp() { + return lib.integerFullVersion(getFactorioVersion()) >= lib.integerFullVersion("2.0.59"); +} + function getUser(name) { return getControl().send(new lib.UserGetRequest(name)); } @@ -111,6 +116,7 @@ describe("Clusterio Instance", function() { await execCtl(`${instSetConfig} factorio.enable_whitelist true`); await execCtl(`${instSetConfig} factorio.enable_save_patching ${savePatchingEnabled}`); await execCtl(`${instSetConfig} factorio.enable_script_commands ${scriptCommandsEnabled}`); + await execCtl(`${instSetConfig} factorio.enable_lua_udp ${hasLuaUdp()}`); await execCtl(`instance save create ${instName}`); await execCtl(`instance start ${instName}`); }); @@ -152,6 +158,24 @@ describe("Clusterio Instance", function() { const userLeave = await getUser("JoiningPlayer"); assert(!userLeave.instances.has(instId), "Player is not shown as offline"); }); + it("should respond to a player join and leave event sent over UDP", async function() { + // The host port is passed to the module by updateInstanceData on startup + if (!hasLuaUdp() || !scriptCommandsEnabled) { + this.skip(); + } + await sendRcon(instId, + `/sc ${requireApi} api.send_udp("player_event",` + + "{ type='join', name='UdpPlayer' })" + ); + const userJoin = await getUser("UdpPlayer"); + assert(userJoin.instances.has(instId), "Player is not shown as online"); + await sendRcon(instId, + `/sc ${requireApi} api.send_udp("player_event",` + + "{ type='leave', name='UdpPlayer', reason='quit' })" + ); + const userLeave = await getUser("UdpPlayer"); + assert(!userLeave.instances.has(instId), "Player is not shown as offline"); + }); } it("should respond to a player ban and unban event", async function() { await execCtl(`${instSetConfig} factorio.sync_banlist bidirectional`); diff --git a/test/lib/config/validators.test.js b/test/lib/config/validators.test.js index 1ae9de05..db5113f4 100644 --- a/test/lib/config/validators.test.js +++ b/test/lib/config/validators.test.js @@ -340,6 +340,35 @@ describe("lib/config/definitions/validators", function() { /requires script commands/ ); }); + it("should validate against factorio.enable_lua_udp", function() { + class TestInstanceConfig extends InstanceConfig { + static fieldDefinitions = { ...InstanceConfig.fieldDefinitions }; + } + + lib.addPluginFieldDefinitions( + { name: "lua_udp", features: ["LuaUdp"] }, + "instanceConfigFields", TestInstanceConfig + ); + + const config = new TestInstanceConfig("controller", initialConfigFields); + + // valid: does not require save patching or script commands + assert.doesNotThrow(() => config.set("factorio.enable_save_patching", false)); + assert.doesNotThrow(() => config.set("factorio.enable_script_commands", false)); + + // valid: can have load disabled + assert.doesNotThrow(() => config.set("lua_udp.load_plugin", false)); + + // invalid: requires lua udp when loaded (disabled by default) + assert.throws( + () => config.set("lua_udp.load_plugin", true), + /requires Lua UDP/ + ); + + // valid: requirement satisfied + assert.doesNotThrow(() => config.set("factorio.enable_lua_udp", true)); + assert.doesNotThrow(() => config.set("lua_udp.load_plugin", true)); + }); it("should allow when no feature flags are present", function() { class TestInstanceConfig extends InstanceConfig { static fieldDefinitions = { ...InstanceConfig.fieldDefinitions };