Commit Graph
273 Commits
Author SHA1 Message Date
Cooldude2606 1a016372c1 Merge pull request #1232 from bbassie/feature/wait-for-plugin
Add waitForPlugin and load plugins concurrently
2026-11-22 13:14:30 +00:00
Cooldude2606 9dd5b48056 Merge pull request #1263 from bbassie/docs/admin-guide
Add a cluster management guide and complete the clusterioctl docs
2026-11-22 01:04:20 +00:00
Cooldude2606 834f8472df Clarify role permission warnings in documentation
Rephrase warnings about role permissions for clarity.
2026-11-22 01:00:13 +00:00
bbassieandClaude Opus 5.5 af97b1b789 Address review of the cluster management docs
- Explain the host field and Start after creation in the create modal
- Mention Restart and listing in the in-game server browser
- Say where the Factorio credentials come from and what sharing them
  with hosts means
- Explain that built in mods can be disabled but not removed
- Accounts are created for joining players with or without save
  patching, the host falls back to reading joins from the server log
- Roles only need permissions on top of Player, and warn about
  dangerous permissions and role self-assignment
- clusterioctl can live in any directory on any computer, and the web
  interface can download its config

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 00:39:47 +00:00
bbassieandClaude Opus 5.5 3c03574106 Add a guide for managing a cluster
docs/managing-a-cluster.md goes through the day to day tasks in the
web interface: logging in, hosts, instances, saves, mod packs, users
and roles, plugins and logs, each linking to the matching ctl
commands. It explains the data export needed for item icons, names
and mod settings, including that a host with only the headless build
exports no base game icons.

The mod section of the README moves into the guide so there is one
copy of it, and the README points to the guide and the ctl docs.

Part of #1254

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 00:00:06 +00:00
bbassieandClaude Opus 5.5 fb93962972 Document clusterioctl setup and the missing commands
Adds a setup section covering the installer, create-ctl-config, a
hand-made config and self-signed certificates. Documents the commands
that were missing or marked "To be written": controller and host
stop, restart and config, instance start, restart, stop, start-all,
stop-all, load-scenario, delete, send-rcon and export-data, saves,
config set-prop, mods, mod packs, user show and revoke-token, roles,
permissions and logs.

Part of #1254

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 00:00:06 +00:00
bbassieandClaude Opus 5.5 2a7a333b95 Rename managing-a-cluster.md to clusterioctl.md
The document is a reference for the clusterioctl commands. The name
is freed up for a guide to managing a cluster.

Part of #1254

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 00:00:06 +00:00
bbassieandClaude Opus 5.5 a6b44e78d6 Tidy up web interface buttons and labels
Rename save Copy to Duplicate, shorten the save buttons, move Load
scenario into the instance control button and Create template into
More, square off the online players table, show the bind address and
public URL on the controller page, restyle the user settings like the
role page, add a favicon with a controller.favicon_url override, and
put the page name in the tab title.

Closes #1260

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 22:03:02 +00:00
bbassieandClaude Opus 5.5 079340e5dd Reset crash restart attempts on a manual start
A stop is always followed by a start, so the start is the one place that
needs it. The crash restart calls _startSave directly to keep its count.
Rename _runningSinceMs to _startedAtMs to match InstanceDetails.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 16:29:03 +00:00
bbassieandClaude Opus 5.5 565e931a96 Restart instances that crash after running for 10 minutes
Adds instance.restart_after_crash (default off) and
instance.crash_retry_attempts (default 3, 0 for no limit). The host only
restarts an instance that ran for at least 10 minutes before exiting
unexpectedly, so a boot loop stops after one crash. A user stop, kill or
restart resets the count; it is not persisted across host restarts.

Closes #1251

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 15:55:28 +00:00
bbassieandClaude Opus 5.5 3ca203c753 Stop prepare_release on changelog problems unless --force
generateReleaseNotes() returns the errors and warnings from the pull
request changelogs instead of printing them. prepare_release.mts lists
them and aborts before touching any file, --force continues anyway.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 02:56:38 +00:00
bbassieandClaude Opus 5.5 8e01a96df9 Add a prepare release script
scripts/prepare_release.mts takes a version, sets it in the package.json
files under packages/ and plugins/, adds the pr_to_changelog.mts output to
the top of CHANGELOG.md, then commits "Prepare <version>" and tags it
v<version>. It does not push.

