From 5aaea1f2132b80dc9cad67fd2b817c00c95c5ce5 Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Tue, 17 Nov 2026 16:30:36 +0000 Subject: [PATCH 1/2] Support the ARM64 Linux headless build of Factorio Factorio publishes a linux-arm64 headless build from 2.1.18. On ARM64 Linux the host now downloads that build, refuses versions older than 2.1.18 that are not already installed, and finds the binary in bin/arm64 or bin/x64, whichever is present. The host builds the download URL from the version instead of using headlessUrl from the controller, so the version list on the wire stays the same. Co-Authored-By: Claude Opus 5.5 --- Dockerfile | 4 +- README.md | 4 + docs/configuration.md | 3 +- packages/host/src/server.ts | 53 ++++++++++-- packages/lib/src/external/FactorioVersions.ts | 20 ++++- test/host/server.js | 83 ++++++++++++++++++- test/lib/external/FactorioVersions.test.js | 15 +++- 7 files changed, 167 insertions(+), 15 deletions(-) diff --git a/Dockerfile b/Dockerfile index 66c296b0..dd225b86 100644 --- a/Dockerfile +++ b/Dockerfile @@ -11,7 +11,9 @@ RUN apt update \ && apt install -y wget \ && mkdir /clusterio WORKDIR /clusterio -RUN wget -q -O factorio.tar.gz https://www.factorio.com/get-download/latest/headless/linux64 && tar -xf factorio.tar.gz && rm factorio.tar.gz +ARG TARGETARCH +RUN if [ "$TARGETARCH" = "arm64" ]; then build=linux-arm64; else build=linux64; fi \ +&& wget -q -O factorio.tar.gz https://www.factorio.com/get-download/latest/headless/$build && tar -xf factorio.tar.gz && rm factorio.tar.gz # Copy project files into the container COPY . . diff --git a/README.md b/README.md index f6af8992..57a9f85d 100644 --- a/README.md +++ b/README.md @@ -129,6 +129,10 @@ Check out all our of decisions for [node, factorio, and operation support](/docs 3. Optionally copy the generated systemd service files in `systemd` folder to `/etc/systemd/system/`. +Hosts on Linux download the headless build of Factorio as needed. +On ARM64 (aarch64) Linux this only works for Factorio 2.1.18 and later, which is the first version Factorio published an ARM64 headless build for. +Older versions have to be installed manually, for example the x64 build run through an emulator. + **Ubuntu with Docker** diff --git a/docs/configuration.md b/docs/configuration.md index 82376b98..0fa69826 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -592,7 +592,8 @@ Defaults to "latest". ### factorio.executable_path Path relative to the Factorio installation directory of the executable to run. -If null the path is auto detected, which is `bin/x64/factorio` on Linux and Windows and `MacOS/factorio` on macOS. +If null the path is auto detected, which is `MacOS/factorio` on macOS and otherwise `bin/x64/factorio` or `bin/arm64/factorio`, whichever exists. +When both exist the one matching the CPU is used. Only needed in special setups. Defaults to null. diff --git a/packages/host/src/server.ts b/packages/host/src/server.ts index 6bc02ba0..9c4f8d7f 100644 --- a/packages/host/src/server.ts +++ b/packages/host/src/server.ts @@ -1,6 +1,6 @@ // Factorio Server interface import fs from "node:fs/promises"; -import { type FSWatcher, createWriteStream, watch as fsWatch, writeFileSync } from "node:fs"; +import { type FSWatcher, createWriteStream, existsSync, watch as fsWatch, writeFileSync } from "node:fs"; import child_process from "child_process"; import dgram from "dgram"; import path from "path"; @@ -182,6 +182,19 @@ async function downloadAndExtractTar(url: string, targetDir: string) { } } +/** + * Factorio Linux build architecture matching this host + * + * @returns "arm64" on ARM64 Linux, otherwise "x64". + */ +function factorioArch(): lib.FactorioHeadlessArch { + return process.platform === "linux" && process.arch === "arm64" ? "arm64" : "x64"; +} + +function hasArm64Headless(version: lib.FullVersion) { + return lib.integerFullVersion(version) >= lib.integerFullVersion(lib.minimumArm64HeadlessVersion); +} + // Factorio downloads in progress by target directory, shared by every server in the process const downloadsInProgress = new Map>(); @@ -202,14 +215,27 @@ export async function checkForUpdates( logger: lib.Logger = lib.logger, ) { - const latestVersion = availableVersions - .filter(v => ( - targetVersion === "latest" || v.version === targetVersion || v.version.startsWith(targetVersion) - )) + const matchesTarget = (version: string) => ( + targetVersion === "latest" || version === targetVersion || version.startsWith(targetVersion) + ); + const arch = factorioArch(); + const matching = availableVersions.filter(v => matchesTarget(v.version)); + const latestVersion = matching + .filter(v => arch !== "arm64" || hasArm64Headless(v.version)) .sort((v1, v2) => versionOrder(v1.version, v2.version)) [0]; if (!latestVersion) { + if (matching.length && arch === "arm64" && process.platform === "linux") { + const installed = await listFactorioVersions(factorioDir); + if (!installed.direct && ![...installed.versions].some(matchesTarget)) { + throw new Error( + `Factorio ${targetVersion} has no ARM64 Linux headless build to download, ` + + `ARM64 builds start at ${lib.minimumArm64HeadlessVersion}. Install it manually ` + + `or use version ${lib.minimumArm64HeadlessVersion} or later.` + ); + } + } return; } @@ -242,7 +268,7 @@ export async function checkForUpdates( logger.info(`A newer version of factorio is available (${v}), waiting for download...`); } else { logger.info(`A newer version of factorio is available (${v}), starting download...`); - download = downloadAndExtractTar(latestVersion.headlessUrl, dst).finally(() => { + download = downloadAndExtractTar(lib.factorioHeadlessUrl(v, arch), dst).finally(() => { downloadsInProgress.delete(dst); }); downloadsInProgress.set(dst, download); @@ -1734,8 +1760,8 @@ export class FactorioServer extends events.EventEmitter { /** * Get Factorio binary path * - * Get the path to the factorio binary depending on the configuration - * and or the platform (MacOS support) + * Get the path to the factorio binary depending on the configuration, + * the platform (MacOS support) and the bin/x64 or bin/arm64 dir present * * @returns Path to factorio binary */ @@ -1746,7 +1772,16 @@ export class FactorioServer extends events.EventEmitter { if (process.platform === "darwin") { return this.dataPath("..", "MacOS", "factorio"); } - return this.dataPath("..", "bin", "x64", "factorio"); + // Prefer the native build, fall back to whichever one is installed + const arches = factorioArch() === "arm64" ? ["arm64", "x64"] : ["x64", "arm64"]; + for (const arch of arches) { + const binary = this.dataPath("..", "bin", arch, "factorio"); + // eslint-disable-next-line node/no-sync + if (existsSync(binary)) { + return binary; + } + } + return this.dataPath("..", "bin", arches[0], "factorio"); } /** diff --git a/packages/lib/src/external/FactorioVersions.ts b/packages/lib/src/external/FactorioVersions.ts index ba6902cb..06b370f7 100644 --- a/packages/lib/src/external/FactorioVersions.ts +++ b/packages/lib/src/external/FactorioVersions.ts @@ -14,6 +14,24 @@ export const ExternalFactorioVersionSchema = Type.Object({ export type ExternalFactorioVersion = Static; +/** CPU architectures Factorio publishes Linux headless builds for */ +export type FactorioHeadlessArch = "x64" | "arm64"; + +/** First Factorio version with an ARM64 Linux headless build */ +export const minimumArm64HeadlessVersion = "2.1.18"; + +/** + * Download URL of the Linux headless build of a Factorio version + * + * @param version - Factorio version to download. + * @param arch - CPU architecture of the build. + * @returns URL redirecting to the tarball. + */ +export function factorioHeadlessUrl(version: string, arch: FactorioHeadlessArch = "x64") { + const build = arch === "arm64" ? "linux-arm64" : "linux64"; + return `https://www.factorio.com/get-download/${version}/headless/${build}`; +} + /** * Fetch all factorio versions that support headless * @@ -60,7 +78,7 @@ function parseFactorioVersions(html: string): ExternalFactorioVersion[] { versions.set(version, { version: version, stable: kind === "stable", - headlessUrl: `https://www.factorio.com/get-download/${version}/headless/linux64`, + headlessUrl: factorioHeadlessUrl(version), }); } } diff --git a/test/host/server.js b/test/host/server.js index 96ca5597..a5fea761 100644 --- a/test/host/server.js +++ b/test/host/server.js @@ -328,6 +328,54 @@ describe("host/server", function() { }); }); + describe(".binaryPath()", function() { + const _platform = process.platform; + const _arch = process.arch; + const installDir = path.join("temp", "test", "binary-path"); + function serverFor(dir) { + return new hostServer.FactorioServer( + installDir, writePath, path.join(installDir, dir, "data"), "2.1.24", { rconPassword: "" } + ); + } + function mockHost(platform, arch) { + Object.defineProperty(process, "platform", { value: platform }); + Object.defineProperty(process, "arch", { value: arch }); + } + before(async function() { + await fs.rm(installDir, { force: true, recursive: true }); + const layouts = [["none", []], ["x64", ["x64"]], ["arm64", ["arm64"]], ["both", ["x64", "arm64"]]]; + for (const [dir, arches] of layouts) { + await fs.mkdir(path.join(installDir, dir, "data"), { recursive: true }); + for (const arch of arches) { + await fs.mkdir(path.join(installDir, dir, "bin", arch), { recursive: true }); + await fs.writeFile(path.join(installDir, dir, "bin", arch, "factorio"), ""); + } + } + }); + afterEach(function() { + mockHost(_platform, _arch); + }); + const binary = (dir, arch) => path.join(installDir, dir, "bin", arch, "factorio"); + for (const [platform, arch, dir, expected] of [ + ["linux", "x64", "both", "x64"], + ["linux", "arm64", "both", "arm64"], + ["linux", "x64", "arm64", "arm64"], + ["linux", "arm64", "x64", "x64"], + ["linux", "x64", "none", "x64"], + ["linux", "arm64", "none", "arm64"], + ["win32", "arm64", "none", "x64"], + ]) { + it(`should pick bin/${expected} on ${platform} ${arch} with ${dir} installed`, function() { + mockHost(platform, arch); + assert.equal(serverFor(dir).binaryPath(), binary(dir, expected)); + }); + } + it("should use MacOS/factorio on darwin", function() { + mockHost("darwin", "arm64"); + assert.equal(serverFor("both").binaryPath(), path.join(installDir, "both", "MacOS", "factorio")); + }); + }); + describe("._handleIpc()", function() { it("should emit the correct ipc event", async function() { let waiter = events.once(server, "ipc-channel"); @@ -760,15 +808,46 @@ describe("host/server", function() { stable: false, version: "0.1.0", headlessUrl: "test3", - }], logger), new Error("Failed to fetch test1: -1 Fetch called")); + }], logger), /Failed to fetch \S+\/get-download\/0\.1\.5\/headless\/linux64/); - assert.equal(fetchCalledWith, "test1"); + assert.equal(fetchCalledWith, "https://www.factorio.com/get-download/0.1.5/headless/linux64"); assert.ok(logLine !== null); assert.ok(logLine.endsWith("starting download...")); }); }); /* eslint-enable no-loop-func */ } + describe("on ARM64 Linux", function() { + const _arch = process.arch; + const factorioDir = path.join("test", "file", "factorio"); + beforeEach(function() { + Object.defineProperty(process, "platform", { value: "linux" }); + Object.defineProperty(process, "arch", { value: "arm64" }); + }); + afterEach(function() { + Object.defineProperty(process, "arch", { value: _arch }); + }); + const versions = [ + { stable: false, version: "2.1.25", headlessUrl: "test1" }, + { stable: true, version: "2.1.17", headlessUrl: "test2" }, + { stable: true, version: "0.1.5", headlessUrl: "test3" }, + ]; + it("should download the linux-arm64 build", async function() { + await assert.rejects(hostServer.checkForUpdates(factorioDir, "latest", versions), /Fetch called/); + assert.equal(fetchCalledWith, "https://www.factorio.com/get-download/2.1.25/headless/linux-arm64"); + }); + it("should reject versions older than 2.1.18", async function() { + await assert.rejects( + hostServer.checkForUpdates(factorioDir, "2.1.17", versions), + /Factorio 2.1.17 has no ARM64 Linux headless build to download, ARM64 builds start at 2.1.18/ + ); + assert.equal(fetchCalledWith, null); + }); + it("should accept an older version that is already installed", async function() { + await hostServer.checkForUpdates(factorioDir, "0.1", versions); + assert.equal(fetchCalledWith, null); + }); + }); describe("concurrent downloads", function() { const versions = [{ stable: true, version: "0.1.5", headlessUrl: "test1" }]; diff --git a/test/lib/external/FactorioVersions.test.js b/test/lib/external/FactorioVersions.test.js index b87d9016..5f15b140 100644 --- a/test/lib/external/FactorioVersions.test.js +++ b/test/lib/external/FactorioVersions.test.js @@ -1,10 +1,23 @@ import assert from "node:assert/strict"; import { readFile } from "node:fs/promises"; -import { fetchFactorioVersions } from "@clusterio/lib"; +import { factorioHeadlessUrl, fetchFactorioVersions } from "@clusterio/lib"; import { slowTest, externalTest } from "../../common.js"; describe("FactorioVersions", function() { + describe("factorioHeadlessUrl", function() { + it("should return the linux64 build by default", function() { + assert.equal( + factorioHeadlessUrl("2.1.24"), "https://www.factorio.com/get-download/2.1.24/headless/linux64" + ); + }); + it("should return the linux-arm64 build for arm64", function() { + assert.equal( + factorioHeadlessUrl("2.1.24", "arm64"), + "https://www.factorio.com/get-download/2.1.24/headless/linux-arm64", + ); + }); + }); describe("fetchFactorioVersions", function() { const originalFetch = global.fetch; From 62f17a20afdc2e7d8fd66c22414458b00d8b32bc Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Wed, 18 Nov 2026 11:15:40 +0000 Subject: [PATCH 2/2] Take platform and arch in the lib headless helpers hasFactorioHeadless(version, platform, arch) replaces the host's hasArm64Headless, and factorioHeadlessUrl takes the platform too and throws when Factorio has no headless build for it, which for now is every platform except Linux. headlessUrl is marked deprecated. Co-Authored-By: Claude Opus 5.5 --- packages/host/src/server.ts | 8 +--- packages/lib/src/external/FactorioVersions.ts | 44 ++++++++++++++++--- test/lib/external/FactorioVersions.test.js | 34 ++++++++++++-- 3 files changed, 70 insertions(+), 16 deletions(-) diff --git a/packages/host/src/server.ts b/packages/host/src/server.ts index 9c4f8d7f..c5d01365 100644 --- a/packages/host/src/server.ts +++ b/packages/host/src/server.ts @@ -191,10 +191,6 @@ function factorioArch(): lib.FactorioHeadlessArch { return process.platform === "linux" && process.arch === "arm64" ? "arm64" : "x64"; } -function hasArm64Headless(version: lib.FullVersion) { - return lib.integerFullVersion(version) >= lib.integerFullVersion(lib.minimumArm64HeadlessVersion); -} - // Factorio downloads in progress by target directory, shared by every server in the process const downloadsInProgress = new Map>(); @@ -221,7 +217,7 @@ export async function checkForUpdates( const arch = factorioArch(); const matching = availableVersions.filter(v => matchesTarget(v.version)); const latestVersion = matching - .filter(v => arch !== "arm64" || hasArm64Headless(v.version)) + .filter(v => process.platform !== "linux" || lib.hasFactorioHeadless(v.version, "linux", arch)) .sort((v1, v2) => versionOrder(v1.version, v2.version)) [0]; @@ -268,7 +264,7 @@ export async function checkForUpdates( logger.info(`A newer version of factorio is available (${v}), waiting for download...`); } else { logger.info(`A newer version of factorio is available (${v}), starting download...`); - download = downloadAndExtractTar(lib.factorioHeadlessUrl(v, arch), dst).finally(() => { + download = downloadAndExtractTar(lib.factorioHeadlessUrl(v, "linux", arch), dst).finally(() => { downloadsInProgress.delete(dst); }); downloadsInProgress.set(dst, download); diff --git a/packages/lib/src/external/FactorioVersions.ts b/packages/lib/src/external/FactorioVersions.ts index 06b370f7..e04724cf 100644 --- a/packages/lib/src/external/FactorioVersions.ts +++ b/packages/lib/src/external/FactorioVersions.ts @@ -1,5 +1,5 @@ import { Static, Type } from "@sinclair/typebox"; -import { FullVersionSchema, integerFullVersion, isFullVersion } from "../data/version.js"; +import { FullVersion, FullVersionSchema, integerFullVersion, isFullVersion } from "../data/version.js"; const ARCHIVE_URL = "https://factorio.com/download/archive/"; @@ -9,25 +9,57 @@ const ARCHIVE_URL = "https://factorio.com/download/archive/"; export const ExternalFactorioVersionSchema = Type.Object({ stable: Type.Boolean(), version: FullVersionSchema, + /** @deprecated Linux x64 only, use {@link factorioHeadlessUrl} instead. */ headlessUrl: Type.String(), }); export type ExternalFactorioVersion = Static; -/** CPU architectures Factorio publishes Linux headless builds for */ +/** Platforms Factorio may publish headless builds for, named as in Node's process.platform */ +export type FactorioHeadlessPlatform = "linux" | "win32"; + +/** CPU architectures Factorio may publish headless builds for, named as in Node's process.arch */ export type FactorioHeadlessArch = "x64" | "arm64"; /** First Factorio version with an ARM64 Linux headless build */ export const minimumArm64HeadlessVersion = "2.1.18"; /** - * Download URL of the Linux headless build of a Factorio version + * Check if Factorio publishes a headless build of a version + * + * @param version - Factorio version to check. + * @param platform - Platform of the build. + * @param arch - CPU architecture of the build. + * @returns true if the build can be downloaded. + */ +export function hasFactorioHeadless( + version: FullVersion, + platform: FactorioHeadlessPlatform, + arch: FactorioHeadlessArch, +) { + if (platform !== "linux") { + return false; + } + return arch === "x64" || integerFullVersion(version) >= integerFullVersion(minimumArm64HeadlessVersion); +} + +/** + * Download URL of the headless build of a Factorio version * * @param version - Factorio version to download. + * @param platform - Platform of the build. * @param arch - CPU architecture of the build. - * @returns URL redirecting to the tarball. + * @returns URL redirecting to the archive. + * @throws Error if Factorio has no headless build for the platform and arch. */ -export function factorioHeadlessUrl(version: string, arch: FactorioHeadlessArch = "x64") { +export function factorioHeadlessUrl( + version: FullVersion, + platform: FactorioHeadlessPlatform, + arch: FactorioHeadlessArch, +) { + if (!hasFactorioHeadless(version, platform, arch)) { + throw new Error(`Factorio ${version} has no headless build for ${platform} ${arch}`); + } const build = arch === "arm64" ? "linux-arm64" : "linux64"; return `https://www.factorio.com/get-download/${version}/headless/${build}`; } @@ -78,7 +110,7 @@ function parseFactorioVersions(html: string): ExternalFactorioVersion[] { versions.set(version, { version: version, stable: kind === "stable", - headlessUrl: factorioHeadlessUrl(version), + headlessUrl: factorioHeadlessUrl(version, "linux", "x64"), }); } } diff --git a/test/lib/external/FactorioVersions.test.js b/test/lib/external/FactorioVersions.test.js index 5f15b140..083a9e9a 100644 --- a/test/lib/external/FactorioVersions.test.js +++ b/test/lib/external/FactorioVersions.test.js @@ -1,22 +1,48 @@ import assert from "node:assert/strict"; import { readFile } from "node:fs/promises"; -import { factorioHeadlessUrl, fetchFactorioVersions } from "@clusterio/lib"; +import { factorioHeadlessUrl, fetchFactorioVersions, hasFactorioHeadless } from "@clusterio/lib"; import { slowTest, externalTest } from "../../common.js"; describe("FactorioVersions", function() { + describe("hasFactorioHeadless", function() { + for (const [version, platform, arch, expected] of [ + ["0.17.79", "linux", "x64", true], + ["2.1.17", "linux", "arm64", false], + ["2.1.18", "linux", "arm64", true], + ["2.1.24", "win32", "x64", false], + ["2.1.24", "win32", "arm64", false], + ]) { + it(`should return ${expected} for ${version} ${platform} ${arch}`, function() { + assert.equal(hasFactorioHeadless(version, platform, arch), expected); + }); + } + }); describe("factorioHeadlessUrl", function() { - it("should return the linux64 build by default", function() { + it("should return the linux64 build for x64", function() { assert.equal( - factorioHeadlessUrl("2.1.24"), "https://www.factorio.com/get-download/2.1.24/headless/linux64" + factorioHeadlessUrl("2.1.24", "linux", "x64"), + "https://www.factorio.com/get-download/2.1.24/headless/linux64", ); }); it("should return the linux-arm64 build for arm64", function() { assert.equal( - factorioHeadlessUrl("2.1.24", "arm64"), + factorioHeadlessUrl("2.1.24", "linux", "arm64"), "https://www.factorio.com/get-download/2.1.24/headless/linux-arm64", ); }); + it("should throw for Windows", function() { + assert.throws( + () => factorioHeadlessUrl("2.1.24", "win32", "x64"), + new Error("Factorio 2.1.24 has no headless build for win32 x64"), + ); + }); + it("should throw for linux arm64 before 2.1.18", function() { + assert.throws( + () => factorioHeadlessUrl("2.1.17", "linux", "arm64"), + new Error("Factorio 2.1.17 has no headless build for linux arm64"), + ); + }); }); describe("fetchFactorioVersions", function() { const originalFetch = global.fetch;