Merge pull request #996 from bbassie/feature/instance-udp

Add UDP communication support for instances
This commit is contained in:
Cooldude2606 authored and GitHub committed 2026-10-17 20:47:54 +01:00
commit ba800e853d
19 files changed
+708 -25

No files matched your search

+18 -6
View File
@@ -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,14 @@ 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
helpers.send_udp(port, escape_channel(channel) .. "?" .. data, 0)
end
return api
+15 -3
View File
@@ -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,15 @@ function api.send_json(channel, data)
end
end
function api.send_udp(channel, data)
local clusterio = compat.script_data.clusterio
local port = clusterio and clusterio.host_udp_port
if not port then
return -- Lua UDP is not enabled for this instance
end
helpers.send_udp(port, escape_channel(channel) .. "?" .. data, 0)
end
return api
+20 -2
View File
@@ -12,16 +12,27 @@ local function check_patch()
end
end
-- Added in Factorio 2.0.59, indexing a missing key on a LuaObject errors
local has_recv_udp = helpers ~= nil and pcall(function() return helpers.recv_udp 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, this is
-- a no-op when the server was started without --enable-lua-udp
if has_recv_udp 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 +85,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 +117,12 @@ remote.add_interface('clusterio_api', {
return compat.script_data.clusterio.instance_name
end,
get_host_udp_port = function()
-- Not initialised until the first tick after the save is patched
local clusterio = compat.script_data.clusterio
return clusterio and 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
+16
View File
@@ -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<void> {
await this.instance.sendUdp(message);
}
/**
* Send serially ordered RCON message to instance
*
+21 -1
View File
@@ -233,6 +233,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"),
@@ -506,6 +508,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) {
@@ -1090,7 +1109,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<string, unknown>, previous: Record<string, unknown>) {
+139 -8
View File
@@ -2,6 +2,7 @@
import fs from "node:fs/promises";
import { type FSWatcher, createWriteStream, watch as fsWatch, writeFileSync } from "node:fs";
import child_process from "child_process";
import dgram from "dgram";
import path from "path";
import stream from "node:stream";
import { pipeline } from "node:stream/promises";
@@ -303,6 +304,15 @@ async function generatePassword(length: number) {
}
}
function unescapeChannel(channel: Buffer) {
return channel
.toString("utf-8")
.replace(/\\x([0-9a-f]{2})/g, (match, p1) => (
String.fromCharCode(parseInt(p1, 16))
))
;
}
/**
* Interpret lines of output from Factorio
*
@@ -425,6 +435,9 @@ const outputHeuristics: Heuristic[] = [
filter: { type: "log", message: /^Starting RCON interface/ },
action: function() {
this._startRcon().catch((err) => { this.emit("error", err); });
if (this.enableLuaUdp) {
this._startUdp().catch((err) => { this.emit("error", err); });
}
},
},
@@ -556,6 +569,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. */
@@ -600,8 +617,9 @@ type FactorioServerEvents = {
"_saving": [],
"_saved": [],
// IPS events
// IPC events
[ipcEvent: `ipc-${string}`]: [ event: any ],
[udpEvent: `udp-${string}`]: [ data: Buffer ],
};
/**
@@ -621,6 +639,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-<channel> - invoked with data sent with send_json in-game
* - udp-<channel> - invoked with data sent with send_udp in-game
* @extends events.EventEmitter
*/
export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
@@ -632,6 +652,10 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
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 **/
@@ -661,6 +685,7 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
_server: child_process.ChildProcessWithoutNullStreams | null = null;
_rconClient: Rcon | null= null;
_rconReady = false;
_udpSocket: dgram.Socket | null = null;
_gameReady = false;
_stripRegExp?: RegExp;
_maxConcurrentCommands = 5;
@@ -693,6 +718,10 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
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 **/
@@ -755,19 +784,24 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
}));
}
handleUdp(channel: string, handler: (data: Buffer) => Promise<void>) {
// Runs from the socket callback, so synchronous throws must be caught here too
this.on(`udp-${channel}`, async (data) => {
try {
await handler(data);
} catch (err: any) {
this._logger.error(`Error handling udp event:\n${err.stack ?? err.message}`);
}
});
}
async _handleIpc(line: Buffer) {
let channelEnd = line.indexOf("?");
if (channelEnd === -1) {
throw new Error(`Malformed IPC line "${line.toString()}"`);
}
let channel = line
.subarray(6, channelEnd)
.toString("utf-8")
.replace(/\\x([0-9a-f]{2})/g, (match, p1) => (
String.fromCharCode(parseInt(p1, 16))
))
;
let channel = unescapeChannel(line.subarray(6, channelEnd));
let type = line.subarray(channelEnd + 1, channelEnd + 2).toString("utf-8");
let content;
@@ -805,6 +839,74 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
}
}
_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;
}
let channelEnd = message.indexOf("?");
if (channelEnd === -1) {
this._logger.warn(`Ignoring malformed UDP packet "${message.subarray(0, 100).toString("utf-8")}"`);
return;
}
let channel = unescapeChannel(message.subarray(0, channelEnd));
let data = message.subarray(channelEnd + 1);
if (!this.emit(`udp-${channel}`, data)) {
this._logger.warn(`Warning: Unhandled udp-${channel}`);
}
}
async _startUdp() {
if (this._udpSocket !== null) {
throw Error("UDP socket is already open");
}
const socket = dgram.createSocket("udp4");
socket.on("message", (message, rinfo) => this._handleUdpMessage(message, rinfo));
try {
await new Promise<void>((resolve, reject) => {
socket.once("error", reject);
socket.bind(0, "127.0.0.1", () => {
socket.off("error", reject);
resolve();
});
});
} catch (err: any) {
this._logger.error(`Failed to open UDP socket:\n${err?.stack ?? err?.message ?? err}`);
socket.close();
return;
}
socket.on("error", err => this.emit("error", err));
this._udpSocket = socket;
}
// Factorio before 2.1.10 crashes when a packet is received on a headless server
_checkLuaUdpVersion() {
if (this.enableLuaUdp && lib.integerFullVersion(this._version!) < lib.integerFullVersion("2.1.10")) {
throw new Error("Lua UDP requires Factorio 2.1.10 or later");
}
}
_stopUdp() {
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));
@@ -1087,6 +1189,7 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
this._server = null;
this._rconClient = null;
this._rconReady = false;
this._udpSocket = null;
this._gameReady = false;
this._unexpected = [];
this._killed = false;
@@ -1132,6 +1235,7 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
if (this._rconClient) {
this._rconClient.end().catch(() => {});
}
this._stopUdp();
if (this._whitelistWatcher) {
this._whitelistWatcher.close();
@@ -1150,6 +1254,7 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
if (this._rconClient) {
this._rconClient.end().catch(() => {});
}
this._stopUdp();
if (this._whitelistWatcher) {
this._whitelistWatcher.close();
@@ -1248,6 +1353,7 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
*/
async start(save: string) {
this._check(["init"]);
this._checkLuaUdpVersion();
this._state = "running";
try {
@@ -1263,6 +1369,7 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
"--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"] : []),
@@ -1300,6 +1407,7 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
*/
async startScenario(scenario: string, seed?: number, mapGenSettings?: object, mapSettings?: object) {
this._check(["init"]);
this._checkLuaUdpVersion();
this._state = "running";
try {
@@ -1321,6 +1429,7 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
"--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"] : []),
@@ -1401,6 +1510,27 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
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("UDP socket is not open");
}
const socket = this._udpSocket;
await new Promise<void>((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
@@ -1436,6 +1566,7 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
if (this._rconClient) {
this._rconClient.end().catch(() => {});
}
this._stopUdp();
if (this._whitelistWatcher) {
this._whitelistWatcher.close();
}
+26 -1
View File
@@ -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<InstanceConfigFields> {
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.1.10 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`);
}
};
}
}
+2
View File
@@ -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 */