pr_to_changelog.mts now exports generateReleaseNotes() so the output can
be reused. The template comment in CHANGELOG.md is removed so the first
"## " heading is always the latest release.

Closes #1240

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 02:28:33 +00:00
Bastiaan 8692ea3941 Merge pull request #1241 from bbassie/chore/move-root-scripts
Move clean and publish scripts into scripts folder
2026-11-21 02:23:48 +00:00
bbassieandClaude Opus 5.5 47c84fc289 Add checkEnabled and rename plugin loading files
plugins.checkEnabled(name) tells if a plugin is in the load list.
#plugin_module is renamed to #import_plugin. loadPluginMigrations moves
into PluginLoader.ts, leaving plugin_loader.ts with plugin discovery and
details, so it is renamed to plugin_info.ts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 22:17:12 +00:00
bbassieandClaude Opus 5.5 2e273dc630 Take a burst allowance off what a transfer check requires
controller.transfer_min_speed is now the speed that is never closed.
A check requires that speed over 60 s less 2 MiB, which covers the
bursts the OS sends data in, so at the default of 64 KiB/s the cutoff
is about 30 KiB/s. The requirement is at least 1 byte, so a transfer
that moved nothing is still closed at low settings.

The slow receiver test sends 16 MiB so that it spans real checks, and
two upload tests with set bursts cover the allowance.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 22:13:51 +00:00
bbassieandClaude Opus 5.5 c1ea4d470b Load all plugin types through one short lived PluginLoader
PluginLoader.load takes the plugin type, context, export name and base
class as options and is used by the controller, host, instance, ctl, web
interface and migrations. Module imports go through #plugin_module so the
node variant stays out of the web bundle. loadPlugin.ts and the loading
half of plugin_loader.ts are merged into it.

The loader lives for one load. Plugins reach it through context.plugins,
with waitFor(name, timeoutMs) and checkInstalled(name), replacing the
waitForPlugin methods. Waiting on a plugin that is not in the load list or
failed to load settles right away, as loading can't finish while the
waiting entrypoint is still running.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 21:29:23 +00:00
bbassie 7f688d2ed0 Merge remote-tracking branch 'upstream/master' into feature/wait-for-plugin 2026-11-20 21:13:53 +00:00
bbassieandClaude Opus 5.5 42bc31e406 Check transfer speed over 60 seconds
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 20:59:37 +00:00
bbassieandClaude Opus 5.5 19569aefa4 Measure transfer_min_speed in KiB/s and raise it to 64
The guard measures a proxy stream on completed writes to the receiver.
The OS buffers a couple of MiB per connection and only takes more once
a large part has been sent, so a slow receiver can go a long time with
no write completing. At the old default of 30 KiB per 30 s, downloads
well above that could be closed, and the slow receiver test failed
every run on Linux.

controller.transfer_min_progress (KiB per 30 s) is replaced by
controller.transfer_min_speed (KiB/s), defaulting to 64. At that speed
the measured 1.6 MB bursts come within the 30 second check. Configs
on the old default move to the new one, other values are converted.
The slow receiver test checks every 3 s instead of 500 ms, as with a
500 ms check it fails at any minimum.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 20:59:37 +00:00
Cooldude2606 34deacb881 Merge pull request #1230 from bbassie/feature/ctl-output-json
Add --output json to clusterioctl
2026-11-20 15:22:38 +00:00
bbassieandClaude Opus 5.5 23187859d6 Address second review of ctl --output
CommandOutput.error takes a human reporter like result, so command errors log their message in human mode and print JSON in json and wire mode. table takes a map applied to each row in human mode, which note list, host plugin list, user list and save list now use. Rename streaming to streamingLog, and print startup errors with errorToJson directly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 15:56:48 +00:00
bbassieandClaude Opus 5.5 bf33f4f52e Refuse to start without required mods and download them
requiredMods entries are now Factorio dependency strings, and a mod
listed twice gives a version range. The plugin loader validates them.

The host refuses to start an instance whose mod pack is missing a
required mod of a loaded plugin, has it disabled or has it outside the
version range.

On start the controller resolves the required mods of its plugins and
their dependencies for the default mod pack's Factorio version and
downloads the ones missing from the mod store. The resolver and portal
download move from the ControlConnection handlers into Controller
methods so both paths share them.

Subspace Storage requires subspace_storage >= 1.99.0, and the
integration tests build a stub of that mod for the test mod pack.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 15:19:05 +00:00
bbassieandClaude Opus 5.5 a845b7ac52 Add requiredMods to plugin declarations
Plugins can list the Factorio mods they need under requiredMods. When an
instance starts, the host warns in the instance log about each loaded
plugin whose required mods are missing or disabled in the mod pack.
Subspace Storage declares the subspace_storage mod.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 15:07:06 +00:00
bbassieandClaude Opus 5.5 c8e52e7bde Add waitForPlugin and load plugins concurrently
Plugins can wait for another plugin on the same controller, host or
instance with waitForPlugin(waiter, name, timeoutMs). It resolves to what
the other plugin's entrypoint returned, or to undefined with a warning
naming both plugins if it is not loaded once loading finishes or the
timeout runs out.

Plugin entrypoints now run concurrently so a plugin can await a plugin
later in the list from its entrypoint. loadedPlugins is still filled in
plugin list order, as the instance builds its Lua module list from it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 14:24:56 +00:00
bbassieandClaude Opus 5.5 8550df69eb Address review of ctl --output
Add a wire output format that prints the toJSON format sent over the link. Commands without a result print {"success": true}, or "Command ran successfully" in human mode. The missing URL check throws a StartupError, unexpected command errors are rethrown to the startup handler, and startup errors log as fatal. user list, note list and host plugin list print the objects they received instead of their table rows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 16:48:40 +00:00
bbassieandClaude Opus 5.5 10beffe167 Add --output json to clusterioctl
Commands print their results through a CommandOutput on the ctl link.
In json mode lists print as arrays of objects, other results as an
object, commands without a result print {} and failures print
{ error: ClassName, message } with exit code 1. log follow and
debug dump-ws print JSON lines.

Human output now goes through the shared asTable printer in every
command, results that were logged to stderr (role create, save and mod
upload/download) print to stdout, and config edit failures are logged
instead of printed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 13:07:18 +00:00
bbassieandClaude Opus 5.5 5aaea1f213 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 <noreply@anthropic.com>
2026-11-18 11:14:54 +00:00
bbassieandClaude Opus 5.5 6363f15cb9 Replace SILENT_TEST and VERBOSE_TEST with TEST_OUTPUT
The reporter now handles all three modes: verbose prints everything,
normal prints output from failing tests and hooks, silent prints only
the results. The integration spawn helper and setup_logging no longer
filter output themselves.

npm install output in plugin install now goes through the logger
instead of inherited stdio, so it follows the log level and is
captured in tests like the rest.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 12:31:45 +00:00
bbassieandClaude Opus 5.5 838a43428b Only print test output for failing tests
A spec reporter subclass buffers console output, including winston's
ConsoleTransport and the integration child process lines, and prints it
above the failure line when a test or hook fails. VERBOSE_TEST streams
everything as before, and CI sets it on debug re-runs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 12:27:29 +00:00
BastiaanandClaude Opus 5.5 42e2e0284b Document the real user import and export commands (#1217)
The managing a cluster guide listed whitelist-bulk-import,
admin-bulk-import and banned-bulk-import, which don't exist. Describe
user import, restore and export with the JSON formats they read and
write. Also reword the README known issue now that the installer no
longer offers server_select and discord_bridge.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 11:11:45 +00:00
BastiaanandClaude Opus 5.5 c2c7edf1b7 Default to the newest Base Game pack on new clusters (#1216)
A new cluster gets the default mod packs but controller.default_mod_pack_id
stays null, so the first Create save or Start fails with "Default mod pack
not set on controller". When seeding the packs, also point the default at
the newest Base Game pack, unless an admin already set one. Clusters that
already have mod packs are left alone. The config is written with the
mod packs on the next autosave or shutdown.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 11:03:22 +00:00
Daniel 79ef9aaeb0 Merge branch 'master' into fix/stream-reject-closes-connection 2026-11-13 23:17:41 +01:00
Danielv123 b31983e30b Close requests moving too little instead of idle ones
Replace controller.transfer_idle_timeout with
controller.transfer_min_progress, the amount a request has to move
every 30 seconds, so a request trickled in is closed too. The check
now runs for every route.

Both ends of a proxy stream are judged on what the receiver has taken,
so a sender held back by a slow receiver is not closed.

Keep the limit on receiving headers, which turning off the request
timeout also turned off.
2026-11-13 22:59:12 +01:00
Bastiaan e37bf31cd3 Merge pull request #1200 from bbassie/feature/log-retention
Delete log files older than a configurable number of days
2026-11-13 19:30:24 +00:00
Danielv123 49ddc9ebd1 Stop reading all rejected uploads and close stalled transfers
Guard the export, save, mod and stream routes with one middleware that
closes the connection of an upload answered before its body was read,
and of a transfer that has made no progress for the new
controller.transfer_idle_timeout.

The save and mod uploads share one handler that responds on the first
error instead of reading the rest of the upload, and uploads cut short
now fail the transfer instead of leaving it hanging.

Node's 5 minute limit on receiving a request is turned off so large
uploads over slow connections are not cut off.
2026-11-10 21:59:03 +01:00
Danielv123 60a4b103ab Merge remote-tracking branch 'origin/master' into fix/stream-reject-closes-connection 2026-11-10 21:32:23 +01:00
Cooldude2606andClaude Opus 5.5 7cf9cf8d3e Unpatch saves started with save patching disabled (#1184)
* Unpatch saves started with save patching disabled

Turning factorio.enable_save_patching off did nothing to a save that
was patched before. Its control.lua still loaded every module, so the
clusterio_api interface, player_sync's join handling and the other
module event handlers kept running with no plugin on the host side.

When patching is disabled the instance now restores the original
control.lua that patching kept as scenario.lua and removes the module
files, locale files included, as listed in clusterio.json. The patch
info stays with an empty module list so the patch number keeps
counting. Otherwise patching the save again would reuse the number
stored in the game and on_server_startup would not be raised. Data
the modules put in storage is left alone.

PatchInfo.fromSave dropped the version read from the save, so the
check against newer patch versions never fired. It now keeps it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Remove scenario.lua when unpatching a save

Unpatching moves scenario.lua back to control.lua instead of copying it, so the save only keeps clusterio.json for the patch number. Patching such a save again copies control.lua back to scenario.lua.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 20:58:13 +00:00
Bastiaan 4a2c164188 Merge pull request #1183 from bbassie/fix/save-patching-plugin-default
Default load_plugin to off when the instance lacks required features
2026-11-04 01:19:10 +00:00
bbassieandClaude Opus 5.5 4c6aed3cff Return the host record from verifyHostToken
Matches verifyUserToken returning the user. HostConnection._saveInfo is
renamed saveRecord to match User.saveRecord.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 00:37:37 +00:00
bbassieandClaude Opus 5.5 e6554e09c7 Add HostManager for host records and host tokens
controller.hosts is now a HostManager wrapping the hosts datastore, the
same way controller.users wraps the users datastore. It owns creating
hosts (moved from HostPairingManager), revoking them (moved from
ControlConnection) and signing and verifying host tokens (moved from
Controller, generateHostToken is renamed signHostToken to match
signUserToken).

UserManager gains verifyUserToken, replacing the copies of the user
token check in WsServer and routes. The WsServer copy accepted a token
without iat when the user had no tokenValidAfter; the shared check
always requires iat, which jsonwebtoken adds by default.

Follows Cooldude2606's comment on #1161.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 00:37:37 +00:00
bbassieandClaude Opus 5.5 ca3dbab49d Unpatch saves started with save patching disabled
Turning factorio.enable_save_patching off did nothing to a save that
was patched before. Its control.lua still loaded every module, so the
clusterio_api interface, player_sync's join handling and the other
module event handlers kept running with no plugin on the host side.

When patching is disabled the instance now restores the original
control.lua that patching kept as scenario.lua and removes the module
files, locale files included, as listed in clusterio.json. The patch
info stays with an empty module list so the patch number keeps
counting. Otherwise patching the save again would reuse the number
stored in the game and on_server_startup would not be raised. Data
the modules put in storage is left alone.

PatchInfo.fromSave dropped the version read from the save, so the
check against newer patch versions never fired. It now keeps it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 00:16:52 +00:00
bbassieandClaude Opus 5.5 f14bfc3222 Address review of template inheritance
- Unlinking a field enables Apply on its own and sends the current value.
- The link button no longer toggles the checkbox of its label.
- Link and disconnect icons for all four states, pending ones highlighted.
- instance.is_template is hidden.
- ctl create takes --as-template.
- Clearer names for the InstanceManager inheritance helpers.

Part of #200

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 11:57:01 +00:00
bbassieandClaude Opus 5.5 b584991f5c Give templates their own table and keep rcon_password per instance
The templates table shows name, inheritor count and a create instance
action instead of the instance status and start/stop columns.
factorio.rcon_password joins the ports as never inherited.

Part of #200

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 11:54:37 +00:00
bbassieandClaude Opus 5.5 b5c372f109 Rename bases to templates and add per property inheritance
Review changes for #1142:
- base becomes template everywhere (is_template, template_id,
  --template, --is-template, --templates, InstanceDetails.isTemplate).
- Object fields inherit per property. inherited_fields lists the
  overridden properties for object fields and the template object is
  merged with them.
- Linking a template also inherits fields that hold the default value.
  The server name stays per instance.
- Ports are never inherited.
- InstanceDetails carries templateId.

Web UI: inherited values are locked until unlocked, overridden values
can be inherited again, templates are listed separately, the create
modal can create templates and instances from templates, and the
instance page has "Create template" which can link the source.

Part of #200

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 11:54:37 +00:00
bbassieandClaude Opus 5.5 01cf789f5d Add base instances for instance config inheritance
Instances can be marked as a base with instance.is_base and other
instances inherit config values from it through instance.base_id.
The controller copies base values into inheriting configs and keeps
track of inherited fields in the hidden instance.inherited_fields, so
hosts receive resolved configs and need no changes. Setting a field
stops inheriting it, `instance config inherit` undoes that.

Bases cannot be assigned to a host, are hidden from `instance list`
unless --bases is given, and cannot be deleted or unmarked while
other instances inherit from them. Chains of bases are allowed and
cycles are rejected.

Part of #200

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 11:54:21 +00:00
024d7b427a Rename safeOutputFile to atomicOverwriteFile (#1167)
"safe" suggested the data being written survives a crash, it only
guarantees the old file is either kept or fully replaced. The new name
says what it does. No alias, plugin API breaks are allowed in minor
versions and the 2.1 migration guide lists the rename.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Cooldude2606 <25043174+Cooldude2606@users.noreply.github.com>
2026-11-01 23:14:31 +00:00
bbassieandClaude Opus 5.5 37d74ca2a6 Find a full install in host.factorio_directory instead of a setting
Per review, drop host.factorio_graphics_directory. findVersion takes a
headless option that filters installs by build, telling them apart by
data/base/graphics/icons. When the instance runs the headless build the
export looks for a full install of the same major.minor version in the
host's factorio directory. Server startup is unchanged.

If none is found the export still runs, and the reason is included in
the missing icons warning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 20:53:05 +00:00
Danielv123 46c6153201 Export without the graphics directory when it has no matching install
If host.factorio_graphics_directory had no install matching the major and
minor version of the instance, or did not exist, findVersion threw and the
whole export failed. Without the setting the same instance exports everything
except the base game icons, so it now logs a warning that names the setting
and exports without it.
2026-11-01 18:33:10 +01:00
Danielv123 46fd7fcad4 Merge remote-tracking branch 'origin/master' into fix/headless-export-icons 2026-11-01 18:32:20 +01:00
Daniel e251bf0072 Merge pull request #1174 from clusterio/fix/dev-plugin-shared-modules
Serve the web interface from source with --dev-plugin
2026-11-01 18:25:08 +01:00