Compare commits

...
57 Commits
Author SHA1 Message Date
Cooldude2606 bbcb64d411 Prepare 2.1.2 2026-11-22 15:33:27 +00:00
Cooldude2606andClaude Opus 5.5 43abe3bb2b Move developer docs to docs/devs (#1262)
* Move developer docs to docs/devs

docs/ now holds the documents for people running a cluster, and
docs/devs/ holds the ones for Clusterio and plugin developers. Links
to the moved files are updated across the repository.

Adds an Audiences decision recording which document covers what.

Part of #1254

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

* Moving CONTRIBUTING.md to root

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Cooldude2606 <25043174+Cooldude2606@users.noreply.github.com>
2026-11-22 15:31:53 +00:00
Cooldude2606 38cfd3d08c Moving CONTRIBUTING.md to root 2026-11-22 15:26:00 +00:00
bbassieandClaude Opus 5.5 95f808a02f Move developer docs to docs/devs
docs/ now holds the documents for people running a cluster, and
docs/devs/ holds the ones for Clusterio and plugin developers. Links
to the moved files are updated across the repository.

Adds an Audiences decision recording which document covers what.

Part of #1254

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 15:26:00 +00:00
Bastiaan 0190394a99 Merge pull request #1264 from bbassie/docs/split-2.0-changelog
Split the early 2.0 changelog into alpha releases
2026-11-22 14:36:09 +00:00
Cooldude2606 d11afb8742 Merge pull request #1249 from bbassie/feature/scroll-restoration
Remember scroll position on back/forward and reload
2026-11-22 13:14:50 +00:00
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
Cooldude2606 677679ac26 Merge pull request #1261 from bbassie/fix/webui-nits-1260
Small web interface button and label changes
2026-11-22 00:01:16 +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 53ddcb1d27 Test cluster name escaping and favicon_url in serveWeb
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:57:09 +00:00
bbassieandClaude Opus 5.5 555f444447 Stage the ban and put the user switches on one row
The Banned switch is now a staged edit like the roles and ban reason,
so Apply sends one ban that includes the reason. The ban reason only
shows while Banned is on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:52:42 +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
Cooldude2606andClaude Opus 5.5 8865038af5 Add bulk save actions and name search to the saves table (#1256)
* Add save selection, name search and bulk transfer to the saves table

Rows get checkboxes and the header checkbox selects every save matching
the name search, including those on other pages. Selected saves can be
copied or moved to another instance in one go, with copy on by default.

Closes #1253

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

* Add bulk copy, download and delete for selected saves

Copy picks name-2.zip, name-3.zip and so on, skipping names already
taken, because the host refuses to overwrite on copy. Downloads use a
link with the download attribute so several in a row do not cancel
each other.

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

* Drop bulk copy from the selected saves actions

Copy on the same instance is rarely needed in bulk, and Transfer with
Copy ticked covers copying to another instance.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 21:50:09 +00:00
bbassieandClaude Opus 5.5 f338c5fd91 Drop bulk copy from the selected saves actions
Copy on the same instance is rarely needed in bulk, and Transfer with
Copy ticked covers copying to another instance.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 21:10:38 +00:00
Bastiaan bee6714ff8 Merge pull request #1258 from bbassie/feature/mod-pack-upload
Add mod upload to the mod pack view
2026-11-21 21:09:38 +00:00
Cooldude2606 ef3b4cb8fc Merge pull request #1257 from bbassie/feature/plugin-dropdown-actions
Let plugins add actions to page dropdowns
2026-11-21 21:05:16 +00:00
bbassieandClaude Opus 5.5 cd2933417a Add bulk copy, download and delete for selected saves
Copy picks name-2.zip, name-3.zip and so on, skipping names already
taken, because the host refuses to overwrite on copy. Downloads use a
link with the download attribute so several in a row do not cancel
each other.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 21:04:04 +00:00
bbassieandClaude Opus 5.5 bd912a8fd4 Respect disabled on the main dropdown button action
A plugin action can be disabled, and it becomes the main button when
the user has no restart permission. Only the main button is disabled so
the menu stays usable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 19:30:18 +00:00
bbassieandClaude Opus 5.5 86befd1231 Let plugins add actions to page dropdowns
Adds control.hooks.pageActions. A plugin returns a function per page
(ControllerPage, HostViewPage, InstanceViewPage, UserViewPage) that is
called during render and returns menu items. Keys are prefixed with the
plugin name. Plugin items go after the built-in ones and before stop and
delete. The user page and instance templates get a More dropdown only
when a plugin adds actions.

Closes #1243

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 19:14:41 +00:00
bbassieandClaude Opus 5.5 73d70cbc91 Add save selection, name search and bulk transfer to the saves table
Rows get checkboxes and the header checkbox selects every save matching
the name search, including those on other pages. Selected saves can be
copied or moved to another instance in one go, with copy on by default.

Closes #1253

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 19:06:38 +00:00
Cooldude2606 516dc1b945 Merge pull request #1252 from bbassie/feature/instance-crash-restart
Restart instances that crash after running for 10 minutes
2026-11-21 17:21:45 +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
Cooldude2606 7a2aade25b Merge pull request #1250 from bbassie/feature/upload-progress
Show upload progress with a cancel button
2026-11-21 15:12:12 +00:00
Cooldude2606andClaude Opus 5.5 2bba4a8ccd Add a prepare release script (#1244)
* 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>

* 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>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 03:05:03 +00:00
BastiaanandClaude Opus 5.5 c03666e749 Add version select to mods in the mod pack view (#1248)
The Version column is now a dropdown of every version of that mod on
the controller, newest first. Versions built for a different Factorio
version than the pack say so, and a pack version missing from the
controller stays listed as "(missing)". Mods with no other version,
built-in mods and removed mods still show plain text.

Closes #1245

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 03:02:15 +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 e1ffb848b1 Define fake DOM globals as non-enumerable in tests
mocha --check-leaks flagged window, document and ResizeObserver set by
the scroll restoration tests. Define them with defineProperty and restore
the original descriptors afterwards.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 02:54:18 +00:00
bbassieandClaude Opus 5.5 fcf858023e Show upload progress with a cancel button for mods and saves
Both pages share a useUploadProgress hook that wraps antd's default
request, lists each upload with bytes sent and a Cancel button, and
notifies with the controller's error message when an upload fails.
Mod uploads showed nothing before, and failures were silent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 02:50:22 +00:00
bbassieandClaude Opus 5.5 faf214e2a1 Remove partial downloads when the stream is cut mid-write
When the connection drops while the body is being written, the pipe
destroys the file stream with an error before it has closed.
events.once then rejects on that error, so the temporary file was
never unlinked. A save upload cancelled from the web UI left a
<name>.tmp.zip in the instance saves folder, listed as a save.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 02:50:22 +00:00
bbassieandClaude Opus 5.5 628e59bf2c Move scroll restoration logic out of the hook for testing
The effects now call a ScrollRestorer class and restoreScroll is exported,
so the tests can drive both against a fake window, sessionStorage and
ResizeObserver. The hook is three lines that wire them to the router.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 02:50:12 +00:00
bbassieandClaude Opus 5.5 33817bbe42 Remember scroll position on back/forward and reload
BrowserRouter has no scroll handling and the browser's own restoration
runs before the page has loaded its data, so it lands short. Track the
window scroll per history entry in sessionStorage and restore it on POP,
retrying as the page grows until it fits, the user scrolls or 5 s pass.
Pushing a new pathname scrolls to the top; query-only pushes (table sort,
filter, page) keep the position.

Closes #1247

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 02:43:57 +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
Cooldude2606 a49841f3fc Merge pull request #1237 from bbassie/fix/stream-slow-receiver-test
Measure transfer_min_speed in KiB/s and raise it to 64
2026-11-20 22:33:08 +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 68c5ea82e7 Cover non-class exports and installation errors in PluginLoader tests
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 21:34:20 +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 e9a11013a4 Merge pull request #1236 from bbassie/chore/web-bundle-zip-zlib
Keep yauzl, browserify-zlib and assert out of the web interface
2026-11-20 20:55:12 +00:00
Cooldude2606andClaude Opus 5.5 59fa8403de Keep yauzl and yazl types out of lib's published declarations (#1235)
* Keep yauzl and yazl types out of lib's published declarations

ZipArchive exposed yauzl.ZipFile and yauzl.Entry in its public members
and zipOutputStream took a yazl.ZipFile, so @types/yauzl and @types/yazl
had to be runtime dependencies of @clusterio/lib. They pull in
@types/node and undici-types, about 2.7 MB in every server install.

Entries are now typed with a local ZipEntry interface, the yauzl
ZipFile is private, and zipOutputStream takes any object with an
outputStream and an error event. ZipWriter.addEntry reads the
compressed bytes through the new ZipArchive.openRawStream. Both type
packages move to devDependencies.

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

* Explain why ZipEntry is a local type

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 20:54:56 +00:00
Bastiaan 1c18dc3661 Merge pull request #1234 from bbassie/chore/inline-daily-rotate
Replace winston-daily-rotate-file with an in-repo transport
2026-11-20 20:54:42 +00:00
Bastiaan 81c7d24867 Merge pull request #1233 from bbassie/chore/drop-chalk
Replace chalk with util.styleText
2026-11-20 20:54:30 +00:00
bbassieandClaude Opus 5.5 c4a9545d28 Explain why ZipEntry is a local type
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 16:11:36 +00:00
bbassieandClaude Opus 5.5 6dc48b6732 Replace node:assert in link with a local assert
The assert polyfill is 28 KB in the web interface bundle and link only
uses it for plain truthiness checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 10:19:04 +00:00
bbassieandClaude Opus 5.5 4d7c1020b0 Use fflate for zlib in the web interface
ModPack and map exchange strings need synchronous inflate and deflate.
In the browser these came from the browserify-zlib polyfill, which
brings pako, assert and util along. The browser build now imports
fflate through a #zlib_sync subpath import, Node.js keeps node:zlib.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 10:18:37 +00:00
bbassieandClaude Opus 5.5 909f6ab08b Move ModInfo.fromModFile to ModStore.readModInfo
Reading a mod zip needs zip_ops, which pulled yauzl into the web
interface bundle through the data classes. ModStore is node only, so
the zip reading now lives there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 10:17:40 +00:00
bbassieandClaude Opus 5.5 aaafce4ace Keep yauzl and yazl types out of lib's published declarations
ZipArchive exposed yauzl.ZipFile and yauzl.Entry in its public members
and zipOutputStream took a yazl.ZipFile, so @types/yauzl and @types/yazl
had to be runtime dependencies of @clusterio/lib. They pull in
@types/node and undici-types, about 2.7 MB in every server install.

Entries are now typed with a local ZipEntry interface, the yauzl
ZipFile is private, and zipOutputStream takes any object with an
outputStream and an error event. ZipWriter.addEntry reads the
compressed bytes through the new ZipArchive.openRawStream. Both type
packages move to devDependencies.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 20:39:58 +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
113 changed files with 4384 additions and 1711 deletions

No files matched your search

+1 -1
View File
@@ -40,7 +40,7 @@ jobs:
node-version: 24.x
- run: pnpm install --no-frozen-lockfile
- run: pnpm -r --filter='./packages/*' --filter='./plugins/*' --fail-if-no-match run build-mod --output-dir ../../dist
- run: node ./publish.js factorio ./dist
- run: node ./scripts/publish.js factorio ./dist
env:
FACTORIO_TOKEN: ${{ secrets.FACTORIO_TOKEN }}
- uses: softprops/action-gh-release@v3
+7 -7
View File
@@ -2,13 +2,13 @@
Clusterio manages distributed Factorio servers through a controller, hosts, and plugins.
Read [contributing](docs/contributing.md) for the project map, setup, commands, debugging, tests, and code style.
For PR reviews, follow the [review guide](docs/pr-review-guide.md), including its candidate ledger and final evidence audit.
Read [contributing](contributing.md) for the project map, setup, commands, debugging, tests, and code style.
For PR reviews, follow the [review guide](docs/devs/pr-review-guide.md), including its candidate ledger and final evidence audit.
Use the detailed guides for the affected area:
- [Communication and routing](docs/communication.md), [wire protocol](docs/devs/protocol.md), and [configuration](docs/config-system.md).
- [Plugins](docs/writing-plugins.md), [plugin migration](docs/devs/plugin-migration-to-2.0.md), and [Factorio/Lua](docs/developing-for-clusterio.md).
- [Compatibility policies](docs/decisions.md) and [releases](docs/release-workflow.md).
- [Communication and routing](docs/devs/communication.md), [wire protocol](docs/devs/protocol.md), and [configuration](docs/devs/config-system.md).
- [Plugins](docs/devs/writing-plugins.md), [plugin migration](docs/devs/plugin-migration-to-2.0.md), and [Factorio/Lua](docs/devs/developing-for-clusterio.md).
- [Compatibility policies](docs/devs/decisions.md) and [releases](docs/devs/release-workflow.md).
## Working rules
@@ -20,7 +20,7 @@ Use the detailed guides for the affected area:
Update affected documentation in the same change.
- Follow nearby code and `.oxlintrc.json`: tabs, double quotes, semicolons, and `.js` extensions in relative TypeScript imports.
Import shared public APIs through `@clusterio/lib` and check Node/browser exports when changing them.
- Run commands from the root using the pinned pnpm version and the [documented Node requirements](docs/contributing.md#supported-nodejs-and-factorio-versions).
- Run commands from the root using the pinned pnpm version and the [documented Node requirements](contributing.md#supported-nodejs-and-factorio-versions).
Install with `pnpm install --no-frozen-lockfile`; the lockfile is intentionally ignored.
- `pnpm build` compiles TypeScript.
It does not regenerate validators or production web bundles; use the appropriate package's `prepare` script.
@@ -30,7 +30,7 @@ Use the detailed guides for the affected area:
The harness needs Factorio, recreates `temp/test/`, and shares ports 8880/4443; do not run competing suites.
- Report checks, failures, skips, and unverified behavior precisely.
Documentation-only changes need path, command, and formatting checks.
- Preview cleanup with `node clean.js --dry-run`; see the [cleanup scopes](docs/contributing.md#cleaning-generated-and-runtime-files).
- Preview cleanup with `node scripts/clean.js --dry-run`; see the [cleanup scopes](contributing.md#cleaning-generated-and-runtime-files).
Runtime-data deletion and release publication require explicit authorization.
Keep local configs, credentials, runtime data, and generated output out of commits.
- Follow the [PR template](.github/pull_request_template.md), including `### Changelog` (`None.` when appropriate).
+113 -35
View File
@@ -1,35 +1,59 @@
# Changelog
<!-- Template for entries. Add sections that apply as changes are made.
## Version 2.0.0-alpha.xx
### Major Features
- Major additions and/or major improvements to managing clusters.
## Version 2.1.2
### Features
- New features added.
### Changes
- Small changes to existing behaviour.
- Added a version select to mods in the mod pack view. [#1245](<https://github.com/clusterio/clusterio/issues/1245>)
- Added upload progress with a cancel button for mods and saves in the web interface. [#1242](<https://github.com/clusterio/clusterio/issues/1242>)
- Added `instance.restart_after_crash` and `instance.crash_retry_attempts` to restart instances that crash after running for at least 10 minutes. [#1251](<https://github.com/clusterio/clusterio/issues/1251>)
- Plugins can add actions to the dropdown menus on the controller, host, instance and user pages. [#1243](<https://github.com/clusterio/clusterio/issues/1243>)
- Added mod upload to the mod pack view. [#1246](<https://github.com/clusterio/clusterio/issues/1246>)
- Added name search and row selection to the saves table, with buttons to download, transfer or delete the selected saves. [#1253](<https://github.com/clusterio/clusterio/issues/1253>)
- Added the Clusterio logo as the web interface favicon, with `controller.favicon_url` to replace it. [#1260](<https://github.com/clusterio/clusterio/issues/1260>)
- Added the page name to the browser tab title. [#1260](<https://github.com/clusterio/clusterio/issues/1260>)
- Added the bind address and public URL to the controller page. [#1260](<https://github.com/clusterio/clusterio/issues/1260>)
- Added `plugins.waitFor`, `plugins.checkInstalled` and `plugins.checkEnabled` to the plugin load context so plugins can wait for another plugin to load and get the value its entrypoint returned. [#1232](<https://github.com/clusterio/clusterio/pull/1232>)
- The web interface now restores the scroll position when navigating back/forward, reloading the page or returning to it. [#1247](<https://github.com/clusterio/clusterio/issues/1247>)
### Fixes
- Bugfixes
- Fixed proxy stream downloads by a slow receiver being closed while above the minimum transfer speed. [#1237](<https://github.com/clusterio/clusterio/pull/1237>)
- Fixed failed mod uploads in the web interface not showing an error. [#1242](<https://github.com/clusterio/clusterio/issues/1242>)
- Fixed a cancelled save upload leaving a temporary file in the instance saves folder. [#1242](<https://github.com/clusterio/clusterio/issues/1242>)
- Fixed the cluster name not being HTML escaped in the page title. [#1260](<https://github.com/clusterio/clusterio/issues/1260>)
### Changes
- Replaced chalk with Node's built-in `util.styleText`. Factorio output colours in the terminal now respect `NO_COLOR`. [#1233](<https://github.com/clusterio/clusterio/pull/1233>)
- Replaced the winston-daily-rotate-file dependency with a built-in log file transport. Log file names are unchanged. The `.*-audit.json` files in the log directories are no longer used and can be deleted. [#1234](<https://github.com/clusterio/clusterio/pull/1234>)
- `@types/yauzl` and `@types/yazl` are no longer installed with `@clusterio/lib`, which also drops `@types/node` from server installs. [#1235](<https://github.com/clusterio/clusterio/pull/1235>)
- Reduced the size of the web interface by about 100 KB by keeping yauzl, browserify-zlib and the assert polyfill out of it. [#1236](<https://github.com/clusterio/clusterio/pull/1236>)
- Renamed the save Copy button to Duplicate and shortened the save buttons to Load, Upload and Create. [#1260](<https://github.com/clusterio/clusterio/issues/1260>)
- Moved Load scenario into the instance control button and Create template into the More menu. [#1260](<https://github.com/clusterio/clusterio/issues/1260>)
- Restyled the user page settings to match the role page, with the status switches on one row and an unsaved changes bar for roles and bans. [#1260](<https://github.com/clusterio/clusterio/issues/1260>)
- Removed the padding and rounded corners around the online players table. [#1260](<https://github.com/clusterio/clusterio/issues/1260>)
- Plugins now load concurrently instead of one at a time in plugin list order. [#1232](<https://github.com/clusterio/clusterio/pull/1232>)
### Breaking Changes
- Changes which break backwards compatibility with older hosts or plugins code.
- `lib.ZipArchive.zipfile` is now private and archive entries are typed as `lib.ZipEntry` instead of yauzl's `Entry`. Use `ZipArchive.openStream`/`openRawStream` to read entries. TypeScript plugins that relied on `@types/node` coming in through `@clusterio/lib` need to list it in their own devDependencies. [#1235](<https://github.com/clusterio/clusterio/pull/1235>)
- `ModInfo.fromModFile` has been moved to `ModStore.readModInfo`. [#1236](<https://github.com/clusterio/clusterio/pull/1236>)
- Replaced controller.transfer_min_progress (KiB per 30 seconds) with controller.transfer_min_speed, the speed in KiB/s that is never closed for moving too slowly, defaulting to 64. Configs on the old default move to the new one, other values are converted. [#1237](<https://github.com/clusterio/clusterio/pull/1237>)
### Meta
- Changes to the project activities / structure worth highlighting but have no impact on the published package.
- Added `scripts/prepare_release.mts`, which bumps the package versions, adds the changelog and commits and tags a release. [#1240](<https://github.com/clusterio/clusterio/issues/1240>)
### Contributors
Many thanks to the following for contributing to this release:
[@bbassie](<https://github.com/bbassie>)
### Statistics
Commits: 56 Pull Requests: 19 Files Changed: 105 Additions: +4,328 Deletions: -1,710
Many thanks to the following for contributing to this release:
[@username](https://github.com/username)
-->
## Version 2.1.1
@@ -970,7 +994,75 @@ See the [migration guide](https://github.com/clusterio/clusterio/blob/e0755cb4ee
Many thanks to the following for contributing code in this release:
[@Hornwitser](https://github.com/Hornwitser) [@Luciole0x](https://github.com/Luciole0x) [@Cooldude2606](https://github.com/Cooldude2606) [@Danielv123](https://github.com/Danielv123) [@Reavershark](https://github.com/Reavershark) [@Laar](https://github.com/Laar) [@rstrom1763](https://github.com/rstrom1763)
## Version 2.0.0
## Version 2.0.0-alpha.13
### Changes
- Instance names can be any string again.
Characters that are not valid in a file name are replaced with an underscore in the instance folder name.
## Version 2.0.0-alpha.12
### Features
- Added renaming, copying and transferring of saves.
## Version 2.0.0-alpha.8
### Features
- Added Node.js based installer to simplify setting up a cluster.
## Version 2.0.0-alpha.7
### Major Features
- Added remote save management with the ability to list, create, upload, download, delete and load saves for instances.
### Changes
- Removed rotation of factorio-current.log files.
## Version 2.0.0-alpha.6
### Breaking Changes
- Node.js versions below 12 are no longer supported.
## Version 2.0.0-alpha.5
### Features
- Added an overview of the installed plugins to the web interface.
- Added clusterioctl command to list plugins on the controller.
- Added Player Auth plugin for logging in to the web interface by proving the ability to log in to a server as a given user.
## Version 2.0.0-alpha.4
### Features
- Added option to configure timeout for exported Prometheus metrics.
- Added option to set address to bind HTTP(S) port to.
### Breaking Changes
- Removed automatic creation of self-signed TLS certificate.
## Version 2.0.0-alpha.3
### Major Features
- Added centralized logging for the cluster.
All logs from both Clusterio and Factorio is stored in a shared log which can be inspected and queried.
### Features
- Added stripping of long paths in the Factorio server log.
- Added option to configure maximum number of commands to send in parallel.
- Added option to auto start instances on host startup.
- Added metric mapping of host and instance ids to their names, allowing them to be displayed by name in queries that join with the mapping.
## Version 2.0.0-alpha.0
### Major Features
@@ -987,9 +1079,6 @@ Many thanks to the following for contributing code in this release:
Plugins now inherit from a base class and use the same WebSocket connection Clusterio uses to communicate.
- New configuration system with support for initializing configs when needed, modifying config entries using built-in commands, and updating instance configuration remotely.
- Packaged and uploaded to npm again, greatly simplifying distribution and installation of both Clusterio and plugins.
- Added centralized logging for the cluster.
All logs from both Clusterio and Factorio is stored in a shared log which can be inspected and queried.
- Added remote save management with the ability to list, create, rename, copy, upload, download, transfer, delete and load saves for instances.
### Features
@@ -1005,19 +1094,11 @@ Many thanks to the following for contributing code in this release:
- Added integrated user management for controlling access and storing per player data.
- Added synchronization of in-game adminlist, banlist and whitelist to Clusterio core.
Previously this was handled by the playerManager plugin.
- Added stripping of long paths in the Factorio server log.
- Added option to configure maximum number of commands to send in parallel.
- Added option to auto start instances on host startup.
- Added metric mapping of host and instance ids to their names, allowing them to be displayed by name in queries that join with the mapping.
- Added option to configure timeout for exported Prometheus metrics.
- Added option to set address to bind HTTP(S) port to.
- Added an overview of the installed plugins to the web interface.
- Added clusterioctl command to list plugins on the controller.
- Added Player Auth plugin for logging in to the web interface by proving the ability to log in to a server as a given user.
- Added Node.js based installer to simplify setting up a cluster.
### Changes
- Fixed sslCert and sslPrivKey entries being ignored in the config.
- Changed ssl key creation to be done at startup instead of on npm install.
- Added error handling during controller startup.
- Factorio game and rcon port now defaults to a random port above 49151.
- Removed unimplemented mods update command.
@@ -1048,7 +1129,6 @@ Many thanks to the following for contributing code in this release:
UPS statistics is exported by the statistics exporter plugin.
- Controller now defaults to hosting on https on port 8443.
- Renamed client to slave.
- Removed rotation of factorio-current.log files.
### Breaking Changes
@@ -1056,6 +1136,7 @@ Many thanks to the following for contributing code in this release:
Breaks playerManager.
- The masterIP and masterPort config entries has been merged into masterURL.
Breaks discordChat, playerManager, serverSelect, trainTeleports and clusterioModel.
- Instance names can no longer be invalid Windows file names.
- Removed config management from the command line and the server manager.
- Moved ejs templates into views folder and changed their extension to .ejs.
Breaks playerManager.
@@ -1111,9 +1192,6 @@ Many thanks to the following for contributing code in this release:
- Removed usage of socket.io entirely in favor of a plain WebSocket connection.
- Renamed clusterioMod plugin to subspace_storage.
- Controller no longer creates secret-api-token.txt.
- Removed automatic creation of self-signed TLS certificate.
- Node.js versions below 12 are no longer supported.
## Version 1.2.4
- Removed broken remote combinator signaling.
+17 -17
View File
@@ -4,7 +4,7 @@ You are probably reading this because you want to contribute code to Clusterio.
Great! We need people like you.
Though we have some conventions and workflows that we kindly ask you to follow.
This document covers the development workflow, commands, and repository layout.
Read our [past decisions](/docs/decisions.md) for compatibility policies and design rationale.
Read our [past decisions](/docs/devs/decisions.md) for compatibility policies and design rationale.
## Contents
@@ -51,7 +51,7 @@ Clusterio manages distributed Factorio servers through a controller, hosts, and
| `packages/host/lua/` | Factorio mod sources, including `clusterio_lib`. |
| `test/` | Root test suite, fixtures, helpers, integration harness, and manual tests. Plugin tests also live under `plugins/*/test/`. |
Start with [how it works](how-it-works.md), [communication](communication.md), and the [config system](config-system.md) for architecture.
Start with [how it works](../how-it-works.md), [communication](communication.md), and the [config system](config-system.md) for architecture.
See [writing plugins](writing-plugins.md) and [developing for Clusterio](developing-for-clusterio.md) for plugin and Factorio contracts.
@@ -223,19 +223,19 @@ It locates Factorio through `host.factorio_directory` in root `config-host.json`
The full harness currently requires a usable Factorio installation: a missing directory fails discovery, and an empty directory fails setup while selecting a version.
Some individual tests have conditional skips, but these do not make a full run without Factorio succeed.
Use the relevant production bundle, mod build, or [manual scenario](../test/manual/README.md) for changes affecting those surfaces.
Use the relevant production bundle, mod build, or [manual scenario](../../test/manual/README.md) for changes affecting those surfaces.
For documentation changes, check that links, paths, and example commands are correct.
### Cleaning generated and runtime files
Inspect `node clean.js --help` and preview the selected scope with `--dry-run` before cleaning.
Inspect `node scripts/clean.js --help` and preview the selected scope with `--dry-run` before cleaning.
| Command | Removal scope |
| --- | --- |
| `node clean.js --dry-run` | Preview workspace package/plugin build output and Vite dependency caches; omit `--dry-run` to clean, or use `pnpm clean`. |
| `node clean.js tests --dry-run` | Also preview root `.nyc_output/`, `coverage/`, the whole `temp/` directory, and `static/`. |
| `node clean.js all --dry-run` | Also preview runtime databases, instances, logs, mods, local configs, `FactorioAdminToken.txt`, and `plugin-list.json`. |
| `node scripts/clean.js --dry-run` | Preview workspace package/plugin build output and Vite dependency caches; omit `--dry-run` to clean, or use `pnpm clean`. |
| `node scripts/clean.js tests --dry-run` | Also preview root `.nyc_output/`, `coverage/`, the whole `temp/` directory, and `static/`. |
| `node scripts/clean.js all --dry-run` | Also preview runtime databases, instances, logs, mods, local configs, `FactorioAdminToken.txt`, and `plugin-list.json`. |
`all` deletes cluster runtime data, including configurations and saves; back up anything you want to keep before using it.
The cleaner excludes `external_plugins/` and does not remove mod archives in root `dist/`.
@@ -261,8 +261,8 @@ If there are no changelog entries to add, remove the code block and start the ch
The version-compat job in CI runs the local controller with the latest published host, and the published controller with the local host.
It fails if a link message changed its src, dst, data or response schema since that release.
Control is left out of src and dst, and messages that only go between control and the controller are not checked, as the web UI is served by the controller it talks to.
If the break is intended, add an entry to [scripts/version-compat-breaks.json](../scripts/version-compat-breaks.json) in the same pull request.
Breaking changes are only accepted if the next release is intended to include them, see our decision on [breaking changes](/docs/decisions.md#breaking-changes).
If the break is intended, add an entry to [scripts/version-compat-breaks.json](../../scripts/version-compat-breaks.json) in the same pull request.
Breaking changes are only accepted if the next release is intended to include them, see our decision on [breaking changes](/docs/devs/decisions.md#breaking-changes).
The entry is keyed by the published version directly before the breaking change was introduced, which is the latest release at the time.
Every entry needs the pull request number, a reason saying what breaks, and an impact saying why end users are not or only minimally affected.
@@ -332,35 +332,35 @@ GitHub has no interface or functionality for keeping the branches in your fork u
### Publishing releases to npm
For publishing new releases see [package release workflow](./release-workflow.md#packages).
For publishing new releases see [package release workflow](release-workflow.md#packages).
## Changelog
There's a [Changelog](../CHANGELOG.md) in the root of the project.
There's a [Changelog](../../CHANGELOG.md) in the root of the project.
If you make changes that are visible to users of this project you should add an entry to the changelog describing what has changed.
The format of this log should be self explanatory, please follow it carefully. Please make sure to document any [breaking changes](/docs/decisions.md#breaking-changes).
The format of this log should be self explanatory, please follow it carefully. Please make sure to document any [breaking changes](/docs/devs/decisions.md#breaking-changes).
## Supported Node.js and Factorio Versions
For development, use the latest Node.js LTS release, following the [installation instructions](../README.md#installation).
For development, use the latest Node.js LTS release, following the [installation instructions](../../README.md#installation).
Make sure the Node.js built-in APIs and npm packages you use remain compatible with the supported versions.
The GitHub Actions tests run every Factorio version on the latest Node.js, and every other supported Node.js version with the latest Factorio only, which keeps the number of jobs within GitHub's concurrent job limit.
Coverage is collected on the oldest supported Node.js; see the [CI workflow](../.github/workflows/node.js.yml) for the version matrix.
Coverage is collected on the oldest supported Node.js; see the [CI workflow](../../.github/workflows/node.js.yml) for the version matrix.
For Factorio, active support covers the latest stable version and the previous major version, using version lines such as 2.1, 2.0 and 1.1 as described in the [Factorio support policy](decisions.md#factorio).
Older versions from 0.17 onwards receive passive support where it does not restrict actively supported versions.
Check the Lua API documentation for the Factorio versions your changes target and preserve compatibility with the actively supported versions.
The GitHub Actions tests use pinned Factorio releases; see the [CI workflow](../.github/workflows/node.js.yml) for the current version matrix.
The GitHub Actions tests use pinned Factorio releases; see the [CI workflow](../../.github/workflows/node.js.yml) for the current version matrix.
Check out all our of decisions for [node, factorio, and operation support](/docs/decisions.md#supportability).
Check out all our of decisions for [node, factorio, and operation support](/docs/devs/decisions.md#supportability).
## Code Style
The style of the code is a bit of a mixed bag at the moment.
But there are at least a few things that have been agreed upon.
See our [decisions document](/docs/decisions.md) for justifcations.
See our [decisions document](/docs/devs/decisions.md) for justifcations.
### Naming style
+10 -24
View File
@@ -20,7 +20,7 @@ Plugin authors should also follow the [2.0 migration guide](docs/devs/plugin-mig
### Ways to support me/the project:
* Contribute with code/documentation.
See [Contributing](docs/contributing.md) for how to make pull requests.
See [Contributing](contributing.md) for how to make pull requests.
Always nice to move the project forward.
* Support me monetarily on [patreon](https://www.patreon.com/danielv123) or paypal: danielv@live.no
@@ -93,7 +93,7 @@ The installer offers the six plugins maintained in this repository.
Community plugins are versioned and released independently of Clusterio; check their compatibility before installing them manually.
Want to make your own plugin?
Check out the documentation on [Writing Plugins](/docs/writing-plugins.md) for where to start.
Check out the documentation on [Writing Plugins](/docs/devs/writing-plugins.md) for where to start.
If you have a plugin written for an earlier 2.0 alpha, see [Migrating Plugins to 2.0](/docs/devs/plugin-migration-to-2.0.md).
Note that from 2.0 onwards minor versions of Clusterio may contain breaking changes for plugins, while breaking changes for users running a cluster are held back for major versions.
@@ -107,7 +107,7 @@ If you already have a supported Node.js version installed, you can set it up in
npm init "@clusterio"
Otherwise see below for OS specific instructions.
Check out all our of decisions for [node, factorio, and operation support](/docs/decisions.md#supportability).
Check out all our of decisions for [node, factorio, and operation support](/docs/devs/decisions.md#supportability).
### Ubuntu setup
@@ -223,21 +223,9 @@ See the [readme for @clusterio/controller](/packages/controller/README.md) for m
## Managing Factorio mods
Mods in Clusterio are managed as parts of mod packs.
On the Mods page of the web interface, use **Search** to browse the Factorio Mod Portal and download mods to the controller, or upload mod zip files directly.
Mod Portal downloads require the controller's [Factorio account credentials](docs/configuration.md#controllerfactorio_username) to be configured.
Use **Create** in the Mod Packs section to create a mod pack, then add the mods you want to use.
Assign the mod pack to an instance under Instance config -> Factorio -> Mod pack, or set a default mod pack for new instances in the controller settings.
![Select mod pack for instance](docs/assets/config_select_mod_pack.png)
Mod settings can be managed under the modpack configuration page in the web UI. For mod settings to show, you first need to run an export. This is done by creating an instance with the modpack assigned, opening the instance page and pressing More -> Export data.
![Export mod configuration data](docs/assets/export_mod_config_data.png)
Once this is done, the mod settings will show up under the modpack configuration page.
![Mod settings configuration in web interface](docs/assets/mod_settings_configuration.png)
Mods in Clusterio are managed as parts of mod packs, which are set up on the Mods page of the web interface and assigned to instances.
See [Mod Packs](docs/managing-a-cluster.md#mod-packs) in the Managing a Cluster guide.
To see item icons and names and to edit mod settings in the web interface, data has to be exported from Factorio first, see [Exporting data](docs/managing-a-cluster.md#exporting-data).
## Setting up shared storage
@@ -258,6 +246,7 @@ Once the controller process is running you can log into the web interface which
The first time a host starts it prints a link for approving it, open the link and click Approve.
The basics of setting up a Factorio server from the web interface is to create an instance, assign it to a host and then click start. You can also use the "Connect via Steam" button to launch Factorio directly and connect to the server using Steam's protocol handler.
See [Managing a Cluster](docs/managing-a-cluster.md) for a guide to the day to day tasks, like managing saves and mod packs and giving other users access.
### Running via Systemd
@@ -298,12 +287,9 @@ To add the computer back to the cluster start the host again, it asks for approv
## Setting up clusterioctl
There's a command line interface available for Clusterio which is installed separately with the same installer as for the controller and host.
Run the installer as described in the installation section and choose "Ctl only" as the operating mode to install, you can do this in the same directory as you have installed other Clusterio component(s) to.
The installer will ask for a controller URL and an authentication token, these are the same as you would use to connect to the web interface.
If you want to use a different user for the command line interface, you can generate an authentication token for an existing user with
npx clusteriocontroller bootstrap generate-user-token <username>
There's a command line interface available for Clusterio called clusterioctl.
It is installed separately with the same installer as for the controller and host, by choosing "Ctl only" as the operating mode, you can do this in the same directory as you have installed other Clusterio component(s) to.
See [Clusterioctl](docs/clusterioctl.md#setting-up) for how to set it up and the commands it has.
## Known Issues
+858
View File
@@ -0,0 +1,858 @@
# Clusterioctl
Clusterio clusters can be managed from the command line with `clusterioctl`, which is invoked by running `npx clusterioctl <command>` in the directory it was installed in.
It connects to the controller the same way the web interface does, and what it is allowed to do depends on the roles of the user it logs in as.
See [Managing a Cluster](managing-a-cluster.md) for a guide to the day to day tasks.
This document uses the shorthand `ctl> foo` to indicate `npx clusterioctl foo` should be executed.
Mandatory parameters are shown in `<angles bracket>` and optional pameters are in `[square brackets]`.
Hosts, instances, roles and mod packs can be given by name or by ID.
Run `npx clusterioctl --help` for the list of commands and `npx clusterioctl <command> --help` for the options of a command.
Plugins may add their own commands, these are documented in the plugin's README.
## Setting up
clusterioctl is installed separately from the controller and host.
It only needs to reach the controller over the network, so it can be installed on any computer, in any directory, including next to a controller or host.
Run the installer as described in the [README](/README.md#installation) in the directory you want it in and choose "Ctl only" as the operating mode.
The installer asks for the controller URL and an authentication token, these are the same as you would use to log in to the web interface, and saves them to `config-ctl.json`.
When clusterioctl is installed in the same directory as the controller, `npx clusteriocontroller bootstrap create-ctl-config <username>` writes `config-ctl.json` for managing the cluster as the given user.
The config created this way connects to `localhost`, so it only works on the controller computer.
The web interface can also make this file, click your user name in the top right of the page and pick Ctl Config.
This downloads a `config-ctl.json` for your account that connects to the same address as the web interface, place it in the directory clusterioctl is installed in.
To set it up by hand, generate a token for the user on the controller:
npx clusteriocontroller bootstrap generate-user-token <username>
Then create the config and set the URL and token on the computer you run clusterioctl on:
npx clusterioctl config create
npx clusterioctl config set ctl.controller_url https://example.com/
npx clusterioctl config set ctl.controller_token <token>
The `config` command works offline and is described in the [readme for @clusterio/ctl](/packages/ctl/README.md), along with the other command line options.
See [Ctl Configuration](configuration.md#ctl-configuration) for the available settings.
The token logs in as the user it was generated for and gives the same access as that user's roles.
Anyone holding it can manage the cluster as that user, so keep `config-ctl.json` private.
A token stops working when it is revoked with [`user revoke-token`](#revoke-user-token).
If the controller uses a self-signed certificate, Node.js has to be told to trust it before clusterioctl can connect, see [Setting up TLS](setting-up-tls.md#creating-and-using-a-self-signed-certificate).
For example on Linux:
NODE_EXTRA_CA_CERTS=path/to/cert.pem npx clusterioctl instance list
## Output Format
ctl> --output json <command>
Print the result of the command as JSON on stdout instead of text meant for reading.
Lists are printed as an array of objects, other results as an object, and commands that have no result print `{"success": true}`.
If the command fails it prints `{"error": "<ClassName>", "message": "<message>"}` and exits with a non-zero exit code.
Log messages are written to stderr in all formats.
`--output wire` prints the same results in the format they are sent between the controller, hosts and clusterioctl, which uses snake_case names like `is_admin`.
The `json` format uses the property names shown in the tables of the human format.
`log follow` and `debug dump-ws` keep running and print one JSON object per line as entries arrive.
`instance start-all` and `instance stop-all` print an array with an entry per instance, which has an `error` property if that instance failed to start or stop.
The default is `--output human`, which prints `Command ran successfully` for commands that have no result.
## Controller
### Stop controller
ctl> controller stop
Stops the controller.
The run scripts and systemd services created by the installer do not start it again.
### Restart controller
ctl> controller restart
Restarts the controller.
This only works if the controller was started with `run --can-restart`, which the run scripts and systemd services created by the installer do, otherwise the request is refused.
It is also refused while a plugin install or update is running.
### Controller config
The controller config can be changed while the controller runs, unlike `npx clusteriocontroller config set` which must only be used while it is stopped.
See [Controller Configuration](configuration.md#controller-configuration) for the available fields.
#### List controller config
ctl> controller config list
Lists the config of the controller.
#### Set controller config value
ctl> controller config set <field> [value] [--stdin]
Sets a field in the controller config.
If `value` is left out the field is cleared, `--stdin` reads the value from stdin instead.
Some fields, like `controller.allow_remote_updates`, can not be changed remotely and have to be set on the controller computer while it is stopped.
#### Set controller config property
ctl> controller config set-prop <field> <prop> [value] [--stdin]
Sets one property of an object field in the controller config, see [Set config property of field](#set-config-property-of-field).
#### Edit controller config
ctl> controller config edit [editor]
Opens the controller config in a text editor and applies the changed values once the editor exits.
If `editor` is not given the `EDITOR` or `VISUAL` environment variable is used.
## Hosts
### List hosts
ctl> host list
Lists all hosts.
Hosts are added to the cluster by running the installer on the computer the host runs on and approving the code it shows, see [Setting up remote hosts](/README.md#setting-up-remote-hosts).
Listing, approving and rejecting hosts waiting for approval needs the `core.host.approve` permission.
### List pending hosts
ctl> host pending
Lists hosts waiting for approval with the code they show, the name they asked for, the address they connected from and how long they have been waiting.
A request goes away when its host stops waiting, and after the time set by `controller.host_pairing_timeout`, an hour by default, after which the host asks again with a new code.
### Approve host
ctl> host approve <code> [--name <host name>]
Approves the host showing the code and prints the id of the new host.
The code is not case sensitive and the dash can be left out.
`--name` gives the host a different name than the one it asked for.
Approving gives the host full access to the cluster, check with `host pending` that the name and address match the computer you are setting up.
### Reject host
ctl> host reject <code>
Rejects the host showing the code, the host then exits with an error.
### Revoke host
ctl> host revoke <host>
Specify the host by name or ID.
Removes the host from the cluster, disconnects it and makes its token stop working.
Instances assigned to the host become unassigned, their files stay on the computer.
Requires the `core.host.revoke` permission.
To add the computer back to the cluster, start the host again and approve it.
### Stop host
ctl> host stop <host>
Stops the host and the instances running on it.
The run scripts and systemd services created by the installer do not start it again, it has to be started on the computer it runs on.
### Restart host
ctl> host restart <host>
Restarts the host.
Like the controller, this only works if the host was started with `run --can-restart`.
### Host config
The config of a connected host can be changed from clusterioctl.
See [Host Configuration](configuration.md#host-configuration) for the available fields.
#### List host config
ctl> host config list <host>
Lists the config of the host given by name or ID.
#### Set host config value
ctl> host config set <host> <field> [value] [--stdin]
Sets a field in the host config.
If `value` is left out the field is cleared, `--stdin` reads the value from stdin instead.
Some fields, like `host.allow_remote_updates`, can not be changed remotely and have to be set on the host computer while it is stopped.
#### Set host config property
ctl> host config set-prop <host> <field> <prop> [value] [--stdin]
Sets one property of an object field in the host config, see [Set config property of field](#set-config-property-of-field).
#### Edit host config
ctl> host config edit <host> [editor]
Opens the host config in a text editor and applies the changed values once the editor exits.
If `editor` is not given the `EDITOR` or `VISUAL` environment variable is used.
### Update Clusterio
ctl> host update <host> [--all] [--restart]
Specify the host by name or ID.
If remote updates are enabled on the host, this will attempt to update `@clusterio/host` on the machine. Add `--all` to also update all npm-installed plugins. Changes will not be applied until the host is restarted. If the `--restart` flag is provided, the host will automatically restart once the update is complete.
Remote updates are enabled by default but can be disabled on a per-machine basis at the owner's discretion. For security reasons, this configuration setting cannot be changed remotely. To modify it, run the following command locally while the host is offline:
host> config set host.allow_remote_updates true/false
The controller also supports remote updates, following the same logic. The corresponding commands are:
ctl> controller update [--all] [--restart]
controller> config set controller.allow_remote_updates true/false
### Mark restart required
ctl> host mark-restart-required <host>
Marks the host as requiring a restart, the same way a plugin update does. Use it after installing or changing a plugin by other means than `host plugin install`, such as a plugin checked out into `external_plugins`. The mark shows up in the web interface on the next system metrics poll. The controller has the same command:
ctl> controller mark-restart-required
## Instances
### List Instances
ctl> instance list [--templates]
List instances.
Templates are only listed if `--templates` is passed.
### Create instance
ctl> instance create <name> [--id <instance id>] [--from <instance id>] [--template <instance>] [--as-template]
Create a new instance. `name` is the instance name. `--id` is the optional id. `--from` copies the config of an existing instance. `--template` makes the new instance inherit all config values from the given template. `--as-template` creates the instance as a template, see `instance.is_template` in the [configuration docs](configuration.md). Use `--as-template --from <instance>` to make a template out of an existing instance.
### Delete instance
ctl> instance delete <instance>
Deletes the instance and all its files, including saves, from the host it is assigned to.
The instance must be stopped, and can not be deleted while it is the template of other instances.
### Start instance
ctl> instance start <instance> [--save <name>] [--keep-open]
Starts the instance, which must be assigned to a host.
Loads the given save, or the most recently modified save if `--save` is not passed.
`--keep-open` keeps clusterioctl running and prints the log of the instance until it is stopped with Ctrl+C.
### Restart instance
ctl> instance restart <instance> [--save <name>] [--keep-open]
Stops the instance if it is running and starts it again, takes the same options as `start`.
### Load scenario
ctl> instance load-scenario <instance> <scenario> [--seed <seed>] [--map-exchange-string <string>] [--map-gen-settings <file>] [--map-settings <file>] [--keep-open]
Starts the instance with a new game from the given scenario, for example `base/freeplay`.
This only works with save patching turned off for the instance with `factorio.enable_save_patching`, see [Save Patching](how-it-works.md#save-patching).
`--map-exchange-string` sets the map generation from a map exchange string copied from Factorio.
`--map-gen-settings` and `--map-settings` take paths to the JSON files Factorio uses for these, and `--seed` overrides the seed in them.
### Stop instance
ctl> instance stop <instance>
Saves the game and stops the instance.
### Start all instances
ctl> instance start-all [--force]
Starts every stopped instance that is assigned to a host.
Instances with `instance.exclude_from_start_all` set are skipped unless `--force` is passed.
### Stop all instances
ctl> instance stop-all
Stops every running instance.
### Send RCON command
ctl> instance send-rcon <instance> <command>
Sends a command to the Factorio server of a running instance and prints the reply, for example `ctl> instance send-rcon "My World" /players`.
Quote the command if it contains spaces.
### Export data
ctl> instance export-data <instance>
Exports the item icons, names and mod settings from Factorio for the mod pack the instance uses, and uploads them to the controller.
The instance must be stopped.
The web interface needs this data to show icons and names of items, and to show the settings of the mods in a mod pack.
See [Exporting data](managing-a-cluster.md#exporting-data) for when to run it.
### Kill instance
ctl> instance kill <name>
Terminates the running Factorio server without giving it a chance to save or cleanup after itself.
Note: This may cause loss of data.
### Save game
ctl> instance save-game <name>
Saves the running game of the instance to the save it was started from and waits for the save to finish.
### Extract players from instance
ctl> instance extract-players <name>
Creates a user account in the cluster for each player that has been online on the currently running save of the instance and sets the online time of that account on this instance to the online time recorded in the save.
Useful when importing a save to a cluster.
Note that the online time in a save is recorded differntly from how Clusterio records online time.
Most notably Clusterio records wall clock time while the save time is recorded in ticks and this extraction of player time assumes the game runs at 60 ticks a second.
### Config management
#### List Configuration
ctl> instance config list <instance>
List config values for an instance. `instance` is the instance whose config values to list. Values inherited from a template are marked with `(inherited)`, object fields also list the properties set on the instance.
#### Set config value
ctl> instance config set <instance> <field> [value] [--stdin]
Set field in instance config. `instance` is instance to set. `field` is field to set. `value` is value to set in field. `--stdin` signals to read value from stdin.
#### Set config property of field
ctl> instance config set-prop <instance> <field> <prop> [value] [--stdin]
Set one property of an object field, like `factorio.settings`, without replacing the rest of the object.
`value` is parsed as JSON if it can be, otherwise it is used as a string.
If `value` is left out the property is removed.
For example, to set the max player count and remove the game password:
ctl> instance config set-prop "My World" factorio.settings max_players 16
ctl> instance config set-prop "My World" factorio.settings game_password
#### Inherit config value
ctl> instance config inherit <instance> <field> [prop]
Make a field in the instance config take its value from the template again, undoing a previous `set`. `instance` is the instance to update, `field` is the field to inherit, `prop` limits it to one property of an object field.
#### Edit instance config
ctl> instance config edit <instance> [editor]
Edit instance config in a text editor. Once file is saved and editor has been exited, changed config values will be read back in. `instance` is the instance to edit, `editor` is the editor to use. If `editor` is not given, clusterioctl will read from the `EDITOR` or `VISUAL` enviroment variables.
### Assign instance to host
ctl> instance assign <instance> [host]
Assigns instance to host. `instance` is instance to assign, `host` is host to assign to. If `host` is not provided, instance will be unassigned.
### Saves
Saves are stored on the host the instance is assigned to.
The commands below need the instance to be assigned, and the host to be connected.
#### List saves
ctl> instance save list <instance>
Lists the saves of the instance.
`loadByDefault` marks the save that is loaded when the instance is started without `--save`.
#### Create save
ctl> instance save create <instance> [name] [--seed <seed>] [--map-exchange-string <string>] [--map-gen-settings <file>] [--map-settings <file>]
Creates a new save with a freshly generated map without starting the server.
The name defaults to `world.zip`.
The map options work the same as for [load-scenario](#load-scenario).
#### Upload save
ctl> instance save upload <instance> <file> [--name <name>]
Uploads a save from this computer to the instance.
`--name` gives it a different name on the host, the name must end with `.zip`.
If a save with the same name exists the upload is stored under a new name.
#### Download save
ctl> instance save download <instance> <save>
Downloads a save from the instance to the current directory.
#### Rename save
ctl> instance save rename <instance> <old-name> <new-name>
#### Copy save
ctl> instance save copy <instance> <source> <destination>
Copies a save within the same instance.
#### Transfer save
ctl> instance save transfer <source-instance> <source-save> <target-instance> [target-save] [--copy]
Moves a save to another instance, which can be on a different host.
`--copy` leaves the original in place.
If a save with the target name exists the transferred save is stored under a new name, which is printed.
#### Delete save
ctl> instance save delete <instance> <save>
## Users
Clusterio automatically creates user accounts for all players that join an instance.
These accounts are used to store per player data shared between instances, like if the player should be whitelisted, admin or banned.
### List users
ctl> user list [--attributes] [--stats]
Lists all user accounts in the cluster along with some data for each.
`--attributes` adds the admin, whitelisted and banned status, and `--stats` adds online time and join counts.
### Show user
ctl> user show <name> [--instance-stats]
Shows the account data of one user.
`--instance-stats` adds the online time and join count for each instance.
### Create User
ctl> user create <name>
Creates a new empty user account for the given Factorio player.
Note that case matters here.
This is usually not required as user accounts are created automatically for players that join instances.
### Promote User to Server Admin
ctl> user set-admin <name> [--revoke] [--create]
Promotes the user given to in-game admin on instances with the `sync_adminlist` option enabled.
If the `--revoke` switch is used the user is removed from the adminlist.
Since admin status is a part of the account data the account must exist for this to succeed, passing `--create` will create the account if it does not exist.
**Note:** Being a server admin does not grant any access to manage the cluster.
See [set-roles](#set-cluster-roles) for adding roles which grant access to managing the clusetr.
### Whitelist User
ctl> user set-whitelisted <name> [--remove] [--create]
Add the user given to the whitelist on instances with the `sync_whitelist` option enabled.
If the `--remove` switch is used the user is removed from the whitelist.
Since whitelisted status is a part of the account data the account must exist for this to succeed, passing `--create` will create the account if it does not exist.
### Ban User
ctl> user set-banned <name> [--reason <message>] [--pardon] [--create]
Ban user in-game from instances with the `sync_banlist` option enabled.
Reason is a message that will be shown to the user when attemption to log in.
If the `--pardon` switch is used it removes the ban.
Since ban status is a part of the account data the account must exist for this to succeed, passing `--create` will create the account if it does not exist.
Note: This bans the user from logging in to Factorio servers in the cluster, it does not revoke access to any cluster management they might have, see next section on setting roles for revoking tha.
### Bulk importing admin, whitelist and ban lists
Admin lists, whitelists and banlists can be bulk imported with the following command:
ctl> user import <file> [--admins|--whitelist|--bans|--users]
The admin list and whitelist files should be a JSON array of names, the same format as Factorio's server-adminlist.json and server-whitelist.json:
["joe", "bob", "allan"]
The banlist file uses the format of Factorio's server-banlist.json, where each entry is either a name or an object with a username and reason:
[
"joe",
{"username": "bob", "reason": "stole materials"},
{"username": "allan", "reason": "rude language"}
]
The `--users` option imports a file written by `user export`, which holds the admin, whitelist and ban status of every user.
If no option is given the type is guessed from the file, files with an `export_version` field are treated as user exports, otherwise the file name must contain ban, admin or whitelist.
Users that do not exist are created.
Importing only adds to the existing lists, it never removes anyone from them.
To replace a list instead, use restore:
ctl> user restore <file> [--admins|--whitelist|--bans|--users] [--no-backup]
This takes the same files as import, but removes everyone not in the file from the list.
The previous list is written to `<type>-backup.json` in the current directory unless `--no-backup` is passed.
The current lists can be exported with the following command:
ctl> user export <file> [--admins|--whitelist|--bans|--users]
Defaults to exporting users.
### Set Cluster Roles
ctl> user set-roles <name> [roles...]
Replaces the roles the user has in the cluster with a new list of roles.
Calling with an empty roles argument will remove all roles from the user.
By default there's a roled named Cluster Admin which grants access to everything and a role named Player which grants a limited read access to the cluster, see [the section on roles](#roles) for more information about setting up roles and permissions.
### Revoke user token
ctl> user revoke-token <name>
Makes every authentication token issued to the user stop working, including the one used by the web interface and clusterioctl.
The user has to log in again, or be given a new token with `npx clusteriocontroller bootstrap generate-user-token <name>`.
Revoking the token of another user needs the `core.user.revoke_other_token` permission.
### Delete user
ctl> user delete <name>
Deletes everything stored on the controller for this user.
Note: If the player is banned from the cluster this will effectively unban them, as the ban status is stored with the user account.
Note: If the player joins the cluster again a new account will be made for them automatically.
## Roles
Access to manage the cluster is granted through roles.
A role is a named set of permissions, and a user has the permissions of all the roles they have.
By default there are two roles: Cluster Admin, which has the `core.admin` permission that grants everything, and Player, which can view most of the cluster but not change it.
New users get the Player role, this is set by `controller.default_role_id`.
Use [`user set-roles`](#set-cluster-roles) to give roles to a user.
### List roles
ctl> role list
Lists the roles with their ID, description and permissions.
### Create role
ctl> role create <name> [--description <text>] [--permissions <permission>]...
Creates a new role and prints its ID.
Pass `--permissions` once for each permission the role should grant, for example:
ctl> role create "Instance Operator" --permissions core.instance.start --permissions core.instance.stop
### Edit role
ctl> role edit <role> [--name <name>] [--description <text>] [--set-perms <permission...>] [--add-perms <permission...>] [--remove-perms <permission...>] [--grant-default]
Changes the name, description or permissions of a role.
`--set-perms` replaces the permissions of the role, `--add-perms` and `--remove-perms` change them, and these take several permissions separated by spaces.
`--grant-default` adds the permissions shown as granted by default in [`permission list`](#list-permissions), which are the ones the Player role starts with.
### Delete role
ctl> role delete <role>
Deletes the role, users that had it lose the permissions it granted.
## Permissions
### List permissions
ctl> permission list
Lists all permissions with their name, title, description and whether they are granted by default.
Plugins can add their own permissions, these show up here when the plugin is loaded on the controller.
## Mods
Mods are stored on the controller and sent to hosts when an instance needs them.
### List mods
ctl> mod list [--fields <field...>]
Lists the mods stored on the controller.
`--fields` picks the columns to show, `--fields all` shows every field.
### Search mods
ctl> mod search <factorio-version> [query] [--page <n>] [--page-size <n>] [--sort <field>] [--sort-order asc|desc] [--fields <field...>]
Searches the mods stored on the controller that work with the given major version of Factorio, for example `2.0`.
This does not search the Factorio Mod Portal, use the Mods page of the web interface for that.
### Show mod
ctl> mod show <name> <version>
Shows the details of a stored mod.
### Upload mod
ctl> mod upload <file>
Uploads a mod zip file to the controller.
### Download mod
ctl> mod download <name> <version>
Downloads a stored mod to the current directory.
### Delete mod
ctl> mod delete <name> <version>
Deletes a stored mod from the controller.
## Mod Packs
A mod pack is a list of mods with their versions and mod settings, see [Mod packs](managing-a-cluster.md#mod-packs).
### List mod packs
ctl> mod-pack list
### Show mod pack
ctl> mod-pack show <mod-pack>
Shows the mods and settings of a mod pack.
### Create mod pack
ctl> mod-pack create <name> <factorio-version> [--description <text>] [--mods <name:version...>] [--disabled-mods <name...>] [--bool-setting <scope> <name> <value>] ...
Creates a mod pack for the given version of Factorio and prints its ID.
The built in mods of Factorio, like `base` and `space-age`, are added automatically with only `base` enabled.
Mods are given as `name:version`, and optionally `name:version:sha1`.
`--disabled-mods` takes the names of mods from `--mods` that should be in the pack but not enabled.
Mod settings are set with `--bool-setting`, `--int-setting`, `--double-setting`, `--string-setting` and `--color-setting`, which each take a scope, a setting name and a value.
The scope is one of `startup`, `runtime-global` or `runtime-per-user`, and a color is given as JSON like `{"r":1,"g":0,"b":0,"a":1}`.
### Edit mod pack
ctl> mod-pack edit <mod-pack> [--name <name>] [--description <text>] [--factorio-version <version>] [--add-mods <name:version...>] [--enable-mods <name...>] [--disable-mods <name...>] [--remove-mods <name...>] [--<type>-setting <scope> <name> <value>] [--remove-setting <scope> <name>]
Changes a mod pack, the options work the same as for `create`.
`--add-mods` also replaces the version of a mod already in the pack.
Mods are not checked against the mods stored on the controller, make sure the mods you add have been uploaded.
### Export and import mod packs
ctl> mod-pack export <mod-pack>
ctl> mod-pack import <string>
`export` prints the mod pack as a string, and `import` creates a new mod pack from such a string.
This is the same string as the Import string button and the Export to string action in the web interface use.
### Delete mod pack
ctl> mod-pack delete <mod-pack>
## Notes
Free text notes can be attached to hosts, instances, users, roles, mod packs, mods and saves.
They are stored on the controller and shown to everyone with access to the resource in the web interface, and can for example be used to record who runs a host or what an instance is meant for.
The web interface renders notes as Markdown.
A mention of the form `@<type>/<id>` becomes a link to that resource showing its name, for example `@instance/778528005` or `@user/cooldude2606`.
This works for hosts, instances, users, roles and mod packs, and the id is shown if the name is not available.
The note itself stores the mention as written.
### List notes
ctl> note list [--type <type>]
Lists all notes, optionally limited to one resource type.
### Set note
ctl> note set <type> <id> <content>
Sets the note of a resource.
The type is one of host, instance, user, role, mod_pack, mod or save.
The id is the numeric id for hosts, instances, roles and mod packs, the lower case name for users, `<name>_<version>` for mods and `<instance id>/<file name>` for saves.
### Delete note
ctl> note delete <type> <id>
Removes the note of a resource.
Notes are also removed when the resource they are attached to is deleted.
## Logs
### Query log
ctl> log query [--all] [--controller] [--host <host>] [--instance <instance>] [--max-level <level>] [--limit <n>] [--start]
Prints entries from the cluster log stored on the controller.
At least one of `--all`, `--controller`, `--host` and `--instance` must be passed to pick which logs to read.
`--max-level` leaves out entries less important than the given level, for example `warn`.
Prints the last 1000 entries by default, `--limit` changes the number and `--start` takes them from the start of the log instead.
### Follow log
ctl> log follow [--all] [--controller] [--host <host>] [--instance <instance>]
Prints new log entries as they come in until stopped with Ctrl+C.
Takes the same options for picking logs as `query`.
## Plugins (Local)
The plugins loaded by clusterioctl are managed with the `plugin` command, which works without a connection to the controller.
See the [readme for @clusterio/ctl](/packages/ctl/README.md#plugin-command).
## Plugins (Remote)
The installer asks "Allow remote updates and plugin installs from the web interface?" and the answer sets `allow_remote_updates`, `allow_plugin_updates` and `allow_plugin_install` together on that machine, pass `--remote-npm` or `--no-remote-npm` to answer it from the command line.
Remote updates allow ctl and the web UI to update Clusterio and plugins on machines within the cluster.
Remote installs allow them to install any package from npm onto the machine, which is a risk of arbitrary code execution through malicious npm packages, so only allow them if you trust everyone with access to install plugins.
In a config created without the installer remote updates are enabled and remote installs are disabled by default.
See below for changing these settings after installing.
### List
ctl> controller plugin list
ctl> host plugin list <host>
This command lists all plugins currently known to the remote. Newly installed plugins will not be displayed until the remote is restarted. Plugins that are distributed as an npm package can be updated remotely.
### Update
ctl> controller plugin update <name>[@<version>] [--restart]
ctl> host plugin update <host> <name>[@<version>] [--restart]
If remote plugin updates are enabled on the remote, this will execute `npm update --save <name>`, which stays within the version range saved in the remote's `package.json`.
To update to a specific version, including one outside that range, pass it as `<name>@<version>`, for example `@clusterio/plugin-example@2.1.0`.
The version must be published on npm, and the remote then executes `npm install --save <name>@<version>`.
The plugin must already be installed on the remote, and only remote plugin updates need to be enabled.
Changes will not be applied until the remote is restarted.
If the `--restart` flag is provided, the remote will automatically restart once the update is complete.
### Update All
ctl> controller update --all [--restart]
ctl> host update <host> --all [--restart]
Updates the Clusterio package and all plugins installed from npm in a single `npm update --save` command. Updating everything at once avoids ending up with multiple versions of `@clusterio/lib` in the installation. Requires both remote updates and remote plugin updates to be enabled on the remote.
### Install
ctl> controller plugin install <name>[@<version>] [--restart]
ctl> host plugin install <host> <name>[@<version>] [--restart]
If remote plugin installs are enabled on the remote, this will execute `npm install --save <name>`.
Pass `<name>@<version>` to install a specific version, for example to match the version used by the rest of the cluster.
The package, and the version if given, must be published on npm.
Changes will not be applied until the remote is restarted.
If the `--restart` flag is provided, the remote will automatically restart once the update is complete.
### Search
ctl> controller plugin search [query] [--page <n>] [--page-size <n>]
Searches the npm registry for packages tagged with the clusterio-plugin keyword.
The search is done by the controller and does not require remote installs to be enabled.
The web UI has a plugin browser on the plugins page that uses the same search.
### Concurrent Operations
Only one npm operation runs at a time on a machine.
A standalone controller and host share their working directory, so the operation holds the `npm-operation.lock` file there while npm runs.
Other installs and updates on the same machine or installation are rejected with "Another package operation is already in progress on this machine" until it finishes.
A lock file left behind by a process that is no longer running is removed automatically.
### Enable/Disable Updates
host> config set host.allow_plugin_updates true/false
controller> config set controller.allow_plugin_updates true/false
Remote updates are enabled by default but can be disabled on a per-machine basis at the owner's discretion. For security reasons, this configuration setting cannot be changed remotely. To modify it, run the above commands locally while the remote is offline.
### Enable/Disable Installs
host> config set host.allow_plugin_install true/false
controller> config set controller.allow_plugin_install true/false
Remote installs are disabled by default but can be enabled on a per-machine basis at the owner's discretion. For security reasons, this configuration setting cannot be changed remotely. To modify it, run the above commands locally while the remote is offline.
## Prometheus Metrics
The controller exports metrics for the whole cluster on the `/metrics` endpoint.
Fetching it requires a token for a user with the `core.controller.metrics` permission, sent either as an `Authorization: Bearer <token>` header or as an `X-Access-Token` header.
Requests without a valid token get a 401 response and requests for users lacking the permission get a 403 response.
Create a role with just this permission, a user to hold it, and generate a token for that user.
Give the user a name that is not a valid Factorio player name, such as one starting with `#`, so a player joining the cluster can never claim the account and its token:
ctl> role create Prometheus --permissions core.controller.metrics
ctl> user create #prometheus
ctl> user set-roles #prometheus Prometheus
$ npx clusteriocontroller bootstrap generate-user-token '#prometheus'
Then pass the token in the scrape job for the controller in `prometheus.yml`:
scrape_configs:
- job_name: clusterio
authorization:
credentials: <token>
static_configs:
- targets: ["localhost:8080"]
Concurrent scrapes share a single round of metrics gathering from the hosts, so multiple scrapers polling the controller do not multiply the load on the hosts.
+35 -7
View File
@@ -1,7 +1,7 @@
# Configuration
Config values are changed with the `config set` commands of clusterioctl, clusteriocontroller and clusteriohost, or from the settings pages in the web interface.
See [Managing a Cluster](/docs/managing-a-cluster.md) for the commands.
See [Clusterioctl](/docs/clusterioctl.md) for the commands.
All values are checked against the type of the field when set.
Some fields have additional rules on top of that, such as a number having to be greater than 0, and these are listed under the field.
@@ -126,6 +126,14 @@ This should be a full URL ending with a /.
Defaults to null meaning assume localhost.
### controller.favicon_url
URL of the icon shown in the browser tab.
A relative URL is relative to the web interface root, so `static/icon.png` loads `icon.png` from the `static` folder in the controller's working directory.
Defaults to null meaning use the Clusterio logo.
### controller.static_url
Used to override where static assets such as the web bundle is loaded from.
@@ -241,17 +249,20 @@ Must be greater than 0.
Defaults to 15.
### controller.transfer_min_progress
### controller.transfer_min_speed
Amount in KiB a request to the controller has to move every 30 seconds, requests moving less are closed.
Speed in KiB/s at which a request to the controller is never closed for moving too slowly.
This closes uploads and downloads that have stalled or are sent too slowly to ever finish, while there is no limit on how long a transfer making progress can take.
It applies to saves, mods and exports uploaded to the controller, proxy streams through it, and the body of any other request.
Time spent waiting for a proxy stream to start is not counted, see controller.proxy_stream_timeout.
Data is passed on in chunks of up to 64 KiB and progress is counted per chunk, so a proxy stream moving less than about that in 30 seconds may also be closed.
Requests are checked every 60 seconds and must have moved this speed times 60 seconds, less 2 MiB, since the last check.
The 2 MiB covers the OS sending data in bursts, it can buffer a couple of MiB per connection and only accept more once a large part of that has gone out.
So at the default a request moving slower than about 30 KiB/s is closed, and one moving between that and 64 KiB/s may be.
Set below about 34 KiB/s, only requests that moved nothing in 60 seconds are closed.
Set to 0 for no limit.
Must be 0 or greater.
Defaults to 30.
Defaults to 64.
### controller.factorio_username
@@ -319,7 +330,7 @@ Defaults to 1000.
Whether the `controller update` command in clusterioctl and the update button in the web interface are allowed to update the `@clusterio/controller` package with npm.
For security reasons this can only be changed locally with `clusteriocontroller config set` while the controller is stopped, and it is hidden in the web interface.
The installer sets this, controller.allow_plugin_updates and controller.allow_plugin_install from one question about remote updates and plugin installs.
See [Managing a Cluster](/docs/managing-a-cluster.md) for details on remote updates.
See [Plugins (Remote)](/docs/clusterioctl.md#plugins-remote) for details on remote updates.
Defaults to true.
@@ -474,7 +485,7 @@ Defaults to 30.
Whether the `host update` command in clusterioctl and the update button in the web interface are allowed to update the `@clusterio/host` package with npm.
For security reasons this can only be changed locally with `clusteriohost config set` while the host is stopped, and it is hidden in the web interface.
The installer sets this, host.allow_plugin_updates and host.allow_plugin_install from one question about remote updates and plugin installs.
See [Managing a Cluster](/docs/managing-a-cluster.md) for details on remote updates.
See [Plugins (Remote)](/docs/clusterioctl.md#plugins-remote) for details on remote updates.
Defaults to true.
@@ -546,6 +557,23 @@ Does not affect start or stop of the instance while the host is running.
Defaults to false.
### instance.restart_after_crash
If enabled the host starts this instance again when the Factorio server exits unexpectedly after running for at least 10 minutes.
A crash sooner than that is logged as an error and the instance is left stopped, as it is likely to crash again.
Defaults to false.
### instance.crash_retry_attempts
Number of times the host restarts this instance after a crash before giving up and logging an error.
The count resets when a user starts or restarts the instance, or the host is restarted.
Set to 0 for no limit.
Defaults to 3.
### instance.exclude_from_start_all
If enabled this instance will be excluded from the "Start all" button operation in the web interface.
@@ -2,12 +2,12 @@
Clusterio uses links, connectors, and message classes to communicate between controllers, hosts, instances, and control clients.
A link sends and receives messages through a connector, while message classes define the requests and events that can be exchanged.
See the [system overview](how-it-works.md#system-overview) for a diagram of the processes and their connections, and the [protocol reference](devs/protocol.md) for wire formats and session flow.
See the [system overview](../how-it-works.md#system-overview) for a diagram of the processes and their connections, and the [protocol reference](protocol.md) for wire formats and session flow.
## Links and routing
[Link](../packages/lib/src/link/link.ts) handles request/response matching, event dispatch, message registration, and routing through an attached router.
[Link](../../packages/lib/src/link/link.ts) handles request/response matching, event dispatch, message registration, and routing through an attached router.
Its connector identifies the local and remote endpoints through `connector.src` and `connector.dst`, both `Address` objects.
The controller's `WsServer` stores one link for each host or control connection.
@@ -22,22 +22,22 @@ See [message permissions](writing-plugins.md#static-permission).
At the destination, the registered schema validates the payload and `fromJSON` restores the message before its handler runs.
Routing can perform work before the destination handler runs.
In particular, the [host router](../packages/host/src/Host.ts) can start or wake an instance for messages marked as instance-starting.
In particular, the [host router](../../packages/host/src/Host.ts) can start or wake an instance for messages marked as instance-starting.
## Connectors and sessions
[Connectors](../packages/lib/src/link/connectors.ts) transport messages, assign sequence numbers, and deliver incoming messages to links.
[Connectors](../../packages/lib/src/link/connectors.ts) transport messages, assign sequence numbers, and deliver incoming messages to links.
WebSocket connectors connect hosts and control clients to the controller and validate incoming message structures, including their type and addresses.
Hosts and instances share a Node.js process and communicate in memory through paired `VirtualConnector` objects.
The protocol reference describes [connection and recovery behavior](devs/protocol.md#connection-flow), [connector states and events](devs/protocol.md#connector-flow), and [graceful disconnects](devs/protocol.md#graceful-disconnect).
The protocol reference describes [connection and recovery behavior](protocol.md#connection-flow), [connector states and events](protocol.md#connector-flow), and [graceful disconnects](protocol.md#graceful-disconnect).
For handling these events in a plugin, including queueing work and preparing for disconnection, see [connection handling](writing-plugins.md#handling-connection-events).
## Message definitions and registration
Core request and event classes live under [packages/lib/src/data/](../packages/lib/src/data/).
Core request and event classes live under [packages/lib/src/data/](../../packages/lib/src/data/).
Their static `type`, `src`, and `dst` properties specify the message type and allowed endpoint types, while their schema and permission fields define the payload and access rules.
Plugin classes also supply a `plugin` name.
@@ -53,6 +53,6 @@ Use broadcast destinations only for events.
When using a request's source as a later event destination, remove its request ID with `Address.withoutRequestId()`.
See [writing plugins](writing-plugins.md#defining-link-messages) for a complete example.
When changing a wire message structure in [messages_core.ts](../packages/lib/src/data/messages_core.ts), rebuild the packages with `pnpm -r run prepare` to regenerate the standalone validator.
When changing a wire message structure in [messages_core.ts](../../packages/lib/src/data/messages_core.ts), rebuild the packages with `pnpm -r run prepare` to regenerate the standalone validator.
When changing a request or event class, keep serialization, allowed endpoints, permission checks, registration, and handlers consistent.
The [contributor guide](contributing.md#checking-your-code-for-errors) explains how to run focused tests.
The [contributor guide](../../contributing.md#checking-your-code-for-errors) explains how to run focused tests.
File renamed without changes.
+14 -2
View File
@@ -8,6 +8,7 @@ If there is a particular issue or concern you would like the team to comment on
<!-- For code style, add (Lang) to section names if present in both -->
1. Documentation
- [Audiences](#audiences)
- [Decision Log](#decision-log)
- [TSDoc](#tsdoc)
2. Code Style (General)
@@ -70,6 +71,17 @@ Remember to have one sentence per line.
## Documentation
### Audiences
🧾 21st November 2026 | [Github Issue #1254](https://github.com/clusterio/clusterio/issues/1254)
> Write each document for one audience and keep it where that audience looks: `docs/` for cluster admins and `docs/devs/` for Clusterio and plugin developers.
Admins were confused by developer documents mixed in with the guides they needed, and some topics were covered in several places that drifted apart.
The root README covers installing and starting a cluster, `docs/` covers running it, the package READMEs cover the command line options of each package, and `docs/devs/` covers developing Clusterio and plugins.
When a topic belongs to another document, link to it instead of repeating it.
### Decision Log
🧾 22nd December 2024 | Discord Voice Call
@@ -462,7 +474,7 @@ While we aim to increase the number of useful checks performed by CI in the futu
> We publish packages and mods when a maintainer publishes a stable GitHub release.
Changes merged into the main branch are bundled into releases before publication.
Publishing a stable GitHub release triggers the [Publish workflow](../.github/workflows/publish.yml), which publishes npm packages and Factorio mods.
Publishing a stable GitHub release triggers the [Publish workflow](../../.github/workflows/publish.yml), which publishes npm packages and Factorio mods.
Publishing a prerelease or pushing a tag alone does not trigger publication.
Running clusters are updated by their operators.
See the [release workflow](release-workflow.md) for the publication procedure.
@@ -484,5 +496,5 @@ However, we are always looking for a better framework which is worth the effort
> We perform all tests through GitHub actions using Ubuntu latest, using all supported versions of node and all supported versions of factorio.
The [current CI workflow](../.github/workflows/node.js.yml) tests selected Node.js major versions and pinned Factorio releases.
The [current CI workflow](../../.github/workflows/node.js.yml) tests selected Node.js major versions and pinned Factorio releases.
However, we do not conduct tests on all supported operating systems, as the added demand on our testing resources would be significant, and the value it would provide for a cross-platform engine like NodeJS would be limited.
@@ -122,7 +122,7 @@ There's also the `add_libraries` function exported by event_handler, which accep
## Communicating with Clusterio
Clusterio uses a homebrew protocol based on sending JSON payloads over a WebSocket connection.
See [protocol.md](devs/protocol.md) for the implementation details of it.
See [protocol.md](protocol.md) for the implementation details of it.
It's also possible to write a plugin for Clusterio that exposes a custom interface over HTTP, WebSocket or any other technology supported by Node.js.
@@ -193,7 +193,7 @@ In particular, player-leaving, console-command, and configuration-change handler
Use an idempotent state accessor in handlers that can run early.
It should migrate any legacy namespace before creating fresh state, fill missing fields, and return the same state on repeated calls.
A guard that returns early because the new namespace is absent can silently discard recovery work on an older save.
See [player_sync's state accessor](../plugins/player_sync/module/get_script_data.lua) for an implementation that handles a renamed namespace and [the module template](../packages/create/templates/common/module/control.lua) for lifecycle setup.
See [player_sync's state accessor](../../plugins/player_sync/module/get_script_data.lua) for an implementation that handles a renamed namespace and [the module template](../../packages/create/templates/common/module/control.lua) for lifecycle setup.
Use `on_load` only to restore local references and other operations permitted by Factorio's load lifecycle; do not create or migrate persistent state there.
Perform state changes in startup or other events that permit them.
@@ -227,7 +227,7 @@ end
Access persistent state from the appropriate lifecycle callbacks, after initialisation or loading has made it available.
The JSON helpers also work before runtime; other compatibility helpers may require `game` to be available.
Legacy examples using `global` or `game.table_to_json` directly are version-specific.
See [compat.lua](../packages/host/modules/clusterio/compat.lua) and the [Factorio support policy](decisions.md#factorio) before introducing version checks.
See [compat.lua](../../packages/host/modules/clusterio/compat.lua) and the [Factorio support policy](decisions.md#factorio) before introducing version checks.
### clusterio_api library
+4 -4
View File
@@ -10,7 +10,7 @@ Plugins still on alpha 13 should start with the [alpha 14 guide](plugin-migratio
From 2.0.0 onwards a major version (3.0.0) contains breaking changes for users running a cluster, while a minor version (2.1.0) may contain breaking changes for the plugin API.
This means a plugin written for 2.0 is not guaranteed to work with 2.1 without changes.
Check the Breaking Changes section of the changelog when a new minor version is released and publish an update to your plugin if needed.
See [Breaking Changes](/docs/decisions.md#breaking-changes) in the decision log.
See [Breaking Changes](/docs/devs/decisions.md#breaking-changes) in the decision log.
## Convert to ES modules
@@ -22,7 +22,7 @@ Keep `"clusterio-plugin"` in the package's `"keywords"` for automatic discovery,
An `"exports"` map is not required for ES modules.
If you add one, expose `"./package.json": "./package.json"`; otherwise Clusterio cannot discover or load the plugin by its package name.
Clusterio currently reads the implementation path from `"main"` rather than conditional exports.
See [Plugin Structure](../writing-plugins.md#plugin-structure) for a compatible package example.
See [Plugin Structure](writing-plugins.md#plugin-structure) for a compatible package example.
Relative imports must include the full filename with the `.js` extension.
This also applies in TypeScript, where you import `./messages.js` even though the source file is `messages.ts`.
@@ -77,7 +77,7 @@ Converting the plugin avoids the problem.
Entrypoints now export a default async function instead of a class deriving from `BaseControllerPlugin`, `BaseHostPlugin`, `BaseInstancePlugin`, `BaseCtlPlugin` or `BaseWebPlugin`.
The function is called once when the plugin loads and attaches handlers to the hooks it needs.
Class exports still load, but they are deprecated and a warning is logged for each one.
See [Defining the plugin entrypoint](/docs/writing-plugins.md#defining-the-plugin-entrypoint) for the details.
See [Defining the plugin entrypoint](/docs/devs/writing-plugins.md#defining-the-plugin-entrypoint) for the details.
**Alpha 27**
```js
@@ -289,7 +289,7 @@ declare module "@clusterio/lib" {
```
The plugin template's `tsconfig.browser.json` now includes `index.ts` so the web build also sees the declaration, add it to the `include` list if your plugin has its own tsconfig for the browser.
See [Plugin Permissions](/docs/writing-plugins.md#plugin-permissions).
See [Plugin Permissions](/docs/devs/writing-plugins.md#plugin-permissions).
## Renamed ctl classes and config
+1 -1
View File
@@ -7,7 +7,7 @@ Plugins still on an alpha should start with the [2.0 guide](plugin-migration-to-
## Request errors
`RequestError` is gone.
Errors thrown by request handlers are now received by the requester as the same class, see [Request errors](/docs/writing-plugins.md#request-errors).
Errors thrown by request handlers are now received by the requester as the same class, see [Request errors](/docs/devs/writing-plugins.md#request-errors).
Replace `RequestError` with the class that fits:
- Invalid input: `ValidationError`.
@@ -2,7 +2,7 @@
Review observable behavior across the whole PR, including callers, consumers, and lifecycle transitions.
Reading every changed file and passing tests do not establish that those behaviors were covered.
Use [contributing](contributing.md) for setup and validation commands.
Use [contributing](../../contributing.md) for setup and validation commands.
## Establish the scope
+2 -2
View File
@@ -2,7 +2,7 @@
Clusterio communicates using a simple homebrew message passing protocol based on JSON over WebSocket with limited support for reliable transport of messages.
The protocol is implemented in [packages/lib/src/link](/packages/lib/src/link) and uses the `ws` library to handle the WebSocket connections on the Node.js side and the native WebSocket API on the browser side.
The wire schemas are defined in [messages_core.ts](/packages/lib/src/data/messages_core.ts); see the [communication overview](../communication.md) for how links, connectors, and routing fit together.
The wire schemas are defined in [messages_core.ts](/packages/lib/src/data/messages_core.ts); see the [communication overview](communication.md) for how links, connectors, and routing fit together.
Two general kinds of messages are supported: events and requests.
Events are messages sent by one party and received by the other and offer no notification for the sender on whether it was actually received.
@@ -111,7 +111,7 @@ Along with the following events emitted when transition between states:
- `close` - The connector is closed, moving from any state to `closed`.
Invalidation or closure rejects pending requests with `SessionLost`.
Plugins must handle lost sessions, stale state, and application retries where required; see [connection handling](../writing-plugins.md#handling-connection-events) for the plugin hooks and queueing behavior.
Plugins must handle lost sessions, stale state, and application retries where required; see [connection handling](writing-plugins.md#handling-connection-events) for the plugin hooks and queueing behavior.
![Conector States](../assets/connector_states.svg)
@@ -5,20 +5,21 @@
- CHANGELOG.md in the repository root
- The changelog.txt file in mod directories
Pull requests will usually have suggestions for changelog entries. These can be automatically parsed and formatted by running `node scripts/pr_to_changelog.mts`, though you will have to manually sort through which should go in the changelog in the repository root and which should go in the changelogs in mod directories.
Pull requests have a changelog section that is parsed and formatted by `node scripts/pr_to_changelog.mts`.
The prepare release script below adds its output to CHANGELOG.md, but changes to mods still have to be copied into the changelogs in the mod directories by hand.
If the script fails due to GitHub's 60/hour public access rate limit, you can set the `GH_TOKEN` environment variable to a fine-grained personal access token which has a much higher rate limits.
## Packages
The [Publish workflow](../.github/workflows/publish.yml) publishes npm packages and Lua mods on GitHub's `release: released` event for a stable release.
The [Publish workflow](../../.github/workflows/publish.yml) publishes npm packages and Lua mods on GitHub's `release: released` event for a stable release.
Publishing a prerelease does not trigger it; see [GitHub's release event documentation](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#release).
The npm release includes the packages under `packages/` and the six core plugins under `plugins/`.
Community plugins hosted in separate repositories have independent versions and releases.
For this workflow, first merge the changelog and package version updates into `master`, then create and push the release tag on that merged commit.
Create a draft GitHub release for the existing tag and use the GitHub Release Markdown from `scripts/pr_to_changelog.mts` as its notes.
For this workflow, push the commit and tag made by `scripts/prepare_release.mts` to `master`.
Create a draft GitHub release for the existing tag and use the GitHub Release Markdown printed by `scripts/prepare_release.mts` as its notes.
Publishing the draft as a stable release triggers the workflow; pushing a tag alone does not.
Preparing a release PR, pushing a tag, and publishing a release or packages are separate actions; obtain authorization for the publication steps before executing them on someone else's behalf.
Preparing a release, pushing a tag, and publishing a release or packages are separate actions; obtain authorization for the publication steps before executing them on someone else's behalf.
The steps below describe publishing npm packages manually instead.
> [!NOTE]
@@ -33,36 +34,31 @@ The steps below describe publishing npm packages manually instead.
git status
```
2. Create a release branch and bump the version in the `package.json` files. The commands below use 2.0.1 to 2.0.2 as an example; substitute the versions for the release you are preparing.
2. Run the prepare release script with the new version.
It sets the version in the `package.json` files under `packages/` and `plugins/`, adds the changelog from merged pull requests to the top of CHANGELOG.md, commits it as "Prepare 2.0.2" and tags that commit `v2.0.2`.
Nothing is pushed.
It also prints the GitHub Release Markdown for the release notes.
If a merged pull request has a missing or malformed changelog section, the script lists the problems and stops before changing anything.
Fix the pull request description and run it again, or pass `--force` to continue anyway. Entries with warnings are kept, pull requests whose changelog section could not be read are left out.
```sh
git switch -c release/2.0.2
sed -i 's/"version": "2\.0\.1"/"version": "2.0.2"/' {packages,plugins}/*/package.json
pnpm install --no-frozen-lockfile
node scripts/prepare_release.mts 2.0.2
```
3. Review and commit the version and changelog changes, then open and merge a release pull request.
3. Review the commit, amend it if the changelog needs edits, then push it and the tag.
If you amend the commit, move the tag with `git tag -f v2.0.2`.
```sh
git add -p
git commit -m "Prepare 2.0.2 release"
git show HEAD
git push upstream master v2.0.2
```
4. After the release pull request is merged, tag the merged commit and push the tag.
```sh
git switch master
git pull --ff-only upstream master
git tag v2.0.2
git push upstream v2.0.2
```
5. For manual publication, perform a clean install and publish the packages. For automated publication, publish the GitHub release as described above instead.
4. For manual publication, perform a clean install and publish the packages. For automated publication, publish the GitHub release as described above instead.
The repository does not track `pnpm-lock.yaml`, so allow pnpm to generate or update it during installation.
```sh
node clean.js --dry-run
node scripts/clean.js --dry-run
pnpm clean
pnpm install --no-frozen-lockfile
pnpm -r --filter='./packages/*' --filter='./plugins/*' --fail-if-no-match publish
@@ -44,7 +44,7 @@ For automatic discovery, include `"clusterio-plugin"` in the package's `"keyword
Installed npm plugins are discovered from the installation's dependencies when controller, host or ctl loads its configuration, and added to `plugin-list.json`.
Discovery starts with the root package's `dependencies`, not `devDependencies`, and follows dependencies of recognized plugins.
It does not search arbitrary nested dependency trees for plugins.
For tooling that needs the same discovery behavior, reuse [loadPluginList](../packages/lib/src/load_plugin_list.ts) rather than maintaining another package scanner.
For tooling that needs the same discovery behavior, reuse [loadPluginList](../../packages/lib/src/load_plugin_list.ts) rather than maintaining another package scanner.
A possible workflow for developing plugins is to place the plugin in a sub-directory of where clusterio has been installed, and rely on Node.js searching up the folder heirarchy for it to find `@clusterio/lib`.
After creating a directory for your plugin, the boilerplate can be generated automaticlly from a set of tempaltes using `npm exec @clusterio/create -y -- --plugin-template` after which you will be asked which areas your plugin will interact with and your plugin's name.
@@ -206,6 +206,9 @@ The context has the following properties:
**logger**:
Logger for this plugin, see [Logging Messages](#logging-messages).
**plugins**:
The other plugins loaded alongside this one, see [Depending on other plugins](#depending-on-other-plugins).
**controller**, **host**, **instance**, **hooks** or **control**:
The object the entrypoint is loaded for.
Controller entrypoints get `controller`, host entrypoints get `host`, instance entrypoints get both `instance` and `host`, clusterioctl entrypoints get `hooks` and web entrypoints get `control`.
@@ -216,11 +219,38 @@ An error thrown by a handler is logged and does not affect the other handlers, t
For TypeScript the context types are exported as `ControllerPluginContext`, `HostPluginContext`, `InstancePluginContext`, `CtlPluginContext` and `WebPluginContext` from their respective packages.
### Depending on other plugins
Plugins are loaded at the same time, so there is no order between them.
A plugin that uses another plugin can wait for it with `plugins.waitFor(name, timeoutMs)` from its context, `timeoutMs` defaults to 30 seconds.
It resolves to the value returned by the other plugin's entrypoint for the same controller, host, instance, clusterioctl or web interface, so a plugin that offers an API to other plugins should return it from its entrypoint.
For deprecated class based plugins it resolves to the plugin instance.
```js
export default async function({ plugins }) {
const other = await plugins.waitFor("other_plugin");
if (other) {
other.doSomething();
}
}
```
If the plugin is already loaded it resolves right away.
If the plugin is not installed, has load_plugin set to false, is disabled by recovery mode, or fails to load, it resolves to undefined right away.
If it times out it resolves to undefined.
In both cases a warning naming both plugins is logged.
`plugins.checkInstalled(name)` tells if a plugin is installed, and `plugins.checkEnabled(name)` tells if it is being loaded alongside yours.
Use `checkEnabled` to avoid the warning for optional plugins.
Startup does not continue until every entrypoint has returned.
Two plugins awaiting each other in their entrypoints hold up startup until one of them times out.
Use `.then` or wait from a hook instead if the other plugin may also wait on yours.
### Class based plugins
Plugins written as classes deriving from `BaseControllerPlugin`, `BaseHostPlugin`, `BaseInstancePlugin`, `BaseCtlPlugin` or `BaseWebPlugin` still load, but this way of defining plugins is deprecated and a warning is logged when such a plugin is loaded.
The base class constructor attaches the `on*` methods overridden by the plugin to the corresponding hooks, and the async `init` method is called immediately after.
See [Migrating Plugins to 2.0](devs/plugin-migration-to-2.0.md) for how to convert them.
See [Migrating Plugins to 2.0](plugin-migration-to-2.0.md) for how to convert them.
## Logging Messages
+1 -1
View File
@@ -17,7 +17,7 @@ The blue arrows point from the hosts and clients to the controller they connect
The orange lines connect each host to the Factorio processes it manages.
Open the [full-size diagram](assets/clusterio_2.0_block_diagram.svg) to zoom in, or use the [Draw.io source](assets/clusterio_2.0_block_diagram.drawio) to edit it.
For how messages are handled and routed between these components, see the [communication guide](communication.md).
For how messages are handled and routed between these components, see the [communication guide](devs/communication.md).
## Save Patching
+132 -348
View File
@@ -1,426 +1,210 @@
# Managing a Cluster
Clusterio clusters are managed through the controller by using the `clusterioctl` command line interface which is invoked by running `npx clusterioctl <command>` in the clusterio directory.
This document uses the shorthand `ctl> foo` to indicate `npx clusterioctl foo` should be executed.
Mandatory parameters are shown in `<angles bracket>` and optional pameters are in `[square brackets]`.
Before `clusterioctl` can be used it needs to be configured for the cluster it will connect to.
The easiest way to do this is to run `npx clusteriocontroller bootstrap create-ctl-config <username>` on the controller, which creates the necessary `config-ctl.json` for managing the cluster as the given user.
This guide goes through the day to day tasks of running a cluster from the web interface.
It assumes Clusterio is installed and running, see the [README](/README.md#installation) for how to get there.
Each section ends with the clusterioctl commands for the same task, see [Clusterioctl](clusterioctl.md) for the details of these.
## Output Format
## Logging in
ctl> --output json <command>
The web interface is hosted by the controller, by default on port 8080.
Log in with an authentication token, the installer prints one for the admin account it creates.
Other users can log in by joining one of the Factorio servers in the cluster if the [Player Auth](/plugins/player_auth/README.md) plugin is installed.
Otherwise a token for a user can be generated on the controller computer with
Print the result of the command as JSON on stdout instead of text meant for reading.
Lists are printed as an array of objects, other results as an object, and commands that have no result print `{"success": true}`.
If the command fails it prints `{"error": "<ClassName>", "message": "<message>"}` and exits with a non-zero exit code.
Log messages are written to stderr in all formats.
npx clusteriocontroller bootstrap generate-user-token <username>
`--output wire` prints the same results in the format they are sent between the controller, hosts and clusterioctl, which uses snake_case names like `is_admin`.
The `json` format uses the property names shown in the tables of the human format.
A token gives full access to the account it is for until it is revoked with the Revoke token button on the page of the user.
`log follow` and `debug dump-ws` keep running and print one JSON object per line as entries arrive.
`instance start-all` and `instance stop-all` print an array with an entry per instance, which has an `error` property if that instance failed to start or stop.
The default is `--output human`, which prints `Command ran successfully` for commands that have no result.
What a user can see and do in the web interface depends on their roles, see [Users and Permissions](#users-and-permissions).
## Hosts
### List hosts
A host is a computer that runs Factorio servers for the cluster.
See [Setting up remote hosts](/README.md#setting-up-remote-hosts) for how to add one.
ctl> host list
The Hosts page lists the hosts with their CPU, memory and disk usage.
The page of a host shows the instances assigned to it, its log and its config.
From there it can be restarted, updated, or removed from the cluster with Revoke host access.
Lists all hosts.
ctl: [Hosts](clusterioctl.md#hosts).
Hosts are added to the cluster by running the installer on the computer the host runs on and approving the code it shows, see [Setting up remote hosts](/README.md#setting-up-remote-hosts).
Listing, approving and rejecting hosts waiting for approval needs the `core.host.approve` permission.
### List pending hosts
ctl> host pending
Lists hosts waiting for approval with the code they show, the name they asked for, the address they connected from and how long they have been waiting.
A request goes away when its host stops waiting, and after the time set by `controller.host_pairing_timeout`, an hour by default, after which the host asks again with a new code.
### Approve host
ctl> host approve <code> [--name <host name>]
Approves the host showing the code and prints the id of the new host.
The code is not case sensitive and the dash can be left out.
`--name` gives the host a different name than the one it asked for.
Approving gives the host full access to the cluster, check with `host pending` that the name and address match the computer you are setting up.
### Reject host
ctl> host reject <code>
Rejects the host showing the code, the host then exits with an error.
### Revoke host
ctl> host revoke <host>
Specify the host by name or ID.
Removes the host from the cluster, disconnects it and makes its token stop working.
Instances assigned to the host become unassigned, their files stay on the computer.
Requires the `core.host.revoke` permission.
To add the computer back to the cluster, start the host again and approve it.
### Update Clusterio
ctl> host update <host> [--all] [--restart]
Specify the host by name or ID.
If remote updates are enabled on the host, this will attempt to update `@clusterio/host` on the machine. Add `--all` to also update all npm-installed plugins. Changes will not be applied until the host is restarted. If the `--restart` flag is provided, the host will automatically restart once the update is complete.
Remote updates are enabled by default but can be disabled on a per-machine basis at the owner's discretion. For security reasons, this configuration setting cannot be changed remotely. To modify it, run the following command locally while the host is offline:
host> config set host.allow_remote_updates true/false
The controller also supports remote updates, following the same logic. The corresponding commands are:
ctl> controller update [--all] [--restart]
controller> config set controller.allow_remote_updates true/false
### Mark restart required
ctl> host mark-restart-required <host>
Marks the host as requiring a restart, the same way a plugin update does. Use it after installing or changing a plugin by other means than `host plugin install`, such as a plugin checked out into `external_plugins`. The mark shows up in the web interface on the next system metrics poll. The controller has the same command:
ctl> controller mark-restart-required
## Instances
### List Instances
An instance is a Factorio server along with its config and saves.
Instances are assigned to a host, which is where the server runs and the saves are stored.
ctl> instance list [--templates]
### Creating an instance
List instances.
Templates are only listed if `--templates` is passed.
Click Create on the Instances page and give the instance a name.
The Host field assigns it to a host straight away, and once a host is picked the Start after creation box starts the instance as soon as it is created.
In this example leave the host unassigned and the box unticked, so the instance can be set up before it starts.
Then open the instance and assign it to a host with the Assign button.
### Create instance
The instance uses the default mod pack set on the Controller page, which is the base game of the newest Factorio version unless changed.
To use a different one pick it under Config -> Factorio -> Mod pack on the instance page, see [Mod Packs](#mod-packs) for setting them up.
ctl> instance create <name> [--id <instance id>] [--from <instance id>] [--template <instance>] [--as-template]
ctl: [Create instance](clusterioctl.md#create-instance), [Assign instance to host](clusterioctl.md#assign-instance-to-host).
Create a new instance. `name` is the instance name. `--id` is the optional id. `--from` copies the config of an existing instance. `--template` makes the new instance inherit all config values from the given template. `--as-template` creates the instance as a template, see `instance.is_template` in the [configuration docs](configuration.md). Use `--as-template --from <instance>` to make a template out of an existing instance.
### Starting and stopping
### Kill instance
Click Start on the instance page.
The instance loads the save that was modified last, or creates a new map if it has no saves.
To load a different save, click it in the saves list and use Load save, see [Saves](#saves).
Players connect to the address shown under Public address, or with the Connect via Steam button.
If Factorio credentials are available to the instance and it is set to public, which it is by default, it is also listed in the in-game server browser.
Credentials are taken from the controller, see [Mod Packs](#mod-packs), or set on the host or the instance.
ctl> instance kill <name>
Stop saves the game and shuts the server down.
Restart, in the menu next to Stop, stops the instance and starts it again with the latest save.
Start all and Stop all on the Instances page do the same for every instance, start all skips instances with `instance.exclude_from_start_all` set.
Terminates the running Factorio server without giving it a chance to save or cleanup after itself.
An instance can be started automatically when its host starts with `instance.auto_start`, and restarted after a crash with `instance.restart_after_crash`.
Note: This may cause loss of data.
ctl: [Start instance](clusterioctl.md#start-instance), [Stop instance](clusterioctl.md#stop-instance), [Start all instances](clusterioctl.md#start-all-instances).
### Save game
### Changing settings
ctl> instance save-game <name>
The Config section at the bottom of the instance page holds the instance settings.
The server name, description, password, player limit and other options from Factorio's server-settings.json are under Factorio -> Settings.
Most of these, like the name, password and player limit, are applied to a running server right away.
See [Instance Configuration](configuration.md#instance-configuration) for every setting.
Saves the running game of the instance to the save it was started from and waits for the save to finish.
To share settings between instances, make one instance into a template with Create template and create the other instances from it.
Instances created from a template take every setting they don't set themselves from it, and follow changes made to the template.
### Extract players from instance
ctl: [Config management](clusterioctl.md#config-management).
ctl> instance extract-players <name>
### Running commands
Creates a user account in the cluster for each player that has been online on the currently running save of the instance and sets the online time of that account on this instance to the online time recorded in the save.
The Console section on the instance page shows the log of the instance, and commands typed into it are sent to the Factorio server.
This works like the in-game console with admin rights, so `/c` runs Lua and disables achievements.
Useful when importing a save to a cluster.
Note that the online time in a save is recorded differntly from how Clusterio records online time.
Most notably Clusterio records wall clock time while the save time is recorded in ticks and this extraction of player time assumes the game runs at 60 ticks a second.
ctl: [Send RCON command](clusterioctl.md#send-rcon-command).
### Config management
## Saves
#### List Configuration
The saves list on the instance page shows the saves stored on the host for that instance.
Click a save to show the actions for it.
Load save starts the instance with that save, and Download, Rename, Copy and Delete do what they say.
Transfer moves or copies the save to another instance, which can be on a different host.
ctl> instance config list <instance>
New saves can be made with Create save, which generates a new map, optionally from a seed or a map exchange string.
Saves can also be uploaded with Upload save or by dropping a save file onto the list.
List config values for an instance. `instance` is the instance whose config values to list. Values inherited from a template are marked with `(inherited)`, object fields also list the properties set on the instance.
Several saves can be selected at once with the checkboxes to download, transfer or delete them together.
#### Set config value
The `_autosave` saves are written by Factorio.
Loading one starts the instance from a copy of it, so the autosave isn't overwritten.
ctl> instance config set <instance> <field> [value] [--stdin]
ctl: [Saves](clusterioctl.md#saves).
Set field in instance config. `instance` is instance to set. `field` is field to set. `value` is value to set in field. `--stdin` signals to read value from stdin.
#### Set config property of field
## Mod Packs
To be written.
Mods in Clusterio are managed as parts of mod packs.
A mod pack is a list of mods with their versions, and the mod settings to use with them.
Every instance uses one mod pack, and hosts download the mods in it from the controller when the instance starts.
#### Inherit config value
On the Mods page, use Search to browse the Factorio Mod Portal and download mods to the controller, or upload mod zip files with Upload.
Mod Portal downloads require the controller's [Factorio account credentials](configuration.md#controllerfactorio_username) to be configured.
The username and token are on your profile page on factorio.com, use the token there and not your password.
By default the controller also sends these credentials to the hosts, which put them in the server settings of every instance they start.
This is needed for instances to be listed in the in-game server browser, but it means anyone with access to a host computer can read the token.
Turn off `controller.share_factorio_credentials_with_hosts` if you don't trust the hosts with it.
ctl> instance config inherit <instance> <field> [prop]
Use Create in the Mod Packs section to create a mod pack, then add the mods you want to use.
The built in mods of Factorio, like `space-age`, `quality` and `elevated-rails`, are part of every mod pack for a Factorio version that has them.
They can't be removed, but they can be disabled, and only `base` is enabled in a new mod pack.
Assign the mod pack to an instance under Instance config -> Factorio -> Mod pack, or set a default mod pack for new instances on the Controller page.
Make a field in the instance config take its value from the template again, undoing a previous `set`. `instance` is the instance to update, `field` is the field to inherit, `prop` limits it to one property of an object field.
![Select mod pack for instance](assets/config_select_mod_pack.png)
#### Edit instance config
Mod settings are changed on the page of the mod pack.
The settings only show up after data has been exported for the mod pack, see the next section.
ctl> instance config edit <instance> [editor]
![Mod settings configuration in web interface](assets/mod_settings_configuration.png)
Edit instance config in a text editor. Once file is saved and editor has been exited, changed config values will be read back in. `instance` is the instance to edit, `editor` is the editor to use. If `editor` is not given, clusterioctl will read from the `EDITOR` or `VISUAL` enviroment variables.
Mod packs can be shared between clusters with Export to string on the mod pack page and Import string on the Mods page.
### Assign instance to host
ctl: [Mods](clusterioctl.md#mods), [Mod Packs](clusterioctl.md#mod-packs).
ctl> instance assign <instance> [host]
### Exporting data
Assigns instance to host. `instance` is instance to assign, `host` is host to assign to. If `host` is not provided, instance will be unassigned.
The web interface does not know the names and icons of items, or which settings mods have, until they have been exported from Factorio.
Until then items are shown by their internal name without an icon, and the mod pack page has no settings to edit.
This affects every page that shows items, including the plugin pages of Subspace Storage and Player Sync, which use the export of the default mod pack.
## Users
To export the data, assign the mod pack to an instance, stop the instance, and click More -> Export data on the instance page.
The export belongs to the mod pack the instance uses, so do this once for each mod pack.
Run it again after adding or updating mods in the pack.
Clusterio automatically creates user accounts for all players that join an instance when save patching is enabled.
These accounts are used to store per player data shared between instances, like if the player should be whitelisted, admin or banned.
![Export mod configuration data](assets/export_mod_config_data.png)
### List users
The icons of the base game are read from the Factorio install on the host.
The headless build of Factorio has no graphics, so on a host that only has the headless build the export has the names but none of the base game icons, and the host logs a warning about it.
To get the icons, put a full install of the same Factorio version into the `host.factorio_directory` of the host, or export from a host that has one.
Icons from mods are read from the mod files and are exported either way.
ctl> user list
The Icon reference link under Inspect exported data on the mod pack page shows everything in the export.
Lists all user accounts in the cluster along with some data for each.
ctl: [Export data](clusterioctl.md#export-data).
### Create User
## Users and Permissions
ctl> user create <name>
### Players
Creates a new empty user account for the given Factorio player.
Note that case matters here.
This is usually not required as user accounts are created automatically for players that join instances with save patching enabled.
Clusterio creates a user account for every player that joins an instance.
The Users page lists them with their online time.
The page of a user shows their stats per instance, and has switches for making them an in-game admin, whitelisting them, and banning them.
These lists are shared between all instances that have `factorio.sync_adminlist`, `factorio.sync_whitelist` and `factorio.sync_banlist` turned on, which they are by default.
The whitelist is only enforced on instances with `factorio.enable_whitelist` turned on.
Existing Factorio admin, ban and whitelist files can be imported with Bulk Actions on the Users page, which can also export them.
### Promote User to Server Admin
ctl: [Users](clusterioctl.md#users).
ctl> user set-admin <name> [--revoke] [--create]
### Granting access to the cluster
Promotes the user given to in-game admin on instances with the `sync_adminlist` option enabled.
If the `--revoke` switch is used the user is removed from the adminlist.
Being an in-game admin does not give any access to manage the cluster.
Access to the web interface and clusterioctl is controlled by roles, which are sets of permissions.
There are two roles by default: Cluster Admin, which can do everything, and Player, which can view most of the cluster but not change anything.
New users get the Player role.
Since admin status is a part of the account data the account must exist for this to succeed, passing `--create` will create the account if it does not exist.
To let someone manage part of the cluster, create a role on the Roles page and tick the permissions it should grant.
Every user keeps the Player role, so a new role only needs the permissions on top of it.
For example, a role for starting and stopping servers needs only `core.instance.start` and `core.instance.stop`.
Then add the role to the user under Roles on the page of the user.
Use the Cluster Admin role for people who should have full control.
**Note:** Being a server admin does not grant any access to manage the cluster.
See [set-roles](#set-cluster-roles) for adding roles which grant access to managing the clusetr.
Be careful with what a role grants, some permissions give much more control than their name first suggests.
The Roles page marks these permissions that can stop, kill, delete, revoke or update things as dangerous.
For example `core.controller.stop` and `core.host.stop` shut down Clusterio on that computer, and it can only be started again by someone with access to the computer.
Or `core.user.update_roles` and `core.role.update` which are as powerful as Cluster Admin because setting roles has no restrictions, so a user can give themselves the Cluster Admin role.
The user can then log in as described in [Logging in](#logging-in).
### Whitelist User
ctl: [Roles](clusterioctl.md#roles), [Set Cluster Roles](clusterioctl.md#set-cluster-roles).
ctl> user set-whitelisted <name> [--remove] [--create]
Add the user given to the whitelist on instances with the `sync_whitelist` option enabled.
If the `--remove` switch is used the user is removed from the whitelist.
## Plugins and Updates
Since whitelisted status is a part of the account data the account must exist for this to succeed, passing `--create` will create the account if it does not exist.
The Plugins page lists the plugins installed on the controller and each host, with their versions.
If remote updates are enabled, Clusterio and plugins installed from npm can be updated from here, and the Controller and host pages have an Update Clusterio button.
Browse plugins searches npm for plugins, installing them from the web interface needs remote installs to be enabled on the computer.
Installs and updates take effect after a restart, the Plugins page shows which computers are waiting for one.
See [Plugins (Remote)](clusterioctl.md#plugins-remote) for turning remote updates and installs on or off.
Plugins can also be installed on the computer itself, see [Installing Plugins](/README.md#installing-plugins).
### Ban User
ctl> user set-banned <name> [--reason <message>] [--pardon] [--create]
## Logs
Ban user in-game from instances with the `sync_banlist` option enabled.
Reason is a message that will be shown to the user when attemption to log in.
If the `--pardon` switch is used it removes the ban.
The Controller page shows the log of the controller, the page of a host the log of that host, and the instance page the log of the instance and its Factorio server.
The log files are stored in the `logs` folder of the controller and are kept for `controller.log_retention_days` days.
Since ban status is a part of the account data the account must exist for this to succeed, passing `--create` will create the account if it does not exist.
Note: This bans the user from logging in to Factorio servers in the cluster, it does not revoke access to any cluster management they might have, see next section on setting roles for revoking tha.
### Bulk importing admin, whitelist and ban lists
Admin lists, whitelists and banlists can be bulk imported with the following command:
ctl> user import <file> [--admins|--whitelist|--bans|--users]
The admin list and whitelist files should be a JSON array of names, the same format as Factorio's server-adminlist.json and server-whitelist.json:
["joe", "bob", "allan"]
The banlist file uses the format of Factorio's server-banlist.json, where each entry is either a name or an object with a username and reason:
[
"joe",
{"username": "bob", "reason": "stole materials"},
{"username": "allan", "reason": "rude language"}
]
The `--users` option imports a file written by `user export`, which holds the admin, whitelist and ban status of every user.
If no option is given the type is guessed from the file, files with an `export_version` field are treated as user exports, otherwise the file name must contain ban, admin or whitelist.
Users that do not exist are created.
Importing only adds to the existing lists, it never removes anyone from them.
To replace a list instead, use restore:
ctl> user restore <file> [--admins|--whitelist|--bans|--users] [--no-backup]
This takes the same files as import, but removes everyone not in the file from the list.
The previous list is written to `<type>-backup.json` in the current directory unless `--no-backup` is passed.
The current lists can be exported with the following command:
ctl> user export <file> [--admins|--whitelist|--bans|--users]
Defaults to exporting users.
### Set Cluster Roles
ctl> user set-roles <name> [roles...]
Replaces the roles the user has in the cluster with a new list of roles.
Calling with an empty roles argument will remove all roles from the user.
By default there's a roled named Cluster Admin which grants access to everything and a role named Player which grants a limited read access to the cluster, see [the section on roles](#roles) for more information about setting up roles and permissions.
### Delete user
ctl> user delete <name>
Deletes everything stored on the controller for this user.
Note: If the player is banned from the cluster this will effectively unban them, as the ban status is stored with the user account.
Note: If the player joins the cluster again a new account will be made for them automatically.
## Roles
To be written.
## Notes
Free text notes can be attached to hosts, instances, users, roles, mod packs, mods and saves.
They are stored on the controller and shown to everyone with access to the resource in the web interface, and can for example be used to record who runs a host or what an instance is meant for.
The web interface renders notes as Markdown.
A mention of the form `@<type>/<id>` becomes a link to that resource showing its name, for example `@instance/778528005` or `@user/cooldude2606`.
This works for hosts, instances, users, roles and mod packs, and the id is shown if the name is not available.
The note itself stores the mention as written.
### List notes
ctl> note list [--type <type>]
Lists all notes, optionally limited to one resource type.
### Set note
ctl> note set <type> <id> <content>
Sets the note of a resource.
The type is one of host, instance, user, role, mod_pack, mod or save.
The id is the numeric id for hosts, instances, roles and mod packs, the lower case name for users, `<name>_<version>` for mods and `<instance id>/<file name>` for saves.
### Delete note
ctl> note delete <type> <id>
Removes the note of a resource.
Notes are also removed when the resource they are attached to is deleted.
## Plugins (Local)
To be written.
## Plugins (Remote)
The installer asks "Allow remote updates and plugin installs from the web interface?" and the answer sets `allow_remote_updates`, `allow_plugin_updates` and `allow_plugin_install` together on that machine, pass `--remote-npm` or `--no-remote-npm` to answer it from the command line.
Remote updates allow ctl and the web UI to update Clusterio and plugins on machines within the cluster.
Remote installs allow them to install any package from npm onto the machine, which is a risk of arbitrary code execution through malicious npm packages, so only allow them if you trust everyone with access to install plugins.
In a config created without the installer remote updates are enabled and remote installs are disabled by default.
See below for changing these settings after installing.
### List
ctl> controller plugin list
ctl> host plugin list <host>
This command lists all plugins currently known to the remote. Newly installed plugins will not be displayed until the remote is restarted. Plugins that are distributed as an npm package can be updated remotely.
### Update
ctl> controller plugin update <name>[@<version>] [--restart]
ctl> host plugin update <host> <name>[@<version>] [--restart]
If remote plugin updates are enabled on the remote, this will execute `npm update --save <name>`, which stays within the version range saved in the remote's `package.json`.
To update to a specific version, including one outside that range, pass it as `<name>@<version>`, for example `@clusterio/plugin-example@2.1.0`.
The version must be published on npm, and the remote then executes `npm install --save <name>@<version>`.
The plugin must already be installed on the remote, and only remote plugin updates need to be enabled.
Changes will not be applied until the remote is restarted.
If the `--restart` flag is provided, the remote will automatically restart once the update is complete.
### Update All
ctl> controller update --all [--restart]
ctl> host update <host> --all [--restart]
Updates the Clusterio package and all plugins installed from npm in a single `npm update --save` command. Updating everything at once avoids ending up with multiple versions of `@clusterio/lib` in the installation. Requires both remote updates and remote plugin updates to be enabled on the remote.
### Install
ctl> controller plugin install <name>[@<version>] [--restart]
ctl> host plugin install <host> <name>[@<version>] [--restart]
If remote plugin installs are enabled on the remote, this will execute `npm install --save <name>`.
Pass `<name>@<version>` to install a specific version, for example to match the version used by the rest of the cluster.
The package, and the version if given, must be published on npm.
Changes will not be applied until the remote is restarted.
If the `--restart` flag is provided, the remote will automatically restart once the update is complete.
### Search
ctl> controller plugin search [query] [--page <n>] [--page-size <n>]
Searches the npm registry for packages tagged with the clusterio-plugin keyword.
The search is done by the controller and does not require remote installs to be enabled.
The web UI has a plugin browser on the plugins page that uses the same search.
### Concurrent Operations
Only one npm operation runs at a time on a machine.
A standalone controller and host share their working directory, so the operation holds the `npm-operation.lock` file there while npm runs.
Other installs and updates on the same machine or installation are rejected with "Another package operation is already in progress on this machine" until it finishes.
A lock file left behind by a process that is no longer running is removed automatically.
### Enable/Disable Updates
host> config set host.allow_plugin_updates true/false
controller> config set controller.allow_plugin_updates true/false
Remote updates are enabled by default but can be disabled on a per-machine basis at the owner's discretion. For security reasons, this configuration setting cannot be changed remotely. To modify it, run the above commands locally while the remote is offline.
### Enable/Disable Installs
host> config set host.allow_plugin_install true/false
controller> config set controller.allow_plugin_install true/false
Remote installs are disabled by default but can be enabled on a per-machine basis at the owner's discretion. For security reasons, this configuration setting cannot be changed remotely. To modify it, run the above commands locally while the remote is offline.
## Prometheus Metrics
The controller exports metrics for the whole cluster on the `/metrics` endpoint.
Fetching it requires a token for a user with the `core.controller.metrics` permission, sent either as an `Authorization: Bearer <token>` header or as an `X-Access-Token` header.
Requests without a valid token get a 401 response and requests for users lacking the permission get a 403 response.
Create a role with just this permission, a user to hold it, and generate a token for that user.
Give the user a name that is not a valid Factorio player name, such as one starting with `#`, so a player joining the cluster can never claim the account and its token:
ctl> role create Prometheus --permissions core.controller.metrics
ctl> user create #prometheus
ctl> user set-roles #prometheus Prometheus
$ npx clusteriocontroller bootstrap generate-user-token '#prometheus'
Then pass the token in the scrape job for the controller in `prometheus.yml`:
scrape_configs:
- job_name: clusterio
authorization:
credentials: <token>
static_configs:
- targets: ["localhost:8080"]
Concurrent scrapes share a single round of metrics gathering from the hosts, so multiple scrapers polling the controller do not multiply the load on the hosts.
ctl: [Logs](clusterioctl.md#logs).
+1 -1
View File
@@ -17,7 +17,7 @@
"ci-cover": "c8 --reporter=lcovonly pnpm test",
"lint": "oxlint packages plugins test",
"lint-fix": "oxlint --fix packages plugins test",
"clean": "node ./clean.js",
"clean": "node ./scripts/clean.js",
"bundle-dependencies": "bundle-dependencies"
},
"c8": {
+4 -7
View File
@@ -21,7 +21,6 @@ import crypto from "crypto";
import yargs from "yargs";
import util from "util";
import winston from "winston";
import DailyRotateFile from "winston-daily-rotate-file";
// homebrew modules
@@ -355,19 +354,17 @@ async function initialize(): Promise<InitializeParameters> {
level: "verbose",
levels,
});
clusterLogger.add(new DailyRotateFile({
clusterLogger.add(new lib.DailyFileTransport({
format: winston.format.json(),
filename: "cluster-%DATE%.log",
utc: true,
dirname: path.join(args.logDirectory, "cluster"),
prefix: "cluster",
}));
// Log stream for the controller.
logger.add(new DailyRotateFile({
logger.add(new lib.DailyFileTransport({
format: winston.format.json(),
filename: "controller-%DATE%.log",
utc: true,
dirname: path.join(args.logDirectory, "controller"),
prefix: "controller",
}));
logger.add(new winston.transports.Stream({
stream: clusterLogger,
+1 -2
View File
@@ -1,6 +1,6 @@
{
"name": "@clusterio/controller",
"version": "2.1.1",
"version": "2.1.2",
"description": "Implementation of Clusterio controller",
"homepage": "https://github.com/clusterio/clusterio#readme",
"author": "Hornwitser <github@hornwitser.no>",
@@ -45,7 +45,6 @@
"jsonwebtoken": "catalog:",
"semver": "catalog:",
"winston": "catalog:",
"winston-daily-rotate-file": "catalog:",
"ws": "catalog:",
"yargs": "catalog:"
},
+28 -20
View File
@@ -48,6 +48,11 @@ const logSizeGauge = new Gauge(
type InstanceId = { instanceId: number };
const htmlEscapes: Record<string, string> = { "&": "&amp;", "<": "&lt;", ">": "&gt;", "\"": "&quot;", "'": "&#39;" };
function escapeHtml(text: string) {
return text.replace(/[&<>"']/g, char => htmlEscapes[char]);
}
type ControllerDebugEvents = {
"message": [ { direction: "in" | "out", content: string } ],
};
@@ -1580,7 +1585,7 @@ export default class Controller {
}
async loadPlugins() {
const context = { metrics, logger, controller: this };
const toLoad: lib.PluginNodeEnvInfo[] = [];
for (let pluginInfo of this.pluginInfos) {
try {
const manifestPath = path.posix.join(pluginInfo.requirePath, "dist", "web", "manifest.json");
@@ -1603,25 +1608,20 @@ export default class Controller {
continue;
}
try {
await lib.loadPlugin(
pluginInfo,
"controller",
context,
"ControllerPlugin",
BaseControllerPlugin,
);
toLoad.push(pluginInfo);
}
this.loadedPlugins.add(pluginInfo);
} catch (err: any) {
if (err.code === "InstallationError") {
throw err;
}
throw new lib.PluginError(pluginInfo.name, err);
}
logger.info(`Loaded plugin ${pluginInfo.name}`);
const { loaded } = await lib.PluginLoader.load({
type: "controller",
context: { metrics, controller: this },
logger,
installed: this.pluginInfos,
load: toLoad,
exportName: "ControllerPlugin",
baseClass: BaseControllerPlugin,
});
for (const pluginInfo of loaded.keys()) {
this.loadedPlugins.add(pluginInfo);
}
}
@@ -1720,8 +1720,16 @@ export default class Controller {
path.join(import.meta.dirname, "..", "..", "..", "web", "index.html"),
"utf8",
).then(async (content) => {
const config: lib.ControllerConfig = res.app.locals.controller.config;
let faviconUrl = config.get("controller.favicon_url");
// Relative to the web root rather than the page
if (faviconUrl && !/^([a-z][a-z0-9+.-]*:|\/)/i.test(faviconUrl)) {
faviconUrl = webRoot + faviconUrl;
}
const favicon = faviconUrl ? `<link rel="icon" href="${escapeHtml(faviconUrl)}" />` : "";
content = content
.replace(/__CLUSTER_NAME__/g, res.app.locals.controller.config.get("controller.name"))
.replace(/__CLUSTER_NAME__/g, () => escapeHtml(config.get("controller.name")))
.replace(/__FAVICON__/g, () => favicon)
.replace(/__WEB_ROOT__/g, webRoot)
.replace(/__STATIC_ROOT__/g, staticRoot)
.replace(/__IMPORT_MAP__/g, () => importMap)
+35 -23
View File
@@ -419,7 +419,7 @@ export interface ProxyStream {
timeout: ReturnType<typeof setTimeout>;
closed: boolean;
/** Bytes the receiver has taken, set once the stream is flowing */
progress?: () => number;
bytesTaken?: () => number;
}
export async function createProxyStream(app: Application): Promise<ProxyStream> {
@@ -473,18 +473,23 @@ const answeredUploadDrainMs = 1000;
* so the connection is closed if the body hasn't ended shortly after the
* response. Closing it right away could make the client lose the response.
*
* The connection is also closed if the request moved less than
* controller.transfer_min_progress during a check interval, so that a
* The connection is also closed if the request moved too little during a
* check interval for controller.transfer_min_speed, so that a
* request which stalled or is trickled in does not stay open forever while
* a slow one can take the time it needs. For a request body this is what
* was received of it. For both ends of a proxy stream it is what the
* receiver has taken, as the sender is held back when the receiver is the
* slow one. Time spent waiting for a proxy stream to start is not counted,
* controller.proxy_stream_timeout limits that.
*
* The OS hands data on in bursts, so a transfer at the minimum speed can
* move up to a burst less than that in a check. The burst allowance is
* taken off what a check requires so such a transfer is never closed.
* @param checkIntervalMs - Interval to check the progress of requests on.
* @param burstAllowanceBytes - Bytes taken off what a check requires.
* @returns Express middleware.
*/
function guardRequest(checkIntervalMs: number) {
function guardRequest(checkIntervalMs: number, burstAllowanceBytes: number) {
return function(req: Request, res: Response, next: any) {
const socket = req.socket;
res.once("finish", () => {
@@ -501,33 +506,36 @@ function guardRequest(checkIntervalMs: number) {
});
});
const received = () => socket.bytesRead;
let measure: (() => number) | undefined = received;
let last = received();
const bytesReceived = () => socket.bytesRead;
let measuredBytes: (() => number) | undefined = bytesReceived;
let lastBytes = bytesReceived();
const check = setInterval(() => {
const stream: ProxyStream | undefined = res.locals.proxyStream;
let current: (() => number) | undefined;
let currentBytes: (() => number) | undefined;
if (stream && !stream.closed) {
current = stream.progress;
currentBytes = stream.bytesTaken;
} else if (!req.complete) {
current = received;
currentBytes = bytesReceived;
}
const minProgress = req.app.locals.controller.config.get("controller.transfer_min_progress");
if (current !== measure || !current || !minProgress) {
const minSpeedKiBps = req.app.locals.controller.config.get("controller.transfer_min_speed");
if (currentBytes !== measuredBytes || !currentBytes || !minSpeedKiBps) {
// What to measure changed, start over from here.
measure = current;
last = current ? current() : 0;
measuredBytes = currentBytes;
lastBytes = currentBytes ? currentBytes() : 0;
return;
}
const progress = current();
if (progress - last < minProgress * 1024) {
const bytes = currentBytes();
const intervalS = checkIntervalMs / 1000;
// At least 1 so a transfer that moved nothing is closed at any speed setting.
const requiredBytes = Math.max(minSpeedKiBps * 1024 * intervalS - burstAllowanceBytes, 1);
if (bytes - lastBytes < requiredBytes) {
logger.warn(
`Closing ${req.method} ${req.path}, it moved less than ${minProgress} KiB ` +
`in ${checkIntervalMs / 1000} seconds`
`Closing ${req.method} ${req.path}, it moved ${bytes - lastBytes} bytes in ${intervalS} seconds, ` +
`less than the ${requiredBytes} required for ${minSpeedKiBps} KiB/s`
);
socket.destroy();
}
last = progress;
lastBytes = bytes;
}, checkIntervalMs);
res.once("close", () => clearInterval(check));
next();
@@ -567,7 +575,7 @@ function startStream(res: Response, stream: ProxyStream) {
source.pipe(res);
stream.flowing = true;
// Counts completed writes, so data waiting in a buffer is not progress.
stream.progress = () => socket.bytesWritten - socket.writableLength;
stream.bytesTaken = () => socket.bytesWritten - socket.writableLength;
// Pipe does not pass on a source that was cut short, the receiver would wait forever.
const onSourceClose = () => {
if (!res.writableEnded) {
@@ -828,7 +836,7 @@ async function uploadMod(req: Request, res: Response) {
// Pipe does not pass on an upload that was cut short.
await Promise.all([finished(file.stream), finished(writeStream)]);
const modInfo = await lib.ModInfo.fromModFile(tempFilePath);
const modInfo = await lib.ModStore.readModInfo(tempFilePath);
checkModName(modInfo.filename);
await fs.rename(tempFilePath, path.join(modsDirectory, modInfo.filename));
req.app.locals.controller.modStore.addMod(modInfo);
@@ -856,8 +864,12 @@ async function uploadMod(req: Request, res: Response) {
}
export function addRouteHandlers(app: Application, progressCheckIntervalMs = 30_000) {
app.use(guardRequest(progressCheckIntervalMs));
export function addRouteHandlers(
app: Application,
progressCheckIntervalMs = 60_000,
burstAllowanceBytes = 2 * 1024 * 1024,
) {
app.use(guardRequest(progressCheckIntervalMs, burstAllowanceBytes));
app.get("/metrics",
validateUserToken,
(req:Request, res:Response, next:any) => getMetrics(req, res).catch(next)
+2
View File
@@ -4,7 +4,9 @@
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="theme-color" content="#2a2a2a" />
<meta name="application-name" content="__CLUSTER_NAME__" />
<title>__CLUSTER_NAME__</title>
__FAVICON__
<script type="importmap">__IMPORT_MAP__</script>
<style>
html {
+2 -5
View File
@@ -1,5 +1,5 @@
/* eslint-disable no-console */
import chalk from "chalk";
import { styleText } from "node:util";
export const levels = Object.freeze({
fatal: 0,
@@ -27,10 +27,7 @@ for (let [name, level] of Object.entries(levels)) {
if (level > maxLogLevel) {
return;
}
let style = chalk;
for (let part of colors[name].split(" ")) {
style = style[part];
}
const style = text => styleText(colors[name].split(" "), text);
if (["fatal", "error"].includes(name)) {
console.error(`${style(name)} ${message}`);
} else if (["warn"].includes(name)) {
+1 -2
View File
@@ -1,6 +1,6 @@
{
"name": "@clusterio/create",
"version": "2.1.1",
"version": "2.1.2",
"description": "Installer for clusterio",
"homepage": "https://github.com/clusterio/clusterio#readme",
"author": "Hornwitser <github@hornwitser.no>",
@@ -36,7 +36,6 @@
"@inquirer/confirm": "^6.3.5",
"@inquirer/input": "^5.1.9",
"@inquirer/select": "^5.2.8",
"chalk": "catalog:",
"yargs": "catalog:"
}
}
+3 -3
View File
@@ -3,7 +3,7 @@
Provides a command line interface for managing a Clusterio cluster.
Note that this document only describes the options and commands for managing clusterioctl itself, see [Managing a cluster](/docs/managing-a-cluster.md) for the available commands used for managing a cluster.
Note that this document only describes the options and commands for managing clusterioctl itself, see [Clusterioctl](/docs/clusterioctl.md) for the available commands used for managing a cluster.
## Usage
@@ -25,7 +25,7 @@ Common options:
* `--output <human|json|wire>` Format to print the results of cluster commands in.
Defaults to `human`.
See [Output format](/docs/managing-a-cluster.md#output-format) for what `json` and `wire` print.
See [Output format](/docs/clusterioctl.md#output-format) for what `json` and `wire` print.
The `plugin` and `config` commands described below always print human readable text.
@@ -112,6 +112,6 @@ Lists up all configuration entries with their currently configured values.
## See Also
[Managing a cluster](/docs/managing-a-cluster.md) for the available commands used for managing a cluster.
[Clusterioctl](/docs/clusterioctl.md) for the available commands used for managing a cluster.
[The Clusterio repository](https://github.com/clusterio/clusterio) for instructions on how to set up a cluster.
+10 -12
View File
@@ -118,18 +118,16 @@ async function loadPlugins(pluginList: Map<string, string>, hooks: CtlHooks) {
lib.registerPluginPermissions(pluginInfos);
lib.addPluginConfigFields(pluginInfos);
const ctlPlugins = new Set<lib.PluginNodeEnvInfo>();
for (let pluginInfo of pluginInfos) {
if (!pluginInfo.ctlEntrypoint) {
continue;
}
const context = { hooks, logger, plugin: pluginInfo };
await lib.loadPlugin(pluginInfo, "ctl", context, "CtlPlugin", BaseCtlPlugin);
ctlPlugins.add(pluginInfo);
}
return ctlPlugins;
const { loaded } = await lib.PluginLoader.load({
type: "ctl",
context: { hooks },
logger,
installed: pluginInfos,
load: pluginInfos.filter(pluginInfo => pluginInfo.ctlEntrypoint),
exportName: "CtlPlugin",
baseClass: BaseCtlPlugin,
});
return new Set(loaded.keys());
}
interface CtlArguments {
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@clusterio/ctl",
"version": "2.1.1",
"version": "2.1.2",
"description": "Clusterio command line management tool",
"homepage": "https://github.com/clusterio/clusterio#readme",
"author": "Hornwitser <github@hornwitser.no>",
+2 -4
View File
@@ -17,7 +17,6 @@ import path from "path";
import yargs from "yargs";
import packageConfig from "@clusterio/host/package.json" with { type: "json" };
import winston from "winston";
import "winston-daily-rotate-file";
// internal libraries
// Reduce startup time by lazy compiling schemas.
@@ -147,11 +146,10 @@ async function startHost() {
.parseSync()
;
logger.add(new winston.transports.DailyRotateFile({
logger.add(new lib.DailyFileTransport({
format: winston.format.json(),
filename: "host-%DATE%.log",
utc: true,
dirname: path.join(args.logDirectory, "host"),
prefix: "host",
}));
if (args.logLevel !== "none") {
logger.add(new ConsoleTransport({
+1 -2
View File
@@ -1,6 +1,6 @@
{
"name": "@clusterio/host",
"version": "2.1.1",
"version": "2.1.2",
"description": "Implementation of Clusterio host server",
"homepage": "https://github.com/clusterio/clusterio#readme",
"author": "Hornwitser <github@hornwitser.no>",
@@ -49,7 +49,6 @@
"semver": "catalog:",
"set-blocking": "catalog:",
"winston": "catalog:",
"winston-daily-rotate-file": "catalog:",
"yargs": "catalog:",
"yazl": "catalog:"
},
+16 -19
View File
@@ -351,6 +351,8 @@ export default class Host extends lib.Link {
_shuttingDown = false;
/** Instances waiting on {@link Instance.fromConfig} */
_startingInstances = new Set<number>();
/** Restarts after a crash per instance ID since the last manual start */
_crashRetryAttempts = new Map<number, number>();
startedAtMs = Date.now();
@@ -488,7 +490,7 @@ export default class Host extends lib.Link {
}
async loadPlugins() {
const context = { logger, host: this };
const toLoad: lib.PluginNodeEnvInfo[] = [];
for (let pluginInfo of this.pluginInfos) {
if (
!pluginInfo.hostEntrypoint && !pluginInfo.instanceEntrypoint
@@ -502,25 +504,20 @@ export default class Host extends lib.Link {
continue;
}
try {
await lib.loadPlugin(
pluginInfo,
"host",
context,
"HostPlugin",
BaseHostPlugin,
);
toLoad.push(pluginInfo);
}
this.loadedPlugins.add(pluginInfo);
} catch (err: any) {
if (err.code === "InstallationError") {
throw err;
}
throw new lib.PluginError(pluginInfo.name, err);
}
logger.info(`Loaded plugin ${pluginInfo.name}`);
const { loaded } = await lib.PluginLoader.load({
type: "host",
context: { host: this },
logger,
installed: this.pluginInfos,
load: toLoad,
exportName: "HostPlugin",
baseClass: BaseHostPlugin,
});
for (const pluginInfo of loaded.keys()) {
this.loadedPlugins.add(pluginInfo);
}
}
+63 -21
View File
@@ -44,6 +44,9 @@ const transitoryStatuses: ReadonlySet<Instance["_status"]> = new Set([
"starting", "stopping", "creating_save", "exporting_data",
]);
// Crashes sooner than this after starting are not restarted to avoid boot loops.
const crashRestartMinUptimeMs = 10 * 60e3;
const instanceRconCommandDuration = new lib.Histogram(
"clusterio_instance_rcon_command_duration_seconds",
"Histogram of the RCON command duration from request to response.",
@@ -194,6 +197,8 @@ export default class Instance extends lib.Link {
_playerAutosaveSlot = 1;
_expectedUserUpdates: { action: string, name: string, reason: string }[] = [];
_settleWaiters: (() => void)[] = [];
_startedAtMs: number | null = null;
_killRequested = false;
constructor(
host: Host,
@@ -594,6 +599,9 @@ end`.replace(/\r?\n/g, " ");
notifyStatus(status: Instance["_status"]) {
this._status = status;
if (status === "running") {
this._startedAtMs = Date.now();
}
if (!transitoryStatuses.has(status)) {
const waiters = this._settleWaiters;
this._settleWaiters = [];
@@ -643,6 +651,7 @@ end`.replace(/\r?\n/g, " ");
}
notifyExit() {
const crashed = this._status === "running" && !this._killRequested;
this._loadedSave = null;
this._autoPause = false;
this.notifyStatus("stopped");
@@ -668,6 +677,29 @@ end`.replace(/\r?\n/g, " ");
this._recordPlayerLeave(player, "server_quit");
}
this._saveStats().catch(err => this.logger.error(`Error saving stats:\n${err.stack}`));
if (crashed && this.config.get("instance.restart_after_crash") && !this._host._shuttingDown) {
this._restartAfterCrash(Date.now() - this._startedAtMs!);
}
}
_restartAfterCrash(uptimeMs: number) {
if (uptimeMs < crashRestartMinUptimeMs) {
this.logger.error(`Instance ${this.name} crashed within 10 minutes of starting, not restarting it`);
return;
}
const limit = this.config.get("instance.crash_retry_attempts");
const attempts = this._host._crashRetryAttempts.get(this.id) ?? 0;
if (limit > 0 && attempts >= limit) {
this.logger.error(`Instance ${this.name} reached the limit of ${limit} crash restarts, not restarting it`);
return;
}
this._host._crashRetryAttempts.set(this.id, attempts + 1);
const of = limit > 0 ? ` of ${limit}` : "";
this.logger.warn(`Restarting instance ${this.name} after crash, attempt ${attempts + 1}${of}`);
this._host._connectInstance(this.id)
.then(connection => connection.instance._startSave())
.catch(err => this.logger.error(`Error restarting instance ${this.name} after crash:\n${err.stack}`));
}
static async _readStats(statsPath: string) {
@@ -772,8 +804,7 @@ end`.replace(/\r?\n/g, " ");
* Must be called once the instance is connected to the host.
*/
async loadPlugins(pluginInfos: lib.PluginNodeEnvInfo[]) {
// load plugins
const plugins: Record<string, string> = {};
const toLoad: lib.PluginNodeEnvInfo[] = [];
for (let pluginInfo of pluginInfos) {
if (
!pluginInfo.instanceEntrypoint
@@ -788,26 +819,31 @@ end`.replace(/\r?\n/g, " ");
continue;
}
try {
let pluginLoadStartedMs = Date.now();
await lib.loadPlugin(
pluginInfo,
"instance",
{ logger: this.logger, host: this._host, instance: this },
"InstancePlugin",
BaseInstancePlugin,
);
this.loadedPlugins.add(pluginInfo);
plugins[pluginInfo.name] = pluginInfo.version;
this.logger.info(`Loaded plugin ${pluginInfo.name} in ${Date.now() - pluginLoadStartedMs}ms`);
} catch (err) {
this.notifyExit();
await this.sendSaveListUpdate();
throw err;
}
toLoad.push(pluginInfo);
}
let loaded;
try {
({ loaded } = await lib.PluginLoader.load({
type: "instance",
context: { host: this._host, instance: this },
logger: this.logger,
installed: pluginInfos,
load: toLoad,
exportName: "InstancePlugin",
baseClass: BaseInstancePlugin,
}));
} catch (err) {
this.notifyExit();
await this.sendSaveListUpdate();
throw err;
}
const plugins: Record<string, string> = {};
for (const pluginInfo of loaded.keys()) {
this.loadedPlugins.add(pluginInfo);
plugins[pluginInfo.name] = pluginInfo.version;
}
this.send(new lib.InstanceInitialisedEvent(plugins));
}
@@ -1358,6 +1394,7 @@ end`.replace(/\r?\n/g, " ");
if (this._status === "stopped") {
return;
}
this._killRequested = true;
await this.server.kill(true);
}
@@ -1395,7 +1432,11 @@ end`.replace(/\r?\n/g, " ");
}
async handleInstanceStartRequest(request: lib.InstanceStartRequest) {
let saveName = request.save;
this._host._crashRetryAttempts.delete(this.id);
await this._startSave(request.save);
}
async _startSave(saveName?: string) {
if (saveName !== undefined) {
checkRequestSaveName(saveName);
}
@@ -1424,6 +1465,7 @@ end`.replace(/\r?\n/g, " ");
}
async handleInstanceLoadScenarioRequest(request: lib.InstanceLoadScenarioRequest) {
this._host._crashRetryAttempts.delete(this.id);
if (this.config.get("factorio.enable_save_patching")) {
this.notifyExit();
throw new lib.ConflictError("Load scenario cannot be used with save patching enabled");
+1 -1
View File
@@ -13,7 +13,7 @@ export * from "./src/link";
export * from "./src/lua_tools";
export * from "./src/logging";
export * from "./src/permissions";
export * from "./src/loadPlugin";
export * from "./src/PluginLoader";
export * from "./src/schema";
export * from "./src/subscriptions";
+2 -2
View File
@@ -23,8 +23,8 @@ export * from "./src/logging_utils.js";
export * from "./src/lua_tools.js";
export * from "./src/permissions.js";
export * from "./src/plugin.js";
export * from "./src/plugin_loader.js";
export * from "./src/loadPlugin.js";
export * from "./src/plugin_info.js";
export * from "./src/PluginLoader.js";
export * from "./src/prometheus.js";
export * from "./src/schema.js";
export * from "./src/shared_commands.js";
+18 -4
View File
@@ -1,6 +1,6 @@
{
"name": "@clusterio/lib",
"version": "2.1.1",
"version": "2.1.2",
"description": "Shared library for Clusterio",
"homepage": "https://github.com/clusterio/clusterio#readme",
"author": "Hornwitser <github@hornwitser.no>",
@@ -31,6 +31,20 @@
},
"import": "./src/link/WebSocket.browser.ts"
},
"#zlib_sync": {
"node": {
"types": "./src/zlib_sync.node.ts",
"default": "./dist/node/src/zlib_sync.node.js"
},
"import": "./src/zlib_sync.browser.ts"
},
"#import_plugin": {
"node": {
"types": "./src/import_plugin.node.ts",
"default": "./dist/node/src/import_plugin.node.js"
},
"import": "./src/import_plugin.browser.ts"
},
"#is_deep_strict_equal": {
"node": {
"types": "./src/is_deep_strict_equal.node.ts",
@@ -51,11 +65,9 @@
"dependencies": {
"@sinclair/typebox": "catalog:",
"@types/yauzl": "catalog:",
"@types/yazl": "catalog:",
"ajv": "^8.20.0",
"chalk": "catalog:",
"fast-deep-equal": "^3.1.3",
"fflate": "catalog:",
"set-blocking": "catalog:",
"triple-beam": "^1.4.1",
"winston": "catalog:",
@@ -71,6 +83,8 @@
"@types/triple-beam": "^1.3.5",
"@types/ws": "catalog:",
"@types/yargs": "catalog:",
"@types/yauzl": "catalog:",
"@types/yazl": "catalog:",
"typescript": "catalog:"
}
}
+39 -1
View File
@@ -4,6 +4,8 @@ import events from "events";
import { Static } from "@sinclair/typebox";
import { logger } from "./logging.js";
import { downloadFile, atomicOverwriteFile } from "./file_ops.js";
import { hashFile } from "./hash.js";
import { ZipArchive, findRoot } from "./zip_ops.js";
import { ModPortalReleaseSchema, ModPortalDetailsSchema, ModNameVersionPair } from "./data/messages_mod.js";
import { ModInfo, ModPack, MajorMinorVersion, ModVersionEquality, SourceVersion } from "./data/index.js";
@@ -54,8 +56,44 @@ export default class ModStore extends events.EventEmitter<ModStoreEvents> {
mods() { return this.files.values(); }
/**
* Read the info.json of a mod zip file along with its size, mtime and hash
*
* @param modPath - Path to the mod zip file.
* @returns Mod info for the file.
*/
static async readModInfo(modPath: string) {
let modInfo: Static<typeof ModInfo.jsonSchema>;
let zip = await ZipArchive.fromFile(modPath);
try {
let content = await zip.readFile(path.posix.join(findRoot(zip), "info.json"));
if (content === null) {
throw new Error("Mod contains no info.json file");
}
modInfo = JSON.parse(content.toString("utf8"));
} finally {
zip.close();
}
let valid = ModInfo.validateInfo(modInfo);
if (!valid) {
throw new Error("Mod's info.json is not valid");
}
const stat = await fs.stat(modPath);
return ModInfo.fromJSON({
...modInfo,
size: stat.size,
sha1: await hashFile(modPath),
mtime_ms: stat.mtimeMs,
updated_at_ms: stat.mtimeMs,
is_deleted: false,
});
}
static async loadFile(modsDirectory: string, file: string) {
let modInfo = await ModInfo.fromModFile(path.join(modsDirectory, file));
let modInfo = await ModStore.readModInfo(path.join(modsDirectory, file));
if (modInfo.filename !== file) {
throw new Error(`filename does not match the expected name ${modInfo.filename}.`);
}
+264
View File
@@ -0,0 +1,264 @@
// Shared by node and the web interface, node specifics go in #import_plugin
import importPlugin from "#import_plugin";
import { Config } from "./config/classes.js";
import { ControllerConfig, HostConfig, InstanceConfig } from "./config/definitions.js";
import Role from "./data/Role.js";
import { PluginError } from "./errors.js";
import { logger, type Logger } from "./logging.js";
import type {
MigrationHooks, PluginClass, PluginDeclaration, PluginLoadContext, PluginNodeEnvInfo, PluginRegistry, PluginType,
} from "./plugin.js";
type Waiter = {
resolve: (api: unknown) => void,
timeout: ReturnType<typeof setTimeout>,
waiter: string,
};
export type PluginLoadOptions<Context extends object, Info extends PluginDeclaration> = {
/** Entrypoint to load, e.g. controller loads controllerEntrypoint */
type: PluginType,
/** Context passed to each plugin, plugin, logger and plugins are added per plugin */
context: Context | ((pluginInfo: Info) => Context),
/** Logger for warnings, plugins get a child of it */
logger: Logger,
/** All installed plugins, used by checkInstalled */
installed: Info[],
/** Plugins to load, used by checkEnabled */
load: Info[],
/** Name of the deprecated class export, class exports are not accepted if unset */
exportName?: string,
baseClass?: PluginClass<any, any>,
/** Return failed plugins instead of throwing the first error */
continueOnError?: boolean,
};
export type PluginLoadResult<Info> = {
/** What each loaded plugin's entrypoint returned, in load order */
loaded: Map<Info, unknown>,
failed: Map<Info, Error>,
};
/**
* Loads plugins concurrently and lets them wait for each other
*
* Created for one load of plugins with {@link PluginLoader.load}.
*/
export class PluginLoader<Context extends object, Info extends PluginDeclaration> {
private _apis = new Map<string, unknown>();
private _waiters = new Map<string, Waiter[]>();
private _installed: Set<string>;
private _enabled: Set<string>;
/** Plugins still loading */
private _pending: Set<string>;
private constructor(
private _options: PluginLoadOptions<Context, Info>,
) {
this._installed = new Set(_options.installed.map(pluginInfo => pluginInfo.name));
this._enabled = new Set(_options.load.map(pluginInfo => pluginInfo.name));
this._pending = new Set(this._enabled);
}
/**
* Load plugins concurrently
*
* Waits for all plugins to settle, then throws the error of the first
* plugin in the list that failed unless continueOnError is set.
* Errors are wrapped in PluginError.
*
* @param options - What to load and how.
* @returns Loaded and failed plugins.
*/
static async load<Context extends object, Info extends PluginDeclaration>(
options: PluginLoadOptions<Context, Info>
): Promise<PluginLoadResult<Info>> {
return await new PluginLoader(options)._load();
}
private async _load() {
const results = await Promise.allSettled(this._options.load.map(async pluginInfo => {
const startedMs = Date.now();
try {
const api = await this._loadPlugin(pluginInfo);
if (this._options.type !== "migration" && pluginInfo[`${this._options.type}Entrypoint`]) {
this._options.logger.info(`Loaded plugin ${pluginInfo.name} in ${Date.now() - startedMs}ms`);
}
this._settle(pluginInfo.name, true, api);
return api;
} catch (err) {
this._settle(pluginInfo.name, false);
throw err;
}
}));
const loaded = new Map<Info, unknown>();
const failed = new Map<Info, Error>();
for (const [index, result] of results.entries()) {
const pluginInfo = this._options.load[index];
if (result.status === "fulfilled") {
loaded.set(pluginInfo, result.value);
} else {
failed.set(pluginInfo, result.reason);
}
}
if (failed.size && !this._options.continueOnError) {
throw failed.values().next().value;
}
return { loaded, failed };
}
private async _loadPlugin(pluginInfo: Info) {
const { type, exportName, baseClass } = this._options;
const entrypoint = pluginInfo[`${type}Entrypoint`];
if (!entrypoint) {
return undefined;
}
const options = this._options;
const context = typeof options.context === "function" ? options.context(pluginInfo) : options.context;
const pluginContext: PluginLoadContext<Context, Info> = {
...context,
plugin: pluginInfo,
logger: options.logger.child({ plugin: pluginInfo.name }),
plugins: this._registry(pluginInfo.name),
};
try {
const module = await importPlugin(pluginInfo, entrypoint);
if (typeof module.default === "function") {
return await module.default(pluginContext) as unknown;
}
// migrate: accept plugins which export classes
if (exportName && baseClass && module[exportName]) {
pluginContext.logger.warn(`Plugin ${pluginInfo.name} is using deprecated class export`);
return await loadPluginClass(pluginInfo, pluginContext, module[exportName], exportName, baseClass);
}
throw new Error(exportName
? `Plugin ${pluginInfo.name} must export either a default function or ${exportName} class`
: `Expected ${type} plugin ${pluginInfo.name} to export a default function`
);
} catch (err: any) {
if (err.code === "InstallationError") {
throw err;
}
throw new PluginError(pluginInfo.name, err);
}
}
private _registry(waiter: string): PluginRegistry {
return {
waitFor: (name, timeoutMs) => this._waitFor(waiter, name, timeoutMs),
checkInstalled: name => this._installed.has(name),
checkEnabled: name => this._enabled.has(name),
};
}
private _settle(name: string, loaded: boolean, api?: unknown) {
this._pending.delete(name);
if (loaded) {
this._apis.set(name, api);
}
for (const entry of this._waiters.get(name) ?? []) {
clearTimeout(entry.timeout);
if (!loaded) {
this._warnNotLoaded(entry.waiter, name);
}
entry.resolve(api);
}
this._waiters.delete(name);
}
private _waitFor<T>(waiter: string, name: string, timeoutMs = 30_000): Promise<T | undefined> {
if (this._apis.has(name)) {
return Promise.resolve(this._apis.get(name) as T);
}
if (!this._pending.has(name)) {
this._warnNotLoaded(waiter, name);
return Promise.resolve(undefined);
}
return new Promise(resolve => {
const entry: Waiter = {
resolve: resolve as (api: unknown) => void,
waiter,
timeout: setTimeout(() => {
const entries = this._waiters.get(name)!;
entries.splice(entries.indexOf(entry), 1);
this._options.logger.warn(
`Plugin ${waiter} timed out after ${timeoutMs}ms waiting for plugin ${name}`
);
resolve(undefined);
}, timeoutMs),
};
let entries = this._waiters.get(name);
if (!entries) {
entries = [];
this._waiters.set(name, entries);
}
entries.push(entry);
});
}
private _warnNotLoaded(waiter: string, name: string) {
this._options.logger.warn(`Plugin ${waiter} waited for plugin ${name} which is not loaded`);
}
}
async function loadPluginClass(
pluginInfo: PluginDeclaration,
context: PluginLoadContext<object, any>,
pluginClass: unknown,
exportName: string,
baseClass: PluginClass<any, any>,
) {
if (typeof pluginClass !== "function") {
throw new Error(`Expected plugin ${pluginInfo.name} to export a class named ${exportName}`);
}
if (!(pluginClass.prototype instanceof baseClass)) {
throw new Error(`Expected ${exportName} exported from ${pluginInfo.name} to extend ${baseClass.name}`);
}
const plugin = (pluginClass as PluginClass<any, any>).fromContext(context);
try {
await plugin.init();
} catch (err) {
plugin.detachHooks();
throw err;
}
return plugin;
}
/**
* Load the migration entrypoints of plugins
*
* Must be called before configs and roles are loaded for the migrations
* to run on them. Loaded for every plugin, including those disabled with
* load_plugin. Also registers the plugin versions written to each config
* after the migrations run.
*
* @param pluginInfos - Plugins to load migrations for.
*/
export async function loadPluginMigrations(pluginInfos: PluginNodeEnvInfo[]) {
const hooks: MigrationHooks = {
controllerConfig: ControllerConfig.pluginMigrations,
hostConfig: HostConfig.pluginMigrations,
instanceConfig: InstanceConfig.pluginMigrations,
role: Role.pluginMigrations,
};
for (const pluginInfo of pluginInfos) {
Config.pluginVersions.set(pluginInfo.name, pluginInfo.version);
}
await PluginLoader.load({
type: "migration",
context: { hooks },
logger,
installed: pluginInfos,
load: pluginInfos,
});
}
+32 -5
View File
@@ -19,6 +19,7 @@ export interface ControllerConfigFields {
"controller.bind_address": string | null;
"controller.trusted_proxies": string | null;
"controller.public_url": string | null;
"controller.favicon_url": string | null;
"controller.static_url": string | null;
"controller.grafana_url": string | null;
"controller.tls_certificate": string | null;
@@ -31,7 +32,7 @@ export interface ControllerConfigFields {
"controller.max_subscription_filters": number;
"controller.system_metrics_interval": number;
"controller.proxy_stream_timeout": number;
"controller.transfer_min_progress": number;
"controller.transfer_min_speed": number;
"controller.factorio_username": string | null;
"controller.factorio_token": string | null;
"controller.share_factorio_credentials_with_hosts": boolean;
@@ -63,6 +64,14 @@ export class ControllerConfig extends classes.Config<ControllerConfigFields> {
config["controller.public_url"] = config["controller.external_address"];
delete config["controller.external_address"];
}
if (config.hasOwnProperty("controller.transfer_min_progress")) {
// Was KiB per 30 s, the old default is left out so the new one applies
const kib = config["controller.transfer_min_progress"];
if (kib !== 30) {
config["controller.transfer_min_speed"] = typeof kib === "number" ? kib / 30 : kib;
}
delete config["controller.transfer_min_progress"];
}
return config;
}
@@ -169,6 +178,12 @@ export class ControllerConfig extends classes.Config<ControllerConfigFields> {
optional: true,
// TODO extendedValidation, valid url including the protocol
},
"controller.favicon_url": {
title: "Favicon URL",
description: "URL of the icon shown in the browser tab, defaults to the Clusterio logo.",
type: "string",
optional: true,
},
"controller.static_url": {
title: "Static URL",
description: "Override the URL to where static assets are hosted (must have a path consisting of /static/)",
@@ -224,11 +239,11 @@ export class ControllerConfig extends classes.Config<ControllerConfigFields> {
initialValue: 15,
validator: validators.greaterThanZero,
},
"controller.transfer_min_progress": {
title: "Transfer Minimum Progress",
description: "KiB an upload or download has to move every 30 seconds to not be closed, 0 for no limit.",
"controller.transfer_min_speed": {
title: "Transfer Minimum Speed",
description: "KiB/s at which an upload or download is never closed for moving too slowly, 0 for no limit.",
type: "number",
initialValue: 30,
initialValue: 64,
validator: validators.greaterThanEqualZero,
},
"controller.session_timeout": {
@@ -512,6 +527,8 @@ export interface InstanceConfigFields {
"instance.assigned_host": number | null;
"instance.auto_start": boolean;
"instance.exclude_from_start_all": boolean;
"instance.restart_after_crash": boolean;
"instance.crash_retry_attempts": number;
"instance.is_template": boolean;
"instance.template_id": number | null;
"instance.inherited_fields": Record<string, true | string[]>;
@@ -625,6 +642,16 @@ export class InstanceConfig extends classes.Config<InstanceConfigFields> {
type: "boolean",
initialValue: false,
},
"instance.restart_after_crash": {
description: "Start this instance again if it crashes after running for at least 10 minutes",
type: "boolean",
initialValue: false,
},
"instance.crash_retry_attempts": {
description: "Restarts after a crash before giving up, 0 for no limit. Reset when the instance is started",
type: "number",
initialValue: 3,
},
"instance.is_template": {
description:
"Mark this instance as a template other instances can inherit config from. " +
-34
View File
@@ -1,10 +1,6 @@
import fs from "node:fs/promises";
import path from "path";
import { Type, Static } from "@sinclair/typebox";
import * as libHash from "../hash.js";
import * as libSchema from "../schema.js";
import { ZipArchive, findRoot } from "../zip_ops.js";
import { ModRecord } from "./ModPack.js";
import {
@@ -349,34 +345,4 @@ export default class ModInfo {
if (this.isDeleted) { json.is_deleted = this.isDeleted; }
return json;
}
static async fromModFile(modPath: string) {
let modInfo: Static<typeof ModInfo.jsonSchema>;
let zip = await ZipArchive.fromFile(modPath);
try {
let content = await zip.readFile(path.posix.join(findRoot(zip), "info.json"));
if (content === null) {
throw new Error("Mod contains no info.json file");
}
modInfo = JSON.parse(content.toString("utf8"));
} finally {
zip.close();
}
let valid = this.validateInfo(modInfo);
if (!valid) {
throw new Error("Mod's info.json is not valid");
}
const stat = await fs.stat(modPath);
return this.fromJSON({
...modInfo,
size: stat.size,
sha1: await libHash.hashFile(modPath),
mtime_ms: stat.mtimeMs,
updated_at_ms: stat.mtimeMs,
is_deleted: false,
});
}
}
+2 -2
View File
@@ -1,4 +1,4 @@
import zlib from "zlib";
import * as zlib from "#zlib_sync";
import { Type, Static } from "@sinclair/typebox";
import * as libSchema from "../schema.js";
@@ -306,7 +306,7 @@ export default class ModPack {
// eslint-disable-next-line node/no-sync
let buf = zlib.deflateSync(JSON.stringify(json));
return buf.toString("base64");
return Buffer.from(buf).toString("base64");
}
static fromModPackString(modPackString: string) {
+1 -1
View File
@@ -1,4 +1,4 @@
import zlib from "zlib";
import * as zlib from "#zlib_sync";
class MapReaderState {
pos = 0;
+2 -2
View File
@@ -2,7 +2,6 @@
* @module lib/file_ops
*/
import crypto from "crypto";
import events from "events";
import fs from "node:fs/promises";
import path from "path";
import stream from "stream";
@@ -258,7 +257,8 @@ export async function createTempWriteStream(filePath: string) {
async function discardPartialDownload(writeStream: stream.Writable, tempFilePath: string) {
if (!writeStream.closed) {
writeStream.destroy();
await events.once(writeStream, "close");
// Not events.once, it rejects if the stream is still erroring from the aborted pipe.
await new Promise(resolve => writeStream.once("close", resolve));
}
try {
await fs.unlink(tempFilePath);
@@ -0,0 +1,7 @@
import type { PluginDeclaration, PluginWebEnvInfo } from "./plugin";
export default async function importPlugin(
pluginInfo: PluginDeclaration, entrypoint: string
): Promise<Record<string, any>> {
return await (pluginInfo as PluginWebEnvInfo).container.get(entrypoint);
}
+10
View File
@@ -0,0 +1,10 @@
import path from "node:path";
import { pathToFileURL } from "node:url";
import type { PluginDeclaration, PluginNodeEnvInfo } from "./plugin.js";
export default async function importPlugin(
pluginInfo: PluginDeclaration, entrypoint: string
): Promise<Record<string, any>> {
const packagePath = (pluginInfo as PluginNodeEnvInfo).packagePath;
return await import(pathToFileURL(path.join(path.dirname(packagePath), entrypoint)).href);
}
+6
View File
@@ -0,0 +1,6 @@
/** Throws if condition is falsy, node:assert is not available in the browser. */
export function assert(condition: unknown): asserts condition {
if (!condition) {
throw new Error("Assertion failed");
}
}
+1 -1
View File
@@ -1,5 +1,4 @@
// Connection adapters for Links
import { strict as assert } from "assert";
import events from "events";
import { WebSocket } from "#WebSocket";
@@ -7,6 +6,7 @@ import * as libData from "../data/index.js";
import * as libErrors from "../errors.js";
import { logger } from "../logging.js";
import ExponentialBackoff from "../ExponentialBackoff.js";
import { assert } from "./assert.js";
import type { Request, Event } from "./link.js";
/**
+1 -1
View File
@@ -5,7 +5,7 @@ import { logger } from "../logging.js";
import * as libSchema from "../schema.js";
import { dataClasses, errorClasses } from "./messages.js";
import { BaseConnector, WebSocketBaseConnector } from "./connectors.js";
import { strict as assert } from "assert";
import { assert } from "./assert.js";
import type { PluginNodeEnvInfo, PluginWebEnvInfo } from "../plugin.js";
import type {
AddressType, JSONDeserialisable, MessageRoutable, MessageRequest, MessageEvent, IUser,
-54
View File
@@ -1,54 +0,0 @@
// Contained in its own file to allow use within web build
import type { PluginDeclaration, PluginType, PluginLoadContext, PluginClass } from "./plugin.js";
export async function loadPluginEntrypoint<
Context extends object,
Info extends PluginDeclaration
>(
pluginInfo: Info,
pluginType: PluginType,
context: PluginLoadContext<Context, Info>,
module: Record<string, unknown>
) {
const init = module.default;
if (typeof init !== "function") {
throw new Error(`Expected ${pluginType} plugin ${pluginInfo.name} to export a default function`);
}
await init(context);
}
export async function loadPluginClass<
Context extends object,
Class extends PluginClass<Context, Info>,
Info extends PluginDeclaration
>(
pluginInfo: Info,
pluginType: PluginType,
context: PluginLoadContext<Context, Info>,
module: Record<string, unknown>,
exportName: string,
baseClass: Class
) {
const pluginClass = module[exportName];
if (typeof pluginClass !== "function") {
throw new Error(`Expected ${pluginType} plugin ${pluginInfo.name} to export a class named ${exportName}`);
}
if (!(pluginClass.prototype instanceof baseClass)) {
throw new Error(`Expected ${exportName} exported from ${pluginInfo.name} to extend ${baseClass.name}`);
}
const plugin = (pluginClass as Class).fromContext(context);
try {
await plugin.init();
} catch (err) {
plugin.detachHooks();
throw err;
}
return plugin as InstanceType<Class>;
}
+61 -12
View File
@@ -5,14 +5,14 @@
* @module lib/logging_utils
*/
import fs from "node:fs/promises";
import type { ReadStream } from "node:fs";
import { type ReadStream, type WriteStream, createWriteStream, mkdirSync } from "node:fs";
import os from "node:os";
import path from "path";
import stream from "stream";
import util from "util";
import util, { styleText } from "util";
import winston from "winston";
import Transport from "winston-transport";
import { LEVEL, MESSAGE } from "triple-beam";
import chalk from "chalk";
import * as libData from "./data/index.js";
import * as libErrors from "./errors.js";
@@ -108,30 +108,30 @@ export type ParsedFactorioOutput =
function formatServerOutput(parsed: ParsedFactorioOutput) {
let time = "";
if (parsed.format === "seconds") {
time = `${chalk.yellow(parsed.time.padStart(8))} `;
time = `${styleText("yellow", parsed.time.padStart(8))} `;
} else if (parsed.format === "date") {
time = `${chalk.yellow(parsed.time)} `;
time = `${styleText("yellow", parsed.time)} `;
}
let info = "";
if (parsed.type === "log") {
let level = parsed.level;
if (level === "Script") {
level = chalk.bold.greenBright(level);
level = styleText(["bold", "greenBright"], level);
} else if (level === "Verbose") {
level = chalk.bold.gray(level);
level = styleText(["bold", "gray"], level);
} else if (level === "Info") {
level = chalk.bold.blueBright(level);
level = styleText(["bold", "blueBright"], level);
} else if (parsed.level === "Warning") {
level = chalk.bold.yellowBright(level);
level = styleText(["bold", "yellowBright"], level);
} else if (parsed.level === "Error") {
level = chalk.bold.redBright(level);
level = styleText(["bold", "redBright"], level);
}
info = `${level} ${chalk.gray(parsed.file)}: `;
info = `${level} ${styleText("gray", parsed.file)}: `;
} else if (parsed.type === "action") {
info = `[${chalk.yellow(parsed.action)}] `;
info = `[${styleText("yellow", parsed.action)}] `;
}
return time + info + parsed.message;
@@ -226,6 +226,55 @@ export class LinkTransport extends Transport {
}
}
/**
* Writes log entries as lines to dirname/prefix-YYYY-MM-DD.log, opening
* a new file when the UTC date changes.
*/
export class DailyFileTransport extends Transport {
dirname: string;
prefix: string;
now: () => number;
date?: string;
stream?: WriteStream;
constructor(
options: Transport.TransportStreamOptions & {
dirname: string,
prefix: string,
now?: () => number,
}
) {
super(options);
this.dirname = options.dirname;
this.prefix = options.prefix;
this.now = options.now ?? Date.now;
// eslint-disable-next-line node/no-sync
mkdirSync(this.dirname, { recursive: true });
}
log(info: any, callback: () => void) {
const date = new Date(this.now()).toISOString().slice(0, 10);
if (!this.stream || date !== this.date) {
this.stream?.end();
this.date = date;
this.stream = createWriteStream(path.join(this.dirname, `${this.prefix}-${date}.log`), { flags: "a" });
this.stream.on("error", err => this.emit("error", err));
}
this.stream.write(info[MESSAGE] + os.EOL);
return callback();
}
close(callback?: () => void) {
const fileStream = this.stream;
this.stream = undefined;
if (fileStream) {
fileStream.end(callback);
} else {
callback?.();
}
}
}
const logFileGlob = /^[a-z]+-(\d{4}-\d{2}-\d{2})\.log$/;
const logIndexVersion = 2;
+19
View File
@@ -142,12 +142,31 @@ export interface PlayerEvent {
stats: PlayerStats,
}
/** Access to the other plugins loaded alongside a plugin */
export interface PluginRegistry {
/**
* Wait for another plugin to load
*
* @param name - Name of the plugin to wait for.
* @param timeoutMs - Time to wait before giving up, defaults to 30 seconds.
* @returns
* What the plugin's entrypoint returned, or undefined with a
* warning logged if it did not load.
*/
waitFor<T = unknown>(name: string, timeoutMs?: number): Promise<T | undefined>;
/** Check if a plugin is installed, it may still be disabled */
checkInstalled(name: string): boolean;
/** Check if a plugin is being loaded alongside this one */
checkEnabled(name: string): boolean;
}
export type PluginLoadContext<
Context extends object,
Info extends PluginDeclaration = PluginNodeEnvInfo
> = Context & {
logger: Logger;
plugin: Info;
plugins: PluginRegistry;
};
/** Hooks for migrating data that Clusterio stores on behalf of plugins */
@@ -1,18 +1,14 @@
/**
* Helpers for loading plugins in Node.js
* @module lib/plugin_loader
* Helpers for finding installed plugins and reading their info in Node.js
* @module lib/plugin_info
*/
import path from "path";
import fs from "node:fs/promises";
import { fileURLToPath, pathToFileURL } from "node:url";
import * as libErrors from "./errors.js";
import * as libPlugin from "./plugin.js";
import { type Logger, logger } from "./logging.js";
import { loadPluginEntrypoint, loadPluginClass } from "./loadPlugin.js";
import { Config } from "./config/classes.js";
import { ControllerConfig, HostConfig, InstanceConfig } from "./config/definitions.js";
import Role from "./data/Role.js";
import { logger } from "./logging.js";
import { PluginDetails } from "./data/messages_plugin.js";
import {
discoverNpmPluginPackages, findNonRegistryDirs, installedDependencies, readPackageJson, realDir, resolvePackagePath,
@@ -196,82 +192,3 @@ export async function listPluginDetails(
return plugins;
}
/**
* Load the migration entrypoints of plugins
*
* Must be called before configs and roles are loaded for the migrations
* to run on them. Loaded for every plugin, including those disabled with
* load_plugin. Also registers the plugin versions written to each config
* after the migrations run.
*
* @param pluginInfos - Plugins to load migrations for.
*/
export async function loadPluginMigrations(pluginInfos: libPlugin.PluginNodeEnvInfo[]) {
const hooks: libPlugin.MigrationHooks = {
controllerConfig: ControllerConfig.pluginMigrations,
hostConfig: HostConfig.pluginMigrations,
instanceConfig: InstanceConfig.pluginMigrations,
role: Role.pluginMigrations,
};
for (const pluginInfo of pluginInfos) {
Config.pluginVersions.set(pluginInfo.name, pluginInfo.version);
if (!pluginInfo.migrationEntrypoint) {
continue;
}
try {
const module = await import(pathToFileURL(
path.join(path.dirname(pluginInfo.packagePath), pluginInfo.migrationEntrypoint)
).href);
const context: libPlugin.MigrationContext = {
hooks,
plugin: pluginInfo,
logger: logger.child({ plugin: pluginInfo.name }),
};
await loadPluginEntrypoint(pluginInfo, "migration", context, module);
} catch (err: any) {
throw new libErrors.PluginError(pluginInfo.name, err);
}
}
}
export async function loadPlugin<
Context extends { logger: Logger },
Class extends libPlugin.PluginClass<Context, libPlugin.PluginNodeEnvInfo>,
> (
pluginInfo: libPlugin.PluginNodeEnvInfo,
pluginType: libPlugin.PluginType,
context: Context,
exportName: `${string}Plugin`,
baseClass: Class,
) {
const entrypoint = `${pluginType}Entrypoint` as const;
const requirePath = pluginInfo[entrypoint];
if (!requirePath) {
return;
}
const module = await import(pathToFileURL(path.join(path.dirname(pluginInfo.packagePath), requirePath)).href);
const pluginContext: libPlugin.PluginLoadContext<Context> = {
...context,
plugin: pluginInfo,
logger: context.logger.child({ plugin: pluginInfo.name }),
};
if (typeof module.default === "function") {
await loadPluginEntrypoint(pluginInfo, pluginType, pluginContext, module);
return;
}
// migrate: accept plugins which export classes
if (module[exportName]) {
pluginContext.logger.warn(`Plugin ${pluginInfo.name} is using deprecated class export`);
await loadPluginClass(pluginInfo, pluginType, pluginContext, module, exportName, baseClass);
return;
}
throw new Error(`Plugin ${pluginInfo.name} must export either a default function or ${exportName} class`);
}
+42 -10
View File
@@ -7,10 +7,31 @@ import { PassThrough, type Readable } from "stream";
import util from "util";
import zlib from "zlib";
import yauzl from "yauzl";
import type yazl from "yazl";
const deflateRaw = util.promisify(zlib.deflateRaw);
/**
* Entry in a ZipArchive
*
* Local subset of yauzl.Entry so the published declarations do not import
* yauzl, which would make @types/yauzl a runtime dependency of lib.
*/
export interface ZipEntry {
fileName: string;
fileComment: string;
versionMadeBy: number;
versionNeededToExtract: number;
generalPurposeBitFlag: number;
compressionMethod: number;
lastModFileTime: number;
lastModFileDate: number;
crc32: number;
compressedSize: number;
uncompressedSize: number;
externalFileAttributes: number;
getLastModDate(options?: { timezone?: "local" | "UTC" | null, forceDosFormat?: boolean }): Date;
}
/**
* Zip archive opened for random access reading
@@ -21,10 +42,9 @@ const deflateRaw = util.promisify(zlib.deflateRaw);
*/
export class ZipArchive {
private constructor(
/** Underlying yauzl zip file. */
public zipfile: yauzl.ZipFile,
private zipfile: yauzl.ZipFile,
/** Entries by file name in the order they appear in the central directory. */
public entries: Map<string, yauzl.Entry>,
public entries: Map<string, ZipEntry>,
) { }
/**
@@ -77,8 +97,17 @@ export class ZipArchive {
*
* @param entry - Entry to read, must belong to this archive.
*/
openStream(entry: yauzl.Entry): Promise<Readable> {
return this.zipfile.openReadStreamPromise(entry);
openStream(entry: ZipEntry): Promise<Readable> {
return this.zipfile.openReadStreamPromise(entry as yauzl.Entry);
}
/**
* Open a stream of the content of an entry as stored in the archive
*
* @param entry - Entry to read, must belong to this archive.
*/
openRawStream(entry: ZipEntry): Promise<Readable> {
return this.zipfile.openReadStreamPromise(entry as yauzl.Entry, { decodeFileData: false });
}
/**
@@ -86,7 +115,7 @@ export class ZipArchive {
*
* @param entry - Entry to read, must belong to this archive.
*/
async readEntry(entry: yauzl.Entry) {
async readEntry(entry: ZipEntry) {
const chunks: Buffer[] = [];
for await (const chunk of await this.openStream(entry)) {
chunks.push(chunk);
@@ -153,7 +182,10 @@ export function findRoot(zip: ZipArchive) {
*
* @param zipFile - zip file being written.
*/
export function zipOutputStream(zipFile: yazl.ZipFile) {
export function zipOutputStream(zipFile: {
outputStream: NodeJS.ReadableStream,
on(event: "error", listener: (err: Error) => void): unknown,
}) {
const output = zipFile.outputStream as Readable;
zipFile.on("error", err => output.destroy(err));
return output;
@@ -224,7 +256,7 @@ export class ZipWriter {
* @param zip - Archive to copy from.
* @param entry - Entry to copy, must belong to zip.
*/
async addEntry(zip: ZipArchive, entry: yauzl.Entry) {
async addEntry(zip: ZipArchive, entry: ZipEntry) {
const writerEntry: WriterEntry = {
fileName: Buffer.from(entry.fileName, "utf8"),
fileComment: Buffer.from(entry.fileComment, "utf8"),
@@ -242,7 +274,7 @@ export class ZipWriter {
offset: this.offset,
};
await this.write(this.localFileHeader(writerEntry));
const stream = await zip.zipfile.openReadStreamPromise(entry, { decodeFileData: false });
const stream = await zip.openRawStream(entry);
for await (const chunk of stream) {
await this.write(chunk);
}
+15
View File
@@ -0,0 +1,15 @@
/* eslint-disable node/no-sync */
import { strToU8, unzlibSync, zlibSync } from "fflate";
export function inflateSync(data: Uint8Array): Uint8Array {
try {
return unzlibSync(data);
} catch (err: any) {
// Match the error code node:zlib gives for invalid data.
throw Object.assign(new Error(err.message), { code: "Z_DATA_ERROR" });
}
}
export function deflateSync(data: Uint8Array | string): Uint8Array {
return zlibSync(typeof data === "string" ? strToU8(data) : data);
}
+11
View File
@@ -0,0 +1,11 @@
import zlib from "zlib";
export function inflateSync(data: Uint8Array): Uint8Array {
// eslint-disable-next-line node/no-sync
return zlib.inflateSync(data);
}
export function deflateSync(data: Uint8Array | string): Uint8Array {
// eslint-disable-next-line node/no-sync
return zlib.deflateSync(data);
}
+3 -1
View File
@@ -19,12 +19,14 @@
"./src/hash.ts",
"./src/ini.ts",
"./src/is_deep_strict_equal.browser.ts",
"./src/zlib_sync.browser.ts",
"./src/link/*.ts",
"./src/lua_tools.ts",
"./src/logging.ts",
"./src/permissions.ts",
"./src/prometheus.ts",
"./src/loadPlugin.ts",
"./src/PluginLoader.ts",
"./src/import_plugin.browser.ts",
"./src/plugin.ts",
"./src/schema.ts",
"./src/subscriptions.ts",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@clusterio/web_ui",
"version": "2.1.1",
"version": "2.1.2",
"description": "Clusterio web interface implementation",
"homepage": "https://github.com/clusterio/clusterio#readme",
"author": "Hornwitser",
+63
View File
@@ -140,6 +140,46 @@ export type ExtensionComponent<K extends PluginExtensionSlot> = React.ComponentT
export type ExtensionComponents = { [K in PluginExtensionSlot]: Map<string, ExtensionComponent<K>> };
/**
* Action added by a plugin to the actions dropdown of a page.
*/
export type PluginPageAction = {
/** Unique within the plugin, the web UI prefixes it with the plugin name. */
key: string;
label: React.ReactNode;
icon?: React.ReactNode;
disabled?: boolean;
danger?: boolean;
onClick?: () => void;
};
export type PageActionsSlotProps = {
/** Controller control button on the controller page. */
ControllerPage: Record<never, never>;
/** Host control button on each host page. */
HostViewPage: {
host: lib.HostDetails;
};
/** More dropdown on each instance and template page. */
InstanceViewPage: {
instance: lib.InstanceDetails;
};
/** More dropdown on each user page. */
UserViewPage: {
user: lib.UserDetails;
};
};
export type PageActionsSlot = keyof PageActionsSlotProps;
/**
* Returns the actions to add to a page. It is called during render like a
* React hook, so it may call hooks such as useAccount or useState.
*/
export type PageActionsHook<K extends PageActionsSlot> = (props: PageActionsSlotProps[K]) => PluginPageAction[];
export type PageActions = { [K in PageActionsSlot]: Map<string, PageActionsHook<K>> };
export type WebPluginContext = lib.PluginLoadContext<{
control: Control;
container: any;
@@ -156,6 +196,7 @@ export class WebHooks extends lib.AsyncHookCollection {
this.extensionComponents = this.newHook();
this.inputComponents = this.newHook();
this.loginForms = this.newHook();
this.pageActions = this.newHook();
this.pages = this.newHook();
}
@@ -225,6 +266,28 @@ export class WebHooks extends lib.AsyncHookCollection {
*/
readonly loginForms: lib.AsyncHook<[], PluginLoginForm[]>;
/**
* Additional actions for the actions dropdown on resource pages.
*
* Each plugin may return a partial mapping of page names to
* functions returning the actions for that page. Plugin actions are
* placed after the built in ones and before stop and delete.
*
* @example
* ```ts
* control.hooks.pageActions.attach("my_plugin", () => ({
* UserViewPage: ({ user }) => [{
* key: "warn",
* label: "Warn",
* onClick: () => control.send(new WarnUserRequest(user.name)),
* }],
* }));
* ```
*/
readonly pageActions: lib.AsyncHook<[], Partial<{
[K in PageActionsSlot]: PageActionsHook<K>;
}>>;
/**
* Additional pages accessible on the web ui.
*
+36 -39
View File
@@ -12,8 +12,10 @@ import { InputInstanceTemplate } from "./components/InputInstance";
import { InputTargetVersion, InputPartialVersion, InputFullVersion } from "./components/InputVersion";
import { Control, ControlConnector } from "./util/websocket";
import { loadedPluginSetKey } from "./util/pluginSet";
import { pageActionsFromHooks } from "./util/plugin_actions";
import * as WebPlugin from "./BaseWebPlugin";
import { pages } from "./pages";
import logo from "./images/logo.png";
const { ConsoleTransport, WebConsoleFormat, logger } = lib;
@@ -69,49 +71,36 @@ async function loadPlugins(
pluginInfos: lib.PluginWebEnvInfo[],
control: Control
) {
const plugins = new Map<string, WebPlugin.BaseWebPlugin>();
const { loaded, failed } = await lib.PluginLoader.load({
type: "web",
context: (pluginInfo: lib.PluginWebEnvInfo) => ({
control,
container: pluginInfo.container,
package: pluginInfo.package,
}),
logger,
installed: pluginInfos,
load: pluginInfos.filter(pluginInfo => pluginInfo.enabled && pluginInfo.webEntrypoint),
exportName: "WebPlugin",
baseClass: WebPlugin.BaseWebPlugin,
continueOnError: true,
});
for (const pluginInfo of pluginInfos) {
if (!pluginInfo.enabled || !pluginInfo.webEntrypoint) {
continue;
}
try {
const webModule = await pluginInfo.container.get(pluginInfo.webEntrypoint);
const pluginContext: WebPlugin.WebPluginContext = {
control,
plugin: pluginInfo,
container: pluginInfo.container,
package: pluginInfo.package,
logger: logger.child({ plugin: pluginInfo.name }),
};
if (typeof webModule.default === "function") {
await lib.loadPluginEntrypoint(pluginInfo, "web", pluginContext, webModule);
continue;
}
// migrate: accept plugins which export classes
if (webModule.WebPlugin) {
logger.warn(`Plugin ${pluginInfo.name} is using deprecated class hooks`);
plugins.set(pluginInfo.name, await lib.loadPluginClass(
pluginInfo, "web", pluginContext, webModule, "WebPlugin", WebPlugin.BaseWebPlugin
));
continue;
}
throw new Error(`Plugin ${pluginInfo.name} must export either a default function or WebPlugin`);
} catch (err: any) {
pluginInfo.error = `Error loading plugin: ${err.message}`;
logger.error(`Failed to load plugin ${pluginInfo.name}`);
if (err.stack) {
logger.error(err.stack);
}
for (const [pluginInfo, err] of failed) {
const cause = err instanceof lib.PluginError ? err.original : err;
pluginInfo.error = `Error loading plugin: ${cause.message}`;
logger.error(`Failed to load plugin ${pluginInfo.name}`);
if (cause.stack) {
logger.error(cause.stack);
}
}
const plugins = new Map<string, WebPlugin.BaseWebPlugin>();
for (const [pluginInfo, api] of loaded) {
if (api instanceof WebPlugin.BaseWebPlugin) {
plugins.set(pluginInfo.name, api);
}
}
return plugins;
}
@@ -189,6 +178,13 @@ async function pagesFromHooks(control: Control) {
}
export default async function bootstrap() {
// The controller adds a link when controller.favicon_url is set
if (!document.querySelector("link[rel=icon]")) {
const icon = document.createElement("link");
icon.rel = "icon";
icon.href = logo;
document.head.appendChild(icon);
}
logger.add(new ConsoleTransport({
level: "verbose",
format: new WebConsoleFormat(),
@@ -209,6 +205,7 @@ export default async function bootstrap() {
control.inputComponents = await inputComponentsFromHooks(control);
control.extensionComponents = await extensionComponentsFromHooks(control);
control.pageActions = await pageActionsFromHooks(control.hooks);
control.loginForms = await loginFormsFromHooks(control);
control.pages = await pagesFromHooks(control);
@@ -1,4 +1,4 @@
import React, {useContext, useState} from "react";
import React, { useContext, useEffect, useState } from "react";
import { Descriptions, Flex, Modal, Popconfirm, Space, Tooltip, Typography } from "antd";
import { ExclamationCircleOutlined } from "@ant-design/icons";
@@ -19,6 +19,7 @@ import PageLayout from "./PageLayout";
import notify, { notifyErrorHandler } from "../util/notify";
import webUiPackage from "../../package.json";
import { hasNpmButtonPermission, NpmButton } from "./NpmButton";
import usePluginActions from "../util/usePluginActions";
import VariableDropdownButton, { VariableDropdownButtonProps } from "./VariableDropdownButton";
const { Title } = Typography;
@@ -30,6 +31,7 @@ function ControllerControlButton({ canRestart, restartRequired }: ControllerCont
const control = useContext(ControlContext);
const [modal, modalContext] = Modal.useModal();
const actions: VariableDropdownButtonProps["actions"] = [];
const pluginActions = usePluginActions("ControllerPage", {});
if (account.hasPermission("core.controller.restart") && canRestart) {
actions.push({
@@ -71,6 +73,8 @@ function ControllerControlButton({ canRestart, restartRequired }: ControllerCont
});
}
actions.push(...pluginActions);
if (account.hasPermission("core.controller.stop")) {
actions.push({
key: "stop",
@@ -104,12 +108,49 @@ function ControllerControlButton({ canRestart, restartRequired }: ControllerCont
}
function formatListen(config: lib.ControllerConfig) {
let address = config.get("controller.bind_address") || "*";
if (address.includes(":")) {
address = `[${address}]`;
}
const listen = [];
for (const protocol of ["http", "https"] as const) {
const port = config.get(`controller.${protocol}_port`);
if (port) {
listen.push(`${protocol}://${address}:${port}`);
}
}
return listen.join(", ");
}
function useControllerConfig() {
const account = useAccount();
const control = useContext(ControlContext);
const [config, setConfig] = useState<lib.ControllerConfig>();
const canConfig = account.hasPermission("core.controller.get_config");
useEffect(() => {
if (!canConfig) {
return undefined;
}
let canceled = false;
control.send(new lib.ControllerConfigGetRequest()).then(serialized => {
if (!canceled) {
setConfig(lib.ControllerConfig.fromJSON(serialized, "control"));
}
}).catch(notifyErrorHandler("Error loading controller config"));
return () => { canceled = true; };
}, [control, canConfig]);
return config;
}
export default function ControllerPage() {
const account = useAccount();
const [systems] = useSystems();
const system = systems.get("controller");
const [maxLevel, setMaxLevel] = useState<keyof typeof lib.levels>("info");
const canShowNpm = hasNpmButtonPermission(true);
const config = useControllerConfig();
return <PageLayout nav={[{ name: "Controller" }]}>
<PageHeader
@@ -134,7 +175,8 @@ export default function ControllerPage() {
<Descriptions.Item label="Process Uptime">
<MetricRelativeDate timeMs={system?.processStartedAtMs}/>
</Descriptions.Item>
<Descriptions.Item label="Hostname" span={2}>{system?.hostname}</Descriptions.Item>
<Descriptions.Item label="Hostname" span={config ? 1 : 2}>{system?.hostname}</Descriptions.Item>
{config && <Descriptions.Item label="Bind Address">{formatListen(config)}</Descriptions.Item>}
<Descriptions.Item label="CPU Model" span={2}>{system?.cpuModel}</Descriptions.Item>
<Descriptions.Item label="CPU Usage"><MetricCpuRatio system={system} /></Descriptions.Item>
<Descriptions.Item label="Cores"><MetricCpuUsed system={system} /></Descriptions.Item>
@@ -142,6 +184,9 @@ export default function ControllerPage() {
<Descriptions.Item label="Memory"><MetricMemoryUsed system={system} /></Descriptions.Item>
<Descriptions.Item label="Disk Usage"><MetricDiskRatio system={system} /></Descriptions.Item>
<Descriptions.Item label="Disk"><MetricDiskUsed system={system} /></Descriptions.Item>
{config && <Descriptions.Item label="Public URL">
{config.get("controller.public_url") || <em>Not set</em>}
</Descriptions.Item>}
</Descriptions>
{account.hasPermission("core.log.follow") && <>
<Flex justify="space-between" align="baseline">
@@ -96,7 +96,7 @@ export default function CreateSaveModal(props: CreateSaveModalProps) {
setOpen(true);
}}
>
Create save
Create
</Button>
<Modal
title="Create Save"
@@ -0,0 +1,9 @@
import React from "react";
/** Label and control laid out on one line */
export default function FieldRow(props: { label: React.ReactNode, children: React.ReactNode }) {
return <div style={{ marginBottom: 16, display: "flex", alignItems: "center", gap: 12 }}>
<label style={{ width: 110, flexShrink: 0 }}>{props.label}</label>
{props.children}
</div>;
}
@@ -25,22 +25,25 @@ import {
import { useSystems } from "../model/system";
import useResourceState from "../util/useResourceState";
import { hasNpmButtonPermission, NpmButton } from "./NpmButton";
import usePluginActions from "../util/usePluginActions";
import VariableDropdownButton, { VariableDropdownButtonProps } from "./VariableDropdownButton";
const { Title } = Typography;
type HostControlButtonProps = {
hostId: number,
host: lib.HostDetails,
instances: ReadonlyMap<number, lib.InstanceDetails>,
canRestart?: boolean,
restartRequired?: boolean,
};
function HostControlButton({ hostId, instances, canRestart, restartRequired }: HostControlButtonProps) {
function HostControlButton({ host, instances, canRestart, restartRequired }: HostControlButtonProps) {
const account = useAccount();
const control = useContext(ControlContext);
const [modal, modalContext] = Modal.useModal();
const hostId = host.id;
const actions: VariableDropdownButtonProps["actions"] = [];
const pluginActions = usePluginActions("HostViewPage", { host });
if (account.hasPermission("core.host.restart") && canRestart) {
actions.push({
@@ -93,6 +96,8 @@ function HostControlButton({ hostId, instances, canRestart, restartRequired }: H
});
}
actions.push(...pluginActions);
if (account.hasPermission("core.host.stop")) {
actions.push({
key: "stop",
@@ -174,7 +179,7 @@ export default function HostViewPage() {
let hostButtons = <Space wrap>
<HostControlButton
hostId={hostId}
host={host}
instances={hostInstances}
canRestart={system?.canRestart}
restartRequired={system?.restartRequired}
@@ -11,6 +11,8 @@ import VariableDropdownButton, { VariableDropdownButtonProps } from "./VariableD
type InstanceControlButtonProps = Omit<VariableDropdownButtonProps, "actions"> & {
instance: lib.InstanceDetails;
onFinish?: () => void;
/** Added to the dropdown before Kill */
extraActions?: VariableDropdownButtonProps["actions"];
};
export const InstanceControlButtonPermissions = [
@@ -23,8 +25,9 @@ export default function InstanceControlButton(props: InstanceControlButtonProps)
const [switching, setSwitching] = useState<boolean>(false);
const [popconfirm, setPopconfirm] = useState<string | null>(null);
const instanceId = props.instance.id;
const instanceStatus = props.instance.status;
const { instance, onFinish, extraActions, ...buttonProps } = props;
const instanceId = instance.id;
const instanceStatus = instance.status;
// While starting or stopping the button shows the action in progress as loading.
const showStart = ["stopped", "starting"].includes(instanceStatus);
const showStop = ["running", "stopping"].includes(instanceStatus);
@@ -32,8 +35,8 @@ export default function InstanceControlButton(props: InstanceControlButtonProps)
function actionFinish() {
setSwitching(false);
if (props.onFinish) {
props.onFinish();
if (onFinish) {
onFinish();
}
}
@@ -88,6 +91,8 @@ export default function InstanceControlButton(props: InstanceControlButtonProps)
});
}
actions.push(...extraActions ?? []);
if (account.hasPermission("core.instance.kill")) {
actions.push({
key: "kill",
@@ -100,7 +105,7 @@ export default function InstanceControlButton(props: InstanceControlButtonProps)
return <div style={{ position: "relative", display: "inline-block" }}>
<VariableDropdownButton
{...props}
{...buttonProps}
type="primary"
actions={actions}
loading={switching || transitioning}
@@ -27,7 +27,7 @@ import SavesList from "./SavesList";
import OnlinePlayersList from "./OnlinePlayersList";
import { notifyErrorHandler } from "../util/notify";
import { useInstance, useInstances } from "../model/instance";
import { CreateInstanceButton } from "./InstancesPage";
import { CreateInstanceButton, CreateInstanceModal } from "./InstancesPage";
import { useHost } from "../model/host";
import InstanceStatusTag from "./InstanceStatusTag";
import Link from "./Link";
@@ -36,6 +36,7 @@ import { useDefaultModPack, useModPacks } from "../model/mod_pack";
import InstanceModPack from "./InstanceModPack";
import useLocalStorage from "../util/useLocalStorage";
import useResourceState from "../util/useResourceState";
import usePluginActions from "../util/usePluginActions";
import { MetricRelativeDate } from "./system_metrics";
type MenuItem = Required<MenuProps>["items"][number];
@@ -145,13 +146,18 @@ function InstanceButtons(props: { instance: lib.InstanceDetails }) {
let control = useContext(ControlContext);
let navigate = useNavigate();
let [exportingData, setExportingData] = useState(false);
const [modal, setModal] = useState<"scenario" | "template">();
let instance = props.instance;
let instanceId = instance.id!;
let [host] = useHost(instance.assignedHost);
const [instances] = useInstances();
const canCreate = account.hasPermission("core.instance.create");
const pluginActions = usePluginActions("InstanceViewPage", { instance });
let instanceButtonMenuItems: MenuItem[] = [];
if (canCreate) {
instanceButtonMenuItems.push({ key: "template", label: "Create template" });
}
if (account.hasPermission("core.instance.export_data")) {
instanceButtonMenuItems.push({
disabled: exportingData || instance.status !== "stopped",
@@ -166,6 +172,7 @@ function InstanceButtons(props: { instance: lib.InstanceDetails }) {
label: "Extract players from save",
});
}
instanceButtonMenuItems.push(...pluginActions);
if (account.hasPermission("core.instance.delete")) {
if (instanceButtonMenuItems.length) {
instanceButtonMenuItems.push({ type: "divider" });
@@ -196,7 +203,9 @@ function InstanceButtons(props: { instance: lib.InstanceDetails }) {
let instanceButtonsMenuProps: MenuProps = {
items: instanceButtonMenuItems,
onClick: ({ key }: { key: string }) => {
if (key === "export") {
if (key === "template") {
setModal("template");
} else if (key === "export") {
setExportingData(true);
control.sendTo(
{ instanceId },
@@ -230,13 +239,26 @@ function InstanceButtons(props: { instance: lib.InstanceDetails }) {
icon={<DeleteOutlined />}
onClick={confirmDelete}
>Delete</Button>}
{pluginActions.length > 0
&& <Dropdown placement="bottomRight" trigger={["click"]} menu={{ items: pluginActions }}>
<Button>More <DownOutlined /></Button>
</Dropdown>}
</Space>;
}
const canLoadScenario = account.hasPermission("core.instance.load_scenario");
return <Space wrap>
{
account.hasAnyPermission(...InstanceControlButtonPermissions)
&& <InstanceControlButton instance={instance} />
account.hasAnyPermission(...InstanceControlButtonPermissions, "core.instance.load_scenario")
&& <InstanceControlButton
instance={instance}
extraActions={canLoadScenario ? [{
key: "scenario",
label: "Load scenario",
disabled: instance.status !== "stopped",
onClick: () => setModal("scenario"),
}] : []}
/>
}
<Button
onClick={() => {
@@ -249,21 +271,21 @@ function InstanceButtons(props: { instance: lib.InstanceDetails }) {
>
Connect via Steam
</Button>
{account.hasPermission("core.instance.load_scenario") && <LoadScenarioModal instance={instance} />}
{canCreate && <CreateInstanceButton
instances={instances}
initial={{ instanceClone: instanceId, asTemplate: true, linkSource: true }}
buttonText="Create template"
buttonType="default"
/>}
{account.hasAnyPermission(
"core.instance.export_data",
"core.instance.extract_players",
"core.instance.delete",
)
{instanceButtonMenuItems.length > 0
&& <Dropdown placement="bottomRight" trigger={["click"]} menu={instanceButtonsMenuProps}>
<Button>More <DownOutlined /></Button>
</Dropdown>}
{canLoadScenario && <LoadScenarioModal
instance={instance}
open={modal === "scenario"}
onClose={() => setModal(undefined)}
/>}
{canCreate && <CreateInstanceModal
instances={instances}
initial={{ instanceClone: instanceId, asTemplate: true, linkSource: true }}
open={modal === "template"}
onClose={() => setModal(undefined)}
/>}
</Space>;
}
@@ -97,10 +97,28 @@ export function CreateInstanceButton({ buttonText = "Create", buttonType = "prim
buttonType?: "primary" | "default";
buttonSize?: "small";
}) {
const [open, setOpen] = useState(false);
return <>
<Button type={buttonType} size={props.buttonSize} onClick={() => setOpen(true)}>{buttonText}</Button>
<CreateInstanceModal
instances={props.instances}
initial={props.initial}
open={open}
onClose={() => setOpen(false)}
/>
</>;
}
export function CreateInstanceModal(props: {
instances: ReturnType<typeof useInstances>[0];
initial?: CreateInstanceInitial;
open: boolean;
onClose: () => void;
}) {
const { open } = props;
let control = useContext(ControlContext);
let account = useAccount();
let navigate = useNavigate();
let [open, setOpen] = useState(false);
let [creating, setCreating] = useState(false);
let [form] = Form.useForm();
let [hosts] = useHosts();
@@ -190,100 +208,91 @@ export function CreateInstanceButton({ buttonText = "Create", buttonType = "prim
} finally {
setCreating(false);
if (created) {
setOpen(false);
props.onClose();
navigate(`/instances/${instanceId}/view`);
}
}
}
return <>
<Button
type={buttonType}
size={props.buttonSize}
onClick={() => {
setOpen(true);
return <Modal
title={asTemplate ? "Create Template" : "Create Instance"}
okText="Create"
open={open}
confirmLoading={creating}
onOk={() => { createInstance().catch(notifyErrorHandler("Error creating instance")); }}
onCancel={props.onClose}
destroyOnHidden
>
<Form
form={form}
initialValues={{
host: "null", instanceClone: -1, saveMode: "none", startAfter: false,
template: null, asTemplate: false, linkSource: true, ...props.initial,
}}
>{buttonText}</Button>
<Modal
title={asTemplate ? "Create Template" : "Create Instance"}
okText="Create"
open={open}
confirmLoading={creating}
onOk={() => { createInstance().catch(notifyErrorHandler("Error creating instance")); }}
onCancel={() => { setOpen(false); }}
destroyOnHidden
>
<Form
form={form}
initialValues={{
host: "null", instanceClone: -1, saveMode: "none", startAfter: false,
template: null, asTemplate: false, linkSource: true, ...props.initial,
}}
<Form.Item name="instanceName" label="Name">
<Input />
</Form.Item>
<Tooltip title="Templates hold shared config for other instances and cannot be started">
<Form.Item name="asTemplate" valuePropName="checked">
<Checkbox>Create as template</Checkbox>
</Form.Item>
</Tooltip>
{canAssign && !asTemplate && <Form.Item name="host" label="Host">
<Select showSearch optionFilterProp="name">
<Select.Option value={"null"}>
<Typography.Text italic>Unassigned</Typography.Text>
</Select.Option>
{[...hosts.values()].sort((a, b) => strcmp(a.name, b.name)).map(h => <Select.Option
key={h.id}
value={h.id}
name={h.name}
disabled={!h.connected}
>
{h.name}
{!h.connected && " (offline)"}
</Select.Option>)}
</Select>
</Form.Item>}
<ConfigSourceFields
instances={props.instances}
templateId={templateId}
source={source}
asTemplate={asTemplate}
/>
{copySettings && <Tooltip
title="Name of the server as shown in the in-game server browser"
>
<Form.Item name="instanceName" label="Name">
<Form.Item name="serverName" label="Server Name">
<Input />
</Form.Item>
<Tooltip title="Templates hold shared config for other instances and cannot be started">
<Form.Item name="asTemplate" valuePropName="checked">
<Checkbox>Create as template</Checkbox>
</Form.Item>
</Tooltip>
{canAssign && !asTemplate && <Form.Item name="host" label="Host">
<Select showSearch optionFilterProp="name">
<Select.Option value={"null"}>
<Typography.Text italic>Unassigned</Typography.Text>
</Select.Option>
{[...hosts.values()].sort((a, b) => strcmp(a.name, b.name)).map(h => <Select.Option
key={h.id}
value={h.id}
name={h.name}
disabled={!h.connected}
>
{h.name}
{!h.connected && " (offline)"}
</Select.Option>)}
</Select>
</Form.Item>}
<ConfigSourceFields
instances={props.instances}
templateId={templateId}
source={source}
asTemplate={asTemplate}
</Tooltip>}
{source && hostId !== undefined && <Form.Item name="saveMode" label="Copy Save">
<Select
options={[
{ value: "none", label: "None" },
{
value: "copy",
label: activeSave ? `Copy ${activeSave.name}` : "Copy active save",
disabled: !activeSave,
},
{
value: "save_and_copy",
label: "Save the running game and copy it",
disabled: !sourceRunning || !activeSave,
},
]}
/>
{copySettings && <Tooltip
title="Name of the server as shown in the in-game server browser"
>
<Form.Item name="serverName" label="Server Name">
<Input />
</Form.Item>
</Tooltip>}
{source && hostId !== undefined && <Form.Item name="saveMode" label="Copy Save">
<Select
options={[
{ value: "none", label: "None" },
{
value: "copy",
label: activeSave ? `Copy ${activeSave.name}` : "Copy active save",
disabled: !activeSave,
},
{
value: "save_and_copy",
label: "Save the running game and copy it",
disabled: !sourceRunning || !activeSave,
},
]}
/>
</Form.Item>}
{hostId !== undefined && <Form.Item
name="startAfter"
valuePropName="checked"
extra={saveMode === "none" ? "A new save is created if none is copied" : undefined}
>
<Checkbox>Start after creation</Checkbox>
</Form.Item>}
</Form>
</Modal>
</>;
</Form.Item>}
{hostId !== undefined && <Form.Item
name="startAfter"
valuePropName="checked"
extra={saveMode === "none" ? "A new save is created if none is copied" : undefined}
>
<Checkbox>Start after creation</Checkbox>
</Form.Item>}
</Form>
</Modal>;
}
function TemplateList(props: { instances: ReturnType<typeof useInstances>[0] }) {
@@ -8,9 +8,10 @@ import { notifyErrorHandler } from "../util/notify";
type LoadScenarioModalProps = {
instance: lib.InstanceDetails;
open: boolean;
onClose: () => void;
};
export default function LoadScenarioModal(props: LoadScenarioModalProps) {
let [open, setOpen] = useState(false);
let [loadingScenario, setLoadingScenario] = useState(false);
let [form] = Form.useForm();
let control = useContext(ControlContext);
@@ -57,7 +58,7 @@ export default function LoadScenarioModal(props: LoadScenarioModalProps) {
{ instanceId: props.instance.id },
new lib.InstanceLoadScenarioRequest(scenario, seed, mapGenSettings, mapSettings),
).then(() => {
setOpen(false);
props.onClose();
}).catch(
notifyErrorHandler("Error loading scenario")
).finally(() => {
@@ -81,58 +82,43 @@ export default function LoadScenarioModal(props: LoadScenarioModalProps) {
});
}
function handleCancel() {
setOpen(false);
}
return <>
<Button
loading={loadingScenario}
disabled={props.instance.status !== "stopped"}
onClick={() => {
setOpen(true);
}}
>
Load scenario
</Button>
<Modal
title="Load Scenario"
width={560}
okText="Load"
open={open}
confirmLoading={loadingScenario}
onOk={loadScenario}
onCancel={handleCancel}
destroyOnHidden
>
<Form form={form} layout="vertical">
<Form.Item name="scenario" label="Scenario">
<Input placeholder="base/freeplay" />
</Form.Item>
<Form.Item name="seed" label="Seed">
<Input type="number" />
</Form.Item>
<Form.Item name="exchangeString" label="Map Exchange String">
<Input.TextArea allowClear={true} autoSize={{ minRows: 3 }} />
</Form.Item>
<div style={{ textAlign: "right", marginTop: -8 }}>
<Button onClick={() => convertExchangeString()}>Convert to settings</Button>
</div>
<Form.Item
name="mapGenSettings"
label="Map Gen Settings"
tooltip="JSON data to pass to Factorio with --map-gen-settings, overrides Map Exchange String"
>
<Input.TextArea allowClear={true} autoSize={{ minRows: 1 }} />
</Form.Item>
<Form.Item
name="mapSettings"
label="Map Settings"
tooltip="JSON data to pass to Factorio with --map-settings, overrides Map Exchange String"
>
<Input.TextArea allowClear={true} autoSize={{ minRows: 1 }} />
</Form.Item>
</Form>
</Modal>
</>;
return <Modal
title="Load Scenario"
width={560}
okText="Load"
open={props.open}
confirmLoading={loadingScenario}
onOk={loadScenario}
onCancel={props.onClose}
destroyOnHidden
>
<Form form={form} layout="vertical">
<Form.Item name="scenario" label="Scenario">
<Input placeholder="base/freeplay" />
</Form.Item>
<Form.Item name="seed" label="Seed">
<Input type="number" />
</Form.Item>
<Form.Item name="exchangeString" label="Map Exchange String">
<Input.TextArea allowClear={true} autoSize={{ minRows: 3 }} />
</Form.Item>
<div style={{ textAlign: "right", marginTop: -8 }}>
<Button onClick={() => convertExchangeString()}>Convert to settings</Button>
</div>
<Form.Item
name="mapGenSettings"
label="Map Gen Settings"
tooltip="JSON data to pass to Factorio with --map-gen-settings, overrides Map Exchange String"
>
<Input.TextArea allowClear={true} autoSize={{ minRows: 1 }} />
</Form.Item>
<Form.Item
name="mapSettings"
label="Map Settings"
tooltip="JSON data to pass to Factorio with --map-settings, overrides Map Exchange String"
>
<Input.TextArea allowClear={true} autoSize={{ minRows: 1 }} />
</Form.Item>
</Form>
</Modal>;
}
+205 -106
View File
@@ -4,8 +4,9 @@ import { useNavigate, useParams } from "react-router-dom";
import {
Button, Card, ColorPicker, Checkbox, Col, ConfigProvider, Descriptions, Form, Input, Pagination,
Popconfirm, Row, Table, Tag, Typography, Select, Skeleton, Space, Switch, Modal, Tooltip,
TablePaginationConfig, Alert, notification, FormProps, Collapse,
TablePaginationConfig, Alert, notification, FormProps, Collapse, Upload,
} from "antd";
import type { UploadChangeParam } from "antd/es/upload";
import {
ExportOutlined, FileUnknownOutlined, FileExclamationOutlined, FileSyncOutlined,
@@ -31,6 +32,9 @@ import SectionHeader from "./SectionHeader";
import ResourceNotes from "./ResourceNotes";
import ResourceState from "./ResourceState";
import ModDetails from "./ModDetails";
import { Dropzone } from "./Dropzone";
import UploadButton from "./UploadButton";
import { useUploadProgress } from "./UploadProgress";
import { InputPartialVersion } from "./InputVersion";
import Link from "./Link";
@@ -526,6 +530,16 @@ function DownloadDependenciesButton(props: DownloadDependenciesProps) {
</>;
}
function UploadDragger(props: React.ComponentProps<typeof Upload.Dragger>) {
if (props.disabled) {
return <>{props.children}</>;
}
return <Upload.Dragger className="save-list-dragger" openFileDialogOnClick={false} {...props}>
<Dropzone />
{props.children}
</Upload.Dragger>;
}
type ModsTableProps = {
modPack: lib.ModPack;
changes: ModChange[];
@@ -535,6 +549,8 @@ type ModsTableProps = {
};
function ModsTable(props: ModsTableProps) {
const account = useAccount();
const control = useContext(ControlContext);
const { customRequest, list: uploadList } = useUploadProgress();
const [modInfos] = useMods();
const [showAddMods, setShowAddMods] = useState(false);
@@ -600,6 +616,53 @@ function ModsTable(props: ModsTableProps) {
}
mods = lib.applyModRecordAdvisories(mods, lib.getInstalledModUpdates(mods, modInfos.values()));
const versionsByName = new Map<string, lib.ModInfo[]>();
for (const info of modInfos.values()) {
const versions = versionsByName.get(info.name) ?? [];
versions.push(info);
versionsByName.set(info.name, versions);
}
for (const versions of versionsByName.values()) {
versions.sort((a, b) => b.integerVersion - a.integerVersion);
}
let packFactorioVersion: lib.MajorMinorVersion | undefined;
try {
packFactorioVersion = lib.normaliseMajorMinorVersion(props.modPack.factorioVersion);
} catch {
// Invalid pack version, every mod already shows wrong_factorio_version
}
function versionSelect(mod: lib.ModRecord) {
const versions = versionsByName.get(mod.name) ?? [];
if (deletedMods.has(mod.name) || !versions.some(info => info.version !== mod.version)) {
return mod.version;
}
const options = versions.map(info => ({
value: info.version,
label: info.factorioVersion === packFactorioVersion
? info.version : `${info.version} (Factorio ${info.factorioVersion})`,
}));
if (!versions.some(info => info.version === mod.version)) {
options.unshift({ value: mod.version, label: `${mod.version} (missing)` });
}
return <Select
size="small"
variant="borderless"
style={{ marginInlineStart: -8 }} // Line up with the plain text versions
popupMatchSelectWidth={false}
value={mod.version}
options={options}
onChange={(version: string) => {
const info = versions.find(candidate => candidate.version === version)!;
props.onChange({
type: "mods.set",
name: mod.name,
value: { ...props.modPack.mods.get(mod.name)!, version: info.version, sha1: info.sha1 },
});
}}
/>;
}
async function fixDependencyIssues(mod: lib.ModRecord) {
if (!mod.info) {
throw new Error("Mod record has no info"); // Should be unreachable
@@ -696,6 +759,33 @@ function ModsTable(props: ModsTableProps) {
</Space>;
}
function onUpload({ file }: UploadChangeParam) {
if (file.status !== "done") {
return;
}
for (const json of file.response.mods) {
const mod = lib.ModInfo.fromJSON(json);
props.onChange({
type: "mods.set",
name: mod.name,
value: { name: mod.name, enabled: true, version: mod.version, sha1: mod.sha1 },
});
}
}
const canUpload = account.hasPermission("core.mod.upload");
const uploadProps = {
disabled: !canUpload,
name: "file",
accept: ".zip",
multiple: true,
showUploadList: false,
headers: { "X-Access-Token": control.connector.token || "" },
action: `${webRoot}api/upload-mod`,
customRequest,
onChange: onUpload,
};
return <>
<SectionHeader
title="Mods"
@@ -732,6 +822,7 @@ function ModsTable(props: ModsTableProps) {
builtInModNames={props.builtInModNames}
checkForUpdates
/>}
{canUpload && <Upload {...uploadProps}><UploadButton /></Upload>}
<Button icon={<PlusOutlined />} onClick={() => setShowAddMods(true)}>Add</Button>
</Space>}
/>
@@ -743,112 +834,120 @@ function ModsTable(props: ModsTableProps) {
>
<SearchModsTable modPack={props.modPack} changes={props.changes} onChange={props.onChange} />
</Card>}
<Table
size="small"
rowSelection={{
type: "checkbox",
selectedRowKeys: [...props.modPack.mods.values()].filter(mod => mod.enabled).map(mod => mod.name),
getCheckboxProps(mod) {
return { disabled: deletedMods.has(mod.name) };
},
onChange(selectedRowKeys, selectedRows) {
function setEnabled(modNames: string[], enabled: boolean) {
for (let name of modNames) {
props.onChange({
type: "mods.set",
name,
value: { ...props.modPack.mods.get(name)!, enabled },
});
}
}
const added = selectedRowKeys.filter(
key => !props.modPack.mods.get(key as string)?.enabled
) as string[];
const removed = [...props.modPack.mods.values()].filter(
mod => mod.enabled && selectedRowKeys.indexOf(mod.name) === -1
).map(mod => mod.name);
setEnabled(added, true);
setEnabled(removed, false);
},
}}
columns={[
{
title: "Name",
key: "name",
render: (_, mod: lib.ModRecord) => {
const recommendedBy = mod.advisories
?.filter(advisory => advisory.type === "recommended_dependency")
.map(advisory => advisory.sourceModName) ?? [];
const update = mod.advisories
?.find(advisory => advisory.type === "update_available");
return <>
{mod.error === "missing" && <Tooltip title="Mod is missing from storage.">
<FileUnknownOutlined style={{ color: "#a61d24" }} />{" "}
</Tooltip>}
{mod.error === "bad_checksum" && <Tooltip title="Mod checksum mismatch.">
<FileExclamationOutlined style={{ color: "#a61d24" }} />{" "}
</Tooltip>}
{mod.warning === "incompatible" && <Tooltip title="Mod is incompatible with another.">
<FileExclamationOutlined style={{ color: "#dd5e14" }} />{" "}
</Tooltip>}
{mod.warning === "missing_dependency" && <Tooltip title="Mod is missing a dependency.">
<FileUnknownOutlined style={{ color: "#dd5e14" }} />{" "}
</Tooltip>}
{mod.warning === "wrong_version" && <Tooltip
title="Mod has wrong dependency version added."
>
<FileSyncOutlined style={{ color: "#dd5e14" }} />{" "}
</Tooltip>}
{mod.warning === "wrong_factorio_version" && <Tooltip
title="Mod has wrong factorio version."
>
<FileSyncOutlined style={{ color: "#dd5e14" }} />{" "}
</Tooltip>}
{recommendedBy.length > 0 && <Tooltip
title={`Recommended by ${recommendedBy.join(", ")}, but currently disabled.`}
>
<LikeOutlined style={{ color: "#0958d9" }} />{" "}
</Tooltip>}
{update?.type === "update_available" && <Tooltip
title={`A newer compatible version (${update.version}) is available.`}
>
<CloudSyncOutlined style={{ color: "#0958d9" }} />{" "}
</Tooltip>}
{mod.info?.title || mod.name}
</>;
{uploadList}
<UploadDragger {...uploadProps}>
<Table
size="small"
rowSelection={{
type: "checkbox",
selectedRowKeys: [...props.modPack.mods.values()].filter(mod => mod.enabled).map(mod => mod.name),
getCheckboxProps(mod) {
return { disabled: deletedMods.has(mod.name) };
},
defaultSortOrder: "ascend",
sorter: (a, b) => strcmp(a.name, b.name),
},
{
title: "Version",
dataIndex: "version",
sorter: (a, b) => strcmp(a.version, b.version),
},
{
title: "Action",
key: "action",
responsive: ["lg"],
render: mod => actions(mod),
},
]}
expandable={{
expandedRowRender: mod => <ModDetails mod={mod} mods={mods.filter(m => m.enabled)} actions={actions} />,
expandedRowClassName: () => "no-expanded-padding",
}}
dataSource={mods}
pagination={false}
rowKey="name"
rowClassName={mod => {
if (deletedMods.has(mod.name)) {
return "deleted";
}
if (changedMods.has(mod.name)) {
return "changed";
}
return "";
}}
/>
onChange(selectedRowKeys, selectedRows) {
function setEnabled(modNames: string[], enabled: boolean) {
for (let name of modNames) {
props.onChange({
type: "mods.set",
name,
value: { ...props.modPack.mods.get(name)!, enabled },
});
}
}
const added = selectedRowKeys.filter(
key => !props.modPack.mods.get(key as string)?.enabled
) as string[];
const removed = [...props.modPack.mods.values()].filter(
mod => mod.enabled && selectedRowKeys.indexOf(mod.name) === -1
).map(mod => mod.name);
setEnabled(added, true);
setEnabled(removed, false);
},
}}
columns={[
{
title: "Name",
key: "name",
render: (_, mod: lib.ModRecord) => {
const recommendedBy = mod.advisories
?.filter(advisory => advisory.type === "recommended_dependency")
.map(advisory => advisory.sourceModName) ?? [];
const update = mod.advisories
?.find(advisory => advisory.type === "update_available");
return <>
{mod.error === "missing" && <Tooltip title="Mod is missing from storage.">
<FileUnknownOutlined style={{ color: "#a61d24" }} />{" "}
</Tooltip>}
{mod.error === "bad_checksum" && <Tooltip title="Mod checksum mismatch.">
<FileExclamationOutlined style={{ color: "#a61d24" }} />{" "}
</Tooltip>}
{mod.warning === "incompatible" && <Tooltip title="Mod is incompatible with another.">
<FileExclamationOutlined style={{ color: "#dd5e14" }} />{" "}
</Tooltip>}
{mod.warning === "missing_dependency" && <Tooltip title="Mod is missing a dependency.">
<FileUnknownOutlined style={{ color: "#dd5e14" }} />{" "}
</Tooltip>}
{mod.warning === "wrong_version" && <Tooltip
title="Mod has wrong dependency version added."
>
<FileSyncOutlined style={{ color: "#dd5e14" }} />{" "}
</Tooltip>}
{mod.warning === "wrong_factorio_version" && <Tooltip
title="Mod has wrong factorio version."
>
<FileSyncOutlined style={{ color: "#dd5e14" }} />{" "}
</Tooltip>}
{recommendedBy.length > 0 && <Tooltip
title={`Recommended by ${recommendedBy.join(", ")}, but currently disabled.`}
>
<LikeOutlined style={{ color: "#0958d9" }} />{" "}
</Tooltip>}
{update?.type === "update_available" && <Tooltip
title={`A newer compatible version (${update.version}) is available.`}
>
<CloudSyncOutlined style={{ color: "#0958d9" }} />{" "}
</Tooltip>}
{mod.info?.title || mod.name}
</>;
},
defaultSortOrder: "ascend",
sorter: (a, b) => strcmp(a.name, b.name),
},
{
title: "Version",
key: "version",
render: (_, mod: lib.ModRecord) => versionSelect(mod),
sorter: (a, b) => strcmp(a.version, b.version),
},
{
title: "Action",
key: "action",
responsive: ["lg"],
render: mod => actions(mod),
},
]}
expandable={{
expandedRowRender: mod => <ModDetails
mod={mod}
mods={mods.filter(m => m.enabled)}
actions={actions}
/>,
expandedRowClassName: () => "no-expanded-padding",
}}
dataSource={mods}
pagination={false}
rowKey="name"
rowClassName={mod => {
if (deletedMods.has(mod.name)) {
return "deleted";
}
if (changedMods.has(mod.name)) {
return "changed";
}
return "";
}}
/>
</UploadDragger>
</>;
}
@@ -25,6 +25,7 @@ import Link from "./Link";
import ModDetails from "./ModDetails";
import { Dropzone } from "./Dropzone";
import UploadButton from "./UploadButton";
import { useUploadProgress } from "./UploadProgress";
import { InputPartialVersion } from "./InputVersion";
const strcmp = new Intl.Collator(undefined, { numeric: true, sensitivity: "base" }).compare;
@@ -524,6 +525,7 @@ export default function ModsPage() {
let account = useAccount();
let control = useContext(ControlContext);
let [mods] = useMods();
const { customRequest, list: uploadList } = useUploadProgress();
let [modPacks] = useModPacks();
const modPackTable = useTableQueryState<lib.ModPack>({
namespace: "modPack", defaultSortKey: "name",
@@ -582,6 +584,7 @@ export default function ModsPage() {
"X-Access-Token": control.connector.token || "",
}}
action={`${webRoot}api/upload-mod`}
customRequest={customRequest}
>
<UploadButton />
</Upload>;
@@ -635,6 +638,7 @@ export default function ModsPage() {
<SearchModsButton />
{uploadButton}
</Space>} />
{uploadList}
<Upload.Dragger
className="save-list-dragger"
@@ -646,6 +650,7 @@ export default function ModsPage() {
"X-Access-Token": control.connector.token || "",
}}
action={`${webRoot}api/upload-mod`}
customRequest={customRequest}
showUploadList={false}
>
<Dropzone />
@@ -1,5 +1,5 @@
import React, { useState } from "react";
import { Collapse } from "antd";
import { Collapse, ConfigProvider } from "antd";
import { useUsers } from "../model/user";
import UsersTable from "./UsersTable";
@@ -24,12 +24,15 @@ export default function OnlinePlayersList({ instanceId }: OnlinePlayersListProps
items={[{
key: "players",
label: `Online Players (${onlineCount})`,
children: <UsersTable instanceId={instanceId} onlyOnline size="small" pagination={{
defaultPageSize: 10,
showSizeChanger: true,
pageSizeOptions: ["10", "20", "50", "100", "200"],
showTotal: (total: number) => `${total} Users`,
}} />,
styles: { body: { padding: 0 } },
children: <ConfigProvider theme={{ components: { Table: { headerBorderRadius: 0 } } }}>
<UsersTable instanceId={instanceId} onlyOnline size="small" pagination={{
defaultPageSize: 10,
showSizeChanger: true,
pageSizeOptions: ["10", "20", "50", "100", "200"],
showTotal: (total: number) => `${total} Users`,
}} />
</ConfigProvider>,
}]}
/>;
}
+13 -1
View File
@@ -1,4 +1,4 @@
import React from "react";
import React, { useEffect } from "react";
import { Layout, Breadcrumb } from "antd";
import Link from "./Link";
@@ -11,7 +11,19 @@ type PageLayoutProps = {
}[];
children?: any;
};
function clusterName() {
const meta = document.querySelector<HTMLMetaElement>("meta[name=application-name]");
return meta?.content || "Clusterio";
}
export default function PageLayout(props: PageLayoutProps) {
const page = props.nav.at(-1)?.name;
useEffect(() => {
const name = clusterName();
document.title = page ? `${page} - ${name}` : name;
return () => { document.title = name; };
}, [page]);
return <>
<Breadcrumb
className="site-breadcrumb"
@@ -9,6 +9,8 @@ import { useRole } from "../model/roles";
import { useAccount } from "../model/account";
import ControlContext from "./ControlContext";
import PageHeader from "./PageHeader";
import UnsavedChangesBar from "./UnsavedChangesBar";
import FieldRow from "./FieldRow";
import PageLayout from "./PageLayout";
import PluginExtra from "./PluginExtra";
import ResourceNotes from "./ResourceNotes";
@@ -292,46 +294,15 @@ export default function RoleViewPage() {
</Space>}
/>
{edited && (
<div style={{
position: "fixed",
bottom: 24,
left: "50%",
transform: "translateX(-50%)",
background: "#2a1912",
borderRadius: 8,
boxShadow: "0 8px 24px rgba(0,0,0,0.12)",
padding: "10px 14px",
display: "flex",
alignItems: "center",
gap: 12,
zIndex: 1000,
}}>
<span style={{ color: "#FFF" }}>
You have unsaved changes
</span>
{edited && <UnsavedChangesBar onRevert={revertChanges} onApply={applyChanges} />}
<Space>
<Button onClick={revertChanges}>
Revert
</Button>
<Button type="primary" onClick={applyChanges}>
Apply
</Button>
</Space>
</div>
)}
<div style={{ marginBottom: 16, display: "flex", alignItems: "center", gap: 12 }}>
<label style={{ width: 110, flexShrink: 0 }}>Name</label>
<FieldRow label="Name">
<Input value={name} disabled={!canUpdate} onChange={e => setNameEdit(e.target.value)} />
</div>
</FieldRow>
<div style={{ marginBottom: 16, display: "flex", alignItems: "center", gap: 12 }}>
<label style={{ width: 110, flexShrink: 0 }}>Description</label>
<FieldRow label="Description">
<Input value={description} disabled={!canUpdate} onChange={e => setDescriptionEdit(e.target.value)} />
</div>
</FieldRow>
<ResourceNotes resourceType="role" resourceId={roleId} />
+165 -91
View File
@@ -1,7 +1,7 @@
import React, { useContext, useState } from "react";
import {
message, Button, Checkbox, Form, Input, List, Modal,
Popconfirm, Progress, Select, Space, Table, Tooltip, Upload,
message, Button, Checkbox, Form, Input, Modal,
Popconfirm, Select, Space, Table, Tooltip, Typography, Upload,
} from "antd";
import CaretLeftOutlined from "@ant-design/icons/CaretLeftOutlined";
import LeftOutlined from "@ant-design/icons/LeftOutlined";
@@ -10,6 +10,8 @@ import * as lib from "@clusterio/lib";
import { useAccount } from "../model/account";
import useTableQueryState from "../util/useTableQueryState";
import useColumnSearch from "../util/useColumnSearch";
import type { Control } from "../util/websocket";
import ControlContext from "./ControlContext";
import CreateSaveModal from "./CreateSaveModal";
import SectionHeader from "./SectionHeader";
@@ -19,6 +21,7 @@ import { useSavesOfInstance } from "../model/saves";
import { notifyErrorHandler } from "../util/notify";
import { Dropzone } from "./Dropzone";
import UploadButton from "./UploadButton";
import { useUploadProgress } from "./UploadProgress";
type ModalProps = {
@@ -66,16 +69,16 @@ function RenameModal(props: ModalProps) {
</>;
}
function CopyModal(props: ModalProps) {
function DuplicateModal(props: ModalProps) {
let control = useContext(ControlContext);
let [open, setOpen] = useState(false);
let [form] = Form.useForm();
return <>
<Button disabled={props.disabled} onClick={() => setOpen(true)}>Copy</Button>
<Button disabled={props.disabled} onClick={() => setOpen(true)}>Duplicate</Button>
<Modal
title="Copy save"
okText="Copy"
title="Duplicate save"
okText="Duplicate"
open={open}
onOk={() => form.submit()}
onCancel={() => setOpen(false)}
@@ -90,7 +93,7 @@ function CopyModal(props: ModalProps) {
).then(() => {
setOpen(false);
form.resetFields();
}).catch(notifyErrorHandler("Error copying save"));
}).catch(notifyErrorHandler("Error duplicating save"));
}}
>
<Form.Item
@@ -106,17 +109,66 @@ function CopyModal(props: ModalProps) {
}
function TransferModal(props: ModalProps) {
/** Runs action on each save in turn, returning the names that failed. */
async function forEachSave(
saves: lib.SaveDetails[],
action: (save: lib.SaveDetails) => Promise<unknown>,
errorText: string,
) {
const failed: string[] = [];
for (const save of saves) {
try {
await action(save);
} catch (err: any) {
failed.push(save.name);
notifyErrorHandler(`${errorText} ${save.name}`)(err);
}
}
return failed;
}
function downloadSave(control: Control, instanceId: number, name: string) {
return control.send(new lib.InstanceDownloadSaveRequest(instanceId, name)).then(streamId => {
let url = new URL(webRoot, document.location.href);
url.pathname += `api/stream/${streamId}`;
// A download link instead of navigating, so several downloads do not cancel each other.
const link = document.createElement("a");
link.href = url.href;
link.download = name;
link.click();
});
}
type TransferModalProps = {
disabled: boolean;
saves: lib.SaveDetails[];
instanceId: number;
onDone?: (failed: string[]) => void;
};
function TransferModal(props: TransferModalProps) {
let account = useAccount();
let control = useContext(ControlContext);
let [open, setOpen] = useState(false);
let [form] = Form.useForm();
let [instances] = useInstances();
const single = props.saves.length === 1 ? props.saves[0] : undefined;
const canCopy = account.hasPermission("core.instance.save.copy");
function transfer(values: { targetInstanceId: number, transferredName?: string, copy: boolean }) {
return forEachSave(props.saves, save => control.send(new lib.InstanceTransferSaveRequest(
props.instanceId,
save.name,
values.targetInstanceId,
(single && values.transferredName) || save.name,
values.copy,
)), "Error transfering");
}
return <>
<Button disabled={props.disabled} onClick={() => setOpen(true)}>Transfer</Button>
<Modal
title="Transfer save"
title={single ? "Transfer save" : `Transfer ${props.saves.length} saves`}
okText="Transfer"
open={open}
onOk={() => form.submit()}
@@ -127,22 +179,17 @@ function TransferModal(props: ModalProps) {
form={form}
labelCol={{ span: 6 }}
wrapperCol={{ span: 18 }}
initialValues={{ transferredName: props.save.name, copy: false }}
initialValues={{ transferredName: single?.name, copy: !single && canCopy }}
onFinish={values => {
setOpen(false);
let hide = message.loading("Transferring save...", 0);
control.send(new lib.InstanceTransferSaveRequest(
props.instanceId,
props.save.name,
values.targetInstanceId,
values.transferredName || props.save.name,
values.copy,
)).then(() => {
message.success("Transfer complete");
let hide = message.loading(single ? "Transferring save..." : "Transferring saves...", 0);
transfer(values).then(failed => {
if (failed.length < props.saves.length) {
message.success(failed.length ? "Transfer partially complete" : "Transfer complete");
}
form.resetFields();
}).catch(
notifyErrorHandler("Error transfering save")
).finally(() => hide());
props.onDone?.(failed);
}).finally(() => hide());
}}
>
<Form.Item
@@ -169,23 +216,21 @@ function TransferModal(props: ModalProps) {
</Select.Option>)}
</Select>
</Form.Item>
<Form.Item
{single && <Form.Item
name="transferredName"
label="Transferred name"
>
<Input
disabled={!account.hasAnyPermission("core.instance.save.rename", "core.instance.save.copy")}
/>
</Form.Item>
</Form.Item>}
<Form.Item
name="copy"
valuePropName="checked"
label="Copy"
tooltip="Copy instead of moving the save to the new instance."
>
<Checkbox
disabled={!account.hasPermission("core.instance.save.copy")}
/>
<Checkbox disabled={!canCopy} />
</Form.Item>
</Form>
</Modal>
@@ -193,22 +238,78 @@ function TransferModal(props: ModalProps) {
}
type File = {
uid: string;
name: string;
percent: number;
status: string;
type BulkActionsProps = {
disabled: boolean;
instanceId: number;
saves: lib.SaveDetails[];
onDone: (failed: string[]) => void;
};
function BulkActions(props: BulkActionsProps) {
const account = useAccount();
const control = useContext(ControlContext);
const [running, setRunning] = useState<string>();
const count = props.saves.length;
function run(name: string, action: (save: lib.SaveDetails) => Promise<unknown>, errorText: string) {
setRunning(name);
forEachSave(props.saves, action, errorText)
.then(props.onDone)
.finally(() => setRunning(undefined));
}
const disabled = props.disabled || running !== undefined;
return <Space wrap>
<Typography.Text type="secondary">{count} selected</Typography.Text>
{account.hasPermission("core.instance.save.download") && <Button
disabled={disabled}
loading={running === "download"}
onClick={() => run(
"download", save => downloadSave(control, props.instanceId, save.name), "Error downloading"
)}
>Download</Button>}
{account.hasPermission("core.instance.save.transfer") && <TransferModal
disabled={disabled} instanceId={props.instanceId} saves={props.saves} onDone={props.onDone}
/>}
{account.hasPermission("core.instance.save.delete") && <Popconfirm
title={`Permanently delete ${count} ${count === 1 ? "save" : "saves"}?`}
okText="Delete"
okButtonProps={{ danger: true }}
onConfirm={() => run("delete", save => control.send(
new lib.InstanceDeleteSaveRequest(props.instanceId, save.name)
), "Error deleting")}
>
<Button danger disabled={disabled} loading={running === "delete"}>Delete</Button>
</Popconfirm>}
</Space>;
}
export default function SavesList(props: { instance: lib.InstanceDetails }) {
let account = useAccount();
let control = useContext(ControlContext);
let [saves] = useSavesOfInstance(props.instance.id);
let [starting, setStarting] = useState(false);
let [uploadingFiles, setUploadingFiles] = useState<File[]>([]);
const { customRequest, list: uploadList } = useUploadProgress();
const tableState = useTableQueryState<lib.SaveDetails>({
namespace: "save", defaultSortKey: "mtimeMs", defaultSortOrder: "descend", pagination: { defaultPageSize: 10 },
});
const nameSearch = useColumnSearch<lib.SaveDetails>(tableState, "name", save => save.name, "Search saves");
const [selectedNames, setSelectedNames] = useState<string[]>([]);
const saveList = [...saves.values()];
const selectedSaves = saveList.filter(save => selectedNames.includes(save.name));
const nameFilter = tableState.filteredValue("name")?.[0]?.toLowerCase();
const visibleNames = saveList
.filter(save => !nameFilter || save.name.toLowerCase().includes(nameFilter))
.map(save => save.name);
const visibleSelected = visibleNames.filter(name => selectedNames.includes(name)).length;
const canTransfer = account.hasPermission("core.instance.save.transfer");
const canSelect = account.hasAnyPermission(
"core.instance.save.download",
"core.instance.save.transfer",
"core.instance.save.delete",
);
let hostOffline = ["unassigned", "unknown"].includes(props.instance.status!);
const saveTable = <Table
@@ -225,6 +326,8 @@ export default function SavesList(props: { instance: lib.InstanceDetails }) {
</>,
sorter: (a, b) => a.name.localeCompare(b.name),
sortOrder: tableState.sortOrder("name"),
filteredValue: tableState.filteredValue("name"),
...nameSearch,
},
{
title: "Size",
@@ -243,10 +346,24 @@ export default function SavesList(props: { instance: lib.InstanceDetails }) {
sortOrder: tableState.sortOrder("mtimeMs"),
},
]}
dataSource={[...saves.values()]}
dataSource={saveList}
pagination={tableState.pagination}
onChange={tableState.onChange}
rowKey={save => save.name}
rowSelection={canSelect ? {
selectedRowKeys: selectedSaves.map(save => save.name),
onChange: keys => setSelectedNames(keys as string[]),
// Select all covers every save matching the search, not just the current page.
columnTitle: <Checkbox
disabled={!visibleNames.length}
checked={visibleNames.length > 0 && visibleSelected === visibleNames.length}
indeterminate={visibleSelected > 0 && visibleSelected < visibleNames.length}
onChange={e => setSelectedNames(e.target.checked
? [...new Set([...selectedNames, ...visibleNames])]
: selectedNames.filter(name => !visibleNames.includes(name))
)}
/>,
} : undefined}
expandable={{
columnWidth: 33,
expandRowByClick: true,
@@ -266,29 +383,23 @@ export default function SavesList(props: { instance: lib.InstanceDetails }) {
() => { setStarting(false); }
);
}}
>Load save</Button>}
>Load</Button>}
{account.hasPermission("core.instance.save.rename") && <RenameModal
disabled={hostOffline} instanceId={props.instance.id!} save={save}
/>}
{account.hasPermission("core.instance.save.copy") && <CopyModal
{account.hasPermission("core.instance.save.copy") && <DuplicateModal
disabled={hostOffline} instanceId={props.instance.id!} save={save}
/>}
{account.hasPermission("core.instance.save.download") && <Button
disabled={hostOffline}
onClick={() => {
control.send(
new lib.InstanceDownloadSaveRequest(props.instance.id!, save.name)
).then(streamId => {
let url = new URL(webRoot, document.location.href);
url.pathname += `api/stream/${streamId}`;
document.location.assign(url);
}).catch(
downloadSave(control, props.instance.id!, save.name).catch(
notifyErrorHandler("Error downloading save")
);
}}
>Download</Button>}
{account.hasPermission("core.instance.save.transfer") && <TransferModal
disabled={hostOffline} instanceId={props.instance.id!} save={save}
{canTransfer && <TransferModal
disabled={hostOffline} instanceId={props.instance.id!} saves={[save]}
/>}
{account.hasPermission("core.instance.save.delete") && <Popconfirm
title="Permanently delete save?"
@@ -309,38 +420,6 @@ export default function SavesList(props: { instance: lib.InstanceDetails }) {
}}
/>;
function onChange(changeEvent: any) {
if (["done", "error"].includes(changeEvent.file.status)) {
if (changeEvent.file.status === "error") {
notifyErrorHandler("Error uploading file")(changeEvent.file.error);
}
let newUploadingFiles = [...uploadingFiles];
let index = newUploadingFiles.findIndex(f => f.uid === changeEvent.file.uid);
if (index !== -1) {
newUploadingFiles.splice(index, 1);
setUploadingFiles(newUploadingFiles);
}
return;
}
let file: File = {
uid: changeEvent.file.uid,
name: changeEvent.file.name,
percent: changeEvent.file.percent,
status: changeEvent.file.status,
};
let newUploadingFiles = [...uploadingFiles];
let index = newUploadingFiles.findIndex(f => f.uid === changeEvent.file.uid);
if (index !== -1) {
newUploadingFiles[index] = file;
} else {
newUploadingFiles.push(file);
}
setUploadingFiles(newUploadingFiles);
}
let uploadProps = {
disabled: hostOffline,
name: "file",
@@ -353,18 +432,23 @@ export default function SavesList(props: { instance: lib.InstanceDetails }) {
},
showUploadList: false,
action: `${webRoot}api/upload-save`,
onChange,
customRequest,
};
return <div>
<SectionHeader title="Saves" extra={<Space wrap>
{selectedSaves.length > 0 && <BulkActions
disabled={hostOffline}
instanceId={props.instance.id!}
saves={selectedSaves}
onDone={setSelectedNames}
/>}
{account.hasPermission("core.instance.save.upload") && <Upload {...uploadProps} >
<UploadButton disabled={hostOffline}>
Upload save
</UploadButton>
<UploadButton disabled={hostOffline} icon={null} />
</Upload>}
{account.hasPermission("core.instance.save.create") && <CreateSaveModal instance={props.instance} />}
</Space>} />
{uploadList}
{
account.hasPermission("core.instance.save.upload")
? <Upload.Dragger className="save-list-dragger" openFileDialogOnClick={false} {...uploadProps}>
@@ -373,15 +457,5 @@ export default function SavesList(props: { instance: lib.InstanceDetails }) {
</Upload.Dragger>
: saveTable
}
{uploadingFiles.length ? <List>
{uploadingFiles.map(file => <List.Item key={file.uid}>
{file.name}
<Progress
percent={file.percent}
format={percent => `${Math.floor(percent || 0)}%`}
status={file.status === "error" ? "exception" : "normal"}
/>
</List.Item>)}
</List> : null}
</div>;
}
@@ -11,6 +11,7 @@ import AboutModal from "./AboutModal";
import Link from "./Link";
import { saveJson } from "../util/save_file";
import useScrollRestoration from "../util/useScrollRestoration";
import { useAccount } from "../model/account";
import { DraggingContext } from "../model/is_dragging";
import webUiPackage from "../../package.json";
@@ -50,6 +51,7 @@ function isActiveDropzone(element: HTMLElement | null): boolean {
export default function SiteLayout() {
let navigate = useNavigate();
useScrollRestoration();
let [currentSidebarPath, setCurrentSidebarPath] = useState<string | null>(null);
const screens = Grid.useBreakpoint();
// On phone screens the sidebar becomes an overlay drawer instead of a fixed sider.
@@ -0,0 +1,40 @@
import React from "react";
import { Button, Space } from "antd";
type UnsavedChangesBarProps = {
onRevert: () => void;
onApply: () => void;
applying?: boolean;
};
/** Floating bar shown while a page has edits that are not applied yet */
export default function UnsavedChangesBar(props: UnsavedChangesBarProps) {
return <div style={{
position: "fixed",
bottom: 24,
left: "50%",
transform: "translateX(-50%)",
background: "#2a1912",
borderRadius: 8,
boxShadow: "0 8px 24px rgba(0,0,0,0.12)",
padding: "10px 14px",
display: "flex",
alignItems: "center",
gap: 12,
zIndex: 1000,
}}>
<span style={{ color: "#FFF" }}>
You have unsaved changes
</span>
<Space>
<Button onClick={props.onRevert}>
Revert
</Button>
<Button type="primary" loading={props.applying} onClick={props.onApply}>
Apply
</Button>
</Space>
</div>;
}
@@ -7,6 +7,8 @@ import { DraggingContext } from "../model/is_dragging";
export default function UploadButton(props: React.ComponentProps<typeof Button>) {
const isDroppingFile = useContext(DraggingContext);
const borderColor = props.disabled ? "gray" : "rgb(22, 119, 255)";
// Pass icon={null} for no icon
const icon = props.icon === undefined ? <UploadOutlined /> : props.icon;
return <Button
className={`dropzone ${props.disabled ? "disabled" : "enabled"}`}
{...props}
@@ -15,7 +17,7 @@ export default function UploadButton(props: React.ComponentProps<typeof Button>)
// Distinct border when dropping file
border: isDroppingFile ? `dashed 2px ${borderColor}` : undefined,
}}
icon={isDroppingFile ? <InboxOutlined /> : props.icon || <UploadOutlined />}
icon={isDroppingFile ? <InboxOutlined /> : icon}
>
{props.children || "Upload"}
</Button>;
@@ -0,0 +1,93 @@
import { useCallback, useState } from "react";
import { Button, List, Progress, Typography, type UploadProps } from "antd";
import * as lib from "@clusterio/lib";
import notify, { notifyErrorHandler } from "../util/notify";
type CustomRequest = NonNullable<UploadProps["customRequest"]>;
interface Upload {
uid: string;
name: string;
loaded: number;
total: number;
abort: () => void;
}
function errorMessage(err: any, body: any) {
const errors = [...body?.request_errors ?? [], ...body?.errors ?? []];
if (errors.length) {
return errors.join(", ");
}
if (err instanceof Error) {
return err.message;
}
return "Connection to the controller failed";
}
/**
* Track uploads made by antd Upload components and show them with a cancel button.
* @returns customRequest to pass to every Upload sharing the list, and the list to render.
*/
export function useUploadProgress(): { customRequest: CustomRequest, list: React.ReactNode } {
const [uploads, setUploads] = useState<Upload[]>([]);
function update(uid: string, change: Partial<Upload>) {
setUploads(current => current.map(upload => (upload.uid === uid ? { ...upload, ...change } : upload)));
}
function remove(uid: string) {
setUploads(current => current.filter(upload => upload.uid !== uid));
}
const customRequest = useCallback<CustomRequest>((options, { defaultRequest }) => {
const file = options.file as File & { uid: string };
const uid = file.uid;
// antd types this as void, rc-upload returns the abort handle.
const request = defaultRequest({
...options,
onProgress(event) {
options.onProgress?.(event);
update(uid, { loaded: event.loaded ?? 0, total: event.total ?? file.size });
},
onSuccess(body, xhr) {
options.onSuccess?.(body, xhr);
remove(uid);
},
onError(err, body) {
options.onError?.(err, body);
remove(uid);
notifyErrorHandler(`Error uploading ${file.name}`)(new Error(errorMessage(err, body)));
},
}) as unknown as { abort: () => void };
const abort = () => {
request.abort();
// An aborted XMLHttpRequest calls neither onload nor onerror.
options.onError?.(new Error("Upload cancelled"));
remove(uid);
notify(`Cancelled upload of ${file.name}`);
};
setUploads(current => [...current, { uid, name: file.name, loaded: 0, total: file.size, abort }]);
return { abort };
}, []);
const list = uploads.length ? <List
size="small"
className="upload-progress-list"
dataSource={uploads}
rowKey={upload => upload.uid}
renderItem={upload => <List.Item
actions={[<Button key="cancel" size="small" onClick={upload.abort}>Cancel</Button>]}
>
<div style={{ flex: 1, minWidth: 0 }}>
<Typography.Text ellipsis>{upload.name}</Typography.Text>
<Progress
percent={upload.total ? upload.loaded / upload.total * 100 : 0}
format={() => `${lib.formatBytes(upload.loaded)} / ${lib.formatBytes(upload.total)}`}
/>
</div>
</List.Item>}
/> : null;
return { customRequest, list };
}
+124 -176
View File
@@ -1,10 +1,10 @@
import React, { useEffect, useContext, useState } from "react";
import { useNavigate, useParams } from "react-router-dom";
import {
Button, Col, Descriptions, Form, Input, Popconfirm,
Row, Table, Tag, Select, Space, Switch,
Button, Descriptions, Dropdown, Input, Popconfirm, Table, Tag, Select, Space, Switch,
} from "antd";
import DeleteOutlined from "@ant-design/icons/DeleteOutlined";
import DownOutlined from "@ant-design/icons/DownOutlined";
import * as lib from "@clusterio/lib";
@@ -13,14 +13,17 @@ import useTableQueryState from "../util/useTableQueryState";
import { useAccount } from "../model/account";
import { useInstances } from "../model/instance";
import ControlContext from "./ControlContext";
import FieldRow from "./FieldRow";
import PageHeader from "./PageHeader";
import PageLayout from "./PageLayout";
import PluginExtra from "./PluginExtra";
import SectionHeader from "./SectionHeader";
import ResourceNotes from "./ResourceNotes";
import ResourceState from "./ResourceState";
import UnsavedChangesBar from "./UnsavedChangesBar";
import useRowNavigation from "../util/useRowNavigation";
import useResourceState from "../util/useResourceState";
import usePluginActions from "../util/usePluginActions";
import Link from "./Link";
import notify, { notifyErrorHandler } from "../util/notify";
import { formatDuration } from "../util/time_format";
@@ -28,6 +31,20 @@ import { formatFirstSeen, formatLastSeen, sortFirstSeen, sortLastSeen, useUser }
const strcmp = new Intl.Collator(undefined, { numeric: true, sensitivity: "base" }).compare;
function sameIds(ids: number[], set: Set<number>) {
return ids.length === set.size && ids.every(id => set.has(id));
}
function UserPluginActions(props: { user: lib.UserDetails }) {
const pluginActions = usePluginActions("UserViewPage", { user: props.user });
if (!pluginActions.length) {
return null;
}
return <Dropdown placement="bottomRight" trigger={["click"]} menu={{ items: pluginActions }}>
<Button>More <DownOutlined /></Button>
</Dropdown>;
}
// The user page has a lot of optional elements, that does not make it
// praticularly complicated.
@@ -45,66 +62,66 @@ export default function UserViewPage() {
const [user, synced, error] = useUser(userName);
const state = useResourceState(user, synced, error, userName);
let [roles, rolesSynced] = useRoles();
let [form] = Form.useForm();
const statsTable = useTableQueryState<[number, lib.PlayerStats]>({
namespace: "stats", defaultSortKey: "instance",
});
let [rolesDirty, setRolesDirty] = useState<boolean>(false);
let [banReasonDirty, setBanReasonDirty] = useState<boolean>(false);
let [applyingRoles, setApplyingRoles] = useState<boolean>(false);
let [rolesError, setRolesError] = useState<string|undefined>();
// Local edits on top of the live user
const [rolesEdit, setRolesEdit] = useState<number[]>();
const [bannedEdit, setBannedEdit] = useState<boolean>();
const [banReasonEdit, setBanReasonEdit] = useState<string>();
const [applying, setApplying] = useState(false);
const canUpdateRoles = account.hasPermission("core.user.update_roles");
const canBan = account.hasPermission("core.user.set_banned");
const canSetAdmin = account.hasPermission("core.user.set_admin");
const canSetWhitelisted = account.hasPermission("core.user.set_whitelisted");
// Drop edits that now match the user, and roles deleted since
useEffect(() => {
if (
account.hasPermission("core.user.set_banned")
&& !banReasonDirty
&& user
&& user.banReason !== form.getFieldValue("banReason")
) {
form.setFieldsValue({ "banReason": user.banReason });
}
}, [account, form, user, banReasonDirty]);
useEffect(() => {
if (!user || !account.hasPermission("core.user.update_roles")) {
if (!user) {
return;
}
const current: number[] = form.getFieldValue("roles") ?? [];
// Keep local edits, but drop roles deleted since
const next = rolesDirty
? current.filter(id => !rolesSynced || roles.has(id))
: [...user.roleIds];
if (next.length !== current.length || next.some((id, i) => id !== current[i])) {
form.setFieldsValue({ "roles": next });
}
}, [account, form, user, roles, rolesSynced, rolesDirty]);
setRolesEdit(prev => {
const next = prev?.filter(id => !rolesSynced || roles.has(id));
return next && sameIds(next, user.roleIds) ? undefined : next;
});
setBannedEdit(prev => (prev === user.isBanned ? undefined : prev));
setBanReasonEdit(prev => (prev === user.banReason ? undefined : prev));
}, [user, roles, rolesSynced]);
useEffect(() => {
setRolesEdit(undefined);
setBannedEdit(undefined);
setBanReasonEdit(undefined);
}, [userName]);
let nav = [{ name: "Users", path: "/users" }, { name: userName }];
if (!user) {
return <ResourceState state={state} type="User" id={userName} nav={nav} listPath="/users" error={error} />;
}
let roleSelector = <Form.Item
noStyle
name="roles"
initialValue={[...user.roleIds]}
rules={[
{ validator: () => (rolesError ? Promise.reject(rolesError) : Promise.resolve()) },
]}
>
<Select
onChange={() => setRolesDirty(true)}
loading={!roles}
mode="multiple"
optionFilterProp="name"
>
{[...roles.values()].map(r => <Select.Option
key={r.id}
value={r.id}
name={r.name}
>{r.name}</Select.Option>)}
</Select>
</Form.Item>;
const roleIds = rolesEdit ?? [...user.roleIds];
const banned = bannedEdit ?? user.isBanned;
const banReason = banned ? banReasonEdit ?? user.banReason : "";
const rolesChanged = rolesEdit !== undefined && !sameIds(rolesEdit, user.roleIds);
const banChanged = banned !== user.isBanned || banReason !== user.banReason;
function revertChanges() {
setRolesEdit(undefined);
setBannedEdit(undefined);
setBanReasonEdit(undefined);
}
async function applyChanges() {
if (rolesChanged) {
await control.send(new lib.UserUpdateRolesRequest(userName, roleIds));
setRolesEdit(undefined);
}
if (banChanged) {
await control.send(new lib.UserSetBannedRequest(userName, false, banned, banReason));
setBannedEdit(undefined);
setBanReasonEdit(undefined);
}
}
function instanceName(id: number) {
return instances.get(id)?.name ?? String(id);
@@ -167,136 +184,67 @@ export default function UserViewPage() {
<DeleteOutlined />
</Button>
</Popconfirm>}
<UserPluginActions user={user} />
</Space>}
/>
<Form
form={form}
labelCol={{
sm: { span: 6 },
md: { span: 6 },
lg: { span: 4 },
xl: { span: 3 },
xxl: { span: 2 },
{(rolesChanged || banChanged) && <UnsavedChangesBar
applying={applying}
onRevert={revertChanges}
onApply={() => {
setApplying(true);
applyChanges()
.catch(notifyErrorHandler("Error applying changes"))
.finally(() => setApplying(false));
}}
wrapperCol={{
sm: { span: 18 },
md: { span: 18 },
lg: { span: 20 },
xl: { span: 21 },
xxl: { span: 22 },
}}
>
<Form.Item
label="Roles"
>
<Row gutter={[8, 8]}>
<Col flex="auto">
{account.hasPermission("core.user.update_roles")
? roleSelector
: [...user.roleIds!].map(id => <Tag key={id}>{
roles?.get(id)?.name ?? id
}</Tag>)
}
</Col>
{account.hasPermission("core.user.update_roles") && <Col flex="0 0 auto">
<Button
type={"primary"}
disabled={!rolesDirty}
loading={applyingRoles}
onClick={() => {
let newRoles = form.getFieldValue("roles");
setApplyingRoles(true);
control.send(
new lib.UserUpdateRolesRequest(userName, newRoles)
).then(() => {
setRolesDirty(false);
setRolesError(undefined);
}).catch(err => {
setRolesError(err.message);
return form.validateFields();
}).finally(() => {
setApplyingRoles(false);
});
}}
>Apply</Button>
</Col>}
</Row>
</Form.Item>
{account.hasPermission("core.user.set_admin") && <Form.Item label="In-game Admin">
<Switch
checked={user.isAdmin}
onClick={() => {
control.send(
new lib.UserSetAdminRequest(userName, false, !user.isAdmin)
).catch(notifyErrorHandler("Error toggling user admin status"));
}}
/>
</Form.Item>}
{account.hasPermission("core.user.set_whitelisted") && <Form.Item label="Whitelisted">
<Switch
checked={user.isWhitelisted}
onClick={() => {
control.send(
new lib.UserSetWhitelistedRequest(userName, false, !user.isWhitelisted)
).catch(notifyErrorHandler("Error toggling user whitelisted status"));
}}
/>
</Form.Item>}
{account.hasPermission("core.user.set_banned")
? <Form.Item label="Ban reason">
<Row gutter={[8, 8]} justify={"end"}>
<Col flex="auto" style={{ minWidth: "20em" }}>
<Form.Item noStyle name="banReason" initialValue={user.banReason}>
<Input
onChange={e => {
setBanReasonDirty(e.target.value !== user.banReason);
}}
/>
</Form.Item>
</Col>
<Col flex="0 0 auto">
{user.isBanned
? <Space>
<Button
type={banReasonDirty ? "primary" : "default"}
onClick={() => {
control.send(
new lib.UserSetBannedRequest(
userName, false, true, form.getFieldValue("banReason")
)
).then(() => {
setBanReasonDirty(false);
}).catch(notifyErrorHandler("Error updating ban"));
}}
>Update</Button>
<Button
onClick={() => {
control.send(
new lib.UserSetBannedRequest(userName, false, false, "")
).catch(notifyErrorHandler("Error unbanning user"));
}}
>Unban</Button>
</Space>
: <Button
type={banReasonDirty ? "primary" : "default"}
onClick={() => {
control.send(
new lib.UserSetBannedRequest(
userName, false, true, form.getFieldValue("banReason")
)
).then(() => {
setBanReasonDirty(false);
}).catch(notifyErrorHandler("Error banning user"));
}}
>Ban</Button>
}
</Col>
</Row>
</Form.Item>
: user.isBanned
&& <Form.Item label="Ban reason">{user.banReason}</Form.Item>
}
</Form>
/>}
<FieldRow label="Roles">
<Select
style={{ width: "100%" }}
mode="multiple"
disabled={!canUpdateRoles}
value={roleIds}
onChange={setRolesEdit}
optionFilterProp="label"
options={[...roles.values()].map(r => ({ value: r.id, label: r.name }))}
/>
</FieldRow>
{(canSetAdmin || canSetWhitelisted || canBan) && <FieldRow label="Status">
<Space size="large" wrap>
{canSetAdmin && <label><Space>
In-game Admin
<Switch
checked={user.isAdmin}
onClick={() => {
control.send(
new lib.UserSetAdminRequest(userName, false, !user.isAdmin)
).catch(notifyErrorHandler("Error toggling user admin status"));
}}
/>
</Space></label>}
{canSetWhitelisted && <label><Space>
Whitelisted
<Switch
checked={user.isWhitelisted}
onClick={() => {
control.send(
new lib.UserSetWhitelistedRequest(userName, false, !user.isWhitelisted)
).catch(notifyErrorHandler("Error toggling user whitelisted status"));
}}
/>
</Space></label>}
{canBan && <label><Space>
Banned
<Switch checked={banned} onClick={() => setBannedEdit(!banned)} />
</Space></label>}
</Space>
</FieldRow>}
{banned && <FieldRow label="Ban reason">
<Input
value={banReason}
disabled={!canBan}
onChange={e => setBanReasonEdit(e.target.value)}
/>
</FieldRow>}
<ResourceNotes resourceType="user" resourceId={user.id} />
<SectionHeader title="Player stats" />
<Descriptions size="small" bordered column={{ xs: 1, sm: 2, md: 2, lg: 2, xl: 2, xxl: 2 }}>
@@ -15,19 +15,20 @@ export default function VariableDropdownButton(props: VariableDropdownButtonProp
return <></>;
}
const mainDisabled = props.disabled || mainAction.disabled;
const buttonProps: DropdownButtonProps = {
...props,
danger: mainAction.danger,
onClick: (event) => {
event.stopPropagation();
if (mainAction.onClick) {
if (!mainDisabled && mainAction.onClick) {
mainAction.onClick();
}
},
};
return menuActions.length === 0
? <Button {...buttonProps}>
? <Button {...buttonProps} disabled={mainDisabled}>
{mainAction.label}
</Button>
: <Dropdown.Button
@@ -35,7 +36,8 @@ export default function VariableDropdownButton(props: VariableDropdownButtonProp
// stopPropagation is needed to prevent propagation to table rows
menu={{ items: menuActions, onClick: (e: any) => e.domEvent.stopPropagation() }}
buttonsRender={([left, right]) => [
left, React.cloneElement(right as any, { onClick: (e: any) => e.stopPropagation() }),
React.cloneElement(left as any, { disabled: mainDisabled }),
React.cloneElement(right as any, { onClick: (e: any) => e.stopPropagation() }),
]}
>
{mainAction.label}
@@ -0,0 +1,34 @@
import type {
PageActions, PageActionsHook, PageActionsSlot, PageActionsSlotProps, PluginPageAction, WebHooks,
} from "../BaseWebPlugin";
export async function pageActionsFromHooks(hooks: WebHooks) {
const pageActions: Partial<PageActions> = {};
for (const [source, record] of await hooks.pageActions.collectEntries()) {
for (const [slot, useActions] of Object.entries(record) as [PageActionsSlot, PageActionsHook<any>][]) {
if (!pageActions[slot]) {
pageActions[slot] = new Map();
}
pageActions[slot].set(source, useActions);
}
}
return pageActions;
}
/**
* Call each plugin's actions hook for a page and prefix the keys with the
* plugin name. Must be called during render, the set of plugins is fixed
* after bootstrap so the hooks are called in the same order every time.
*/
export function callPageActions<K extends PageActionsSlot>(
hooks: Map<string, PageActionsHook<K>> | undefined,
props: PageActionsSlotProps[K],
) {
const actions: PluginPageAction[] = [];
for (const [source, useActions] of hooks ?? []) {
for (const action of useActions(props)) {
actions.push({ ...action, key: `${source}.${action.key}` });
}
}
return actions;
}
@@ -0,0 +1,14 @@
import { useContext } from "react";
import ControlContext from "../components/ControlContext";
import type { PageActionsSlot, PageActionsSlotProps, PluginPageAction } from "../BaseWebPlugin";
import { callPageActions } from "./plugin_actions";
/** Actions plugins add to the dropdown of a page. */
export default function usePluginActions<K extends PageActionsSlot>(
slot: K,
props: PageActionsSlotProps[K],
): PluginPageAction[] {
const control = useContext(ControlContext);
return callPageActions(control.pageActions[slot], props);
}
@@ -0,0 +1,147 @@
import { useEffect, useLayoutEffect, useState } from "react";
import { type Location, type NavigationType, useLocation, useNavigationType } from "react-router-dom";
const storageKey = "scroll_positions";
const maxEntries = 100;
const restoreTimeoutMs = 5000;
/** Read saved scroll positions, oldest first. */
export function loadScrollPositions(storage: Pick<Storage, "getItem">): Map<string, number> {
try {
const stored = JSON.parse(storage.getItem(storageKey) ?? "[]");
if (Array.isArray(stored)) {
return new Map(stored.filter(
(entry): entry is [string, number] => typeof entry[0] === "string" && typeof entry[1] === "number"
));
}
} catch {
// Fall through to an empty map on corrupt data.
}
return new Map();
}
/** Record a position as the newest entry, dropping the oldest past the limit. */
export function setScrollPosition(positions: Map<string, number>, key: string, y: number) {
positions.delete(key);
positions.set(key, y);
for (const oldest of positions.keys()) {
if (positions.size <= maxEntries) {
break;
}
positions.delete(oldest);
}
}
export function saveScrollPositions(storage: Pick<Storage, "setItem">, positions: Map<string, number>) {
try {
storage.setItem(storageKey, JSON.stringify([...positions]));
} catch {
// Ignore storage errors (e.g. quota exceeded or storage disabled).
}
}
/** History entries created outside the router all share the key "default". */
export function scrollKey(location: Pick<Location, "key" | "pathname" | "search">) {
return location.key === "default" ? `${location.pathname}${location.search}` : location.key;
}
/**
* Scroll to y, retrying as the page grows while its data loads. Gives up after
* a timeout or when the user scrolls.
*/
export function restoreScroll(y: number, onDone: () => void) {
const inputEvents = ["wheel", "touchstart", "keydown", "pointerdown"];
const observer = new ResizeObserver(attempt);
const timeout = setTimeout(stop, restoreTimeoutMs);
let stopped = false;
function stop() {
if (stopped) {
return;
}
stopped = true;
observer.disconnect();
clearTimeout(timeout);
for (const event of inputEvents) {
window.removeEventListener(event, stop, true);
}
onDone();
}
function attempt() {
window.scrollTo(0, y);
if (window.scrollY >= y - 1) {
stop();
}
}
for (const event of inputEvents) {
window.addEventListener(event, stop, { capture: true, passive: true });
}
observer.observe(document.body);
attempt();
return stop;
}
export class ScrollRestorer {
positions = loadScrollPositions(sessionStorage);
restoring = false;
key: string;
pathname: string;
constructor(key: string, pathname: string) {
this.key = key;
this.pathname = pathname;
}
/** Start recording scroll positions, returns a function that stops it. */
attach() {
window.history.scrollRestoration = "manual";
const onScroll = () => {
if (!this.restoring) {
setScrollPosition(this.positions, this.key, window.scrollY);
}
};
const persist = () => saveScrollPositions(sessionStorage, this.positions);
window.addEventListener("scroll", onScroll, { passive: true });
window.addEventListener("pagehide", persist);
return () => {
window.removeEventListener("scroll", onScroll);
window.removeEventListener("pagehide", persist);
persist();
};
}
/** Handle a location change, returns a function that cancels a pending restore. */
navigate(key: string, pathname: string, navigationType: NavigationType) {
this.key = key;
saveScrollPositions(sessionStorage, this.positions);
const pathChanged = this.pathname !== pathname;
this.pathname = pathname;
// Table sort, filter and page changes only change the query
if (navigationType === "PUSH" && pathChanged) {
window.scrollTo(0, 0);
return undefined;
}
if (navigationType !== "POP") {
setScrollPosition(this.positions, key, window.scrollY);
return undefined;
}
this.restoring = true;
return restoreScroll(this.positions.get(key) ?? 0, () => { this.restoring = false; });
}
}
/**
* Restore the window scroll position on back/forward and page reload, and
* scroll to the top when navigating to another page.
*/
export default function useScrollRestoration() {
const location = useLocation();
const navigationType = useNavigationType();
const key = scrollKey(location);
const [restorer] = useState(() => new ScrollRestorer(key, location.pathname));
useEffect(() => restorer.attach(), []);
useLayoutEffect(() => restorer.navigate(key, location.pathname, navigationType), [key]);
}
+1
View File
@@ -64,6 +64,7 @@ export class Control extends lib.Link {
public loadedPlugins = new Map<string, lib.PluginWebEnvInfo>();
public inputComponents = new Map<string, WebPlugin.InputComponent>();
public extensionComponents: Partial<WebPlugin.ExtensionComponents> = {};
public pageActions: Partial<WebPlugin.PageActions> = {};
public loginForms: WebPlugin.PluginLoginForm[] = [];
public pages: WebPlugin.PluginPage[] = [];
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@clusterio/plugin-global_chat",
"version": "2.1.1",
"version": "2.1.2",
"description": "Clusterio plugin forwarding between Factorio servers",
"homepage": "https://github.com/clusterio/clusterio#readme",
"author": "Hornwitser <github@hornwitser.no>",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@clusterio/plugin-player_auth",
"version": "2.1.1",
"version": "2.1.2",
"description": "Clusterio plugin authenticating logged in players to the web interface",
"homepage": "https://github.com/clusterio/clusterio#readme",
"author": "Hornwitser <github@hornwitser.no>",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@clusterio/plugin-player_sync",
"version": "2.1.1",
"version": "2.1.2",
"description": "Clusterio plugin forwarding between Factorio servers",
"homepage": "https://github.com/clusterio/clusterio#readme",
"author": "Danielv <danielv@danielv.no>",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@clusterio/plugin-research_sync",
"version": "2.1.1",
"version": "2.1.2",
"description": "Clusterio plugin for synchronizing research between Factorio servers",
"homepage": "https://github.com/clusterio/clusterio#readme",
"author": "Hornwitser <github@hornwitser.no>",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@clusterio/plugin-statistics_exporter",
"version": "2.1.1",
"version": "2.1.2",
"description": "Clusterio plugin for gathering statistics from Factorio servers",
"homepage": "https://github.com/clusterio/clusterio#readme",
"author": "Hornwitser <github@hornwitser.no>",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@clusterio/plugin-subspace_storage",
"version": "2.1.1",
"version": "2.1.2",
"description": "Clusterio plugin for sharing storage between Factorio servers",
"homepage": "https://github.com/clusterio/clusterio#readme",
"author": "Hornwitser <github@hornwitser.no>",
+1 -2
View File
@@ -21,8 +21,8 @@ catalog:
'@types/yazl': ^3.3.1
'@vitejs/plugin-react': ^6.1.2
antd: ^5.29.3
chalk: ^6.0.1
express: ^5.3.0
fflate: ^0.8.3
jsonwebtoken: ^9.0.3
react: ^18.3.1
react-dom: ^18.3.1
@@ -34,7 +34,6 @@ catalog:
typescript: ^7.0.2
vite: ^8.3.4
winston: ^3.19.0
winston-daily-rotate-file: ^5.0.0
winston-transport: ^4.9.0
ws: ^8.22.0
yargs: ^18.2.0
+1 -1
View File
@@ -10,7 +10,7 @@ import path from "node:path";
import fs from "node:fs/promises";
import yargs from "yargs";
import npmPackage from "./package.json" with { type: "json" };
import npmPackage from "../package.json" with { type: "json" };
const workspaces = npmPackage.workspaces
.map(p => p.slice(0, -2))
.filter(p => !p.includes("external_plugins"));
+42 -24
View File
@@ -195,20 +195,21 @@ export function checkPullRequestBody(
function changelogFromPullRequests(pullRequests: Issue[], issues: Issue[]) {
const mergedChangelog: Changelog = Object.create(null);
const problems: string[] = [];
for (const pr of pullRequests) {
const { changelog, error, warnings } = checkPullRequestBody(pr.body, pr, issues);
if (error) {
console.error(`Failed to extract changelog in ${pr.html_url}: ${error}`)
problems.push(`Failed to extract changelog in ${pr.html_url}: ${error}`);
continue;
}
for (const warning of warnings) {
console.warn(`Warning in changelog for ${pr.html_url}: ${warning}`)
problems.push(`Warning in changelog for ${pr.html_url}: ${warning}`);
}
for (const [section, items] of Object.entries(changelog)) {
mergedChangelog[section] = [...mergedChangelog[section] ?? [], ...items];
}
}
return mergedChangelog;
return [mergedChangelog, problems] as const;
}
async function fetchLastRelease() {
@@ -258,7 +259,7 @@ async function fetchStatistics(lastRelease: Release, pullRequests: Issue[]): Pro
};
}
function printMarkdown(
function formatMarkdown(
changelog: Changelog,
issues: Issue[],
users: Issue["user"][],
@@ -266,12 +267,13 @@ function printMarkdown(
refText: (issue: Issue) => string,
userText: (user: Issue["user"]) => string,
) {
const lines: string[] = [];
const sections = new Set([...changelogSections, ...Object.keys(changelog)]);
for (const section of sections) {
if (section in changelog) {
console.log(`### ${section}\n`);
lines.push(`### ${section}`, "");
const entries = changelog[section];
console.log(entries.map(text => (
lines.push(...entries.map(text => (
`- ${text.replaceAll(/#(\d+)/g, (ref, idAsText) => {
const id = Number.parseInt(idAsText, 10);
if (!Number.isFinite(id)) {
@@ -283,27 +285,29 @@ function printMarkdown(
}
return refText(issue);
})}`
)).join("\n"));
console.log();
)));
lines.push("");
}
}
console.log("### Contributors\n");
console.log(`Many thanks to the following for contributing to this release:`);
console.log(users.map(userText).join(", "));
lines.push("### Contributors", "");
lines.push("Many thanks to the following for contributing to this release:");
lines.push(users.map(userText).join(", "));
const format = (value: number) => value.toLocaleString("en-US");
console.log("\n### Statistics\n");
console.log([
lines.push("", "### Statistics", "");
lines.push([
`Commits: ${format(statistics.commits)}`,
`Pull Requests: ${format(statistics.pullRequests)}`,
`Files Changed: ${format(statistics.filesChanged)}`,
`Additions: +${format(statistics.lineAdditions)}`,
`Deletions: -${format(statistics.lineDeletions)}`,
].join(" "));
return lines.join("\n");
}
async function main() {
/** Builds the release notes for the changes merged since the last release. */
export async function generateReleaseNotes() {
const lastRelease = await fetchLastRelease();
const issues = await fetchIssuesUpdatedSince(lastRelease.created_at);
@@ -313,23 +317,37 @@ async function main() {
&& issue.pull_request.merged_at > lastRelease.created_at
));
const changelog = changelogFromPullRequests(pullRequests, issues);
const users = [...new Map(pullRequests.map(issue => [issue.user.login, issue.user])).values()]
const [changelog, problems] = changelogFromPullRequests(pullRequests, issues);
const users = [...new Map(pullRequests.map(issue => [issue.user.login, issue.user])).values()];
const statistics = await fetchStatistics(lastRelease, pullRequests);
return {
/** Errors and warnings from the pull request changelogs. */
problems,
github: formatMarkdown(changelog, issues, users, statistics,
issue => `${repository}#${issue.number}`,
user => `@${user.login}`,
),
changelog: formatMarkdown(changelog, issues, users, statistics,
issue => `[#${issue.number}](<${issue.html_url}>)`,
user => `[@${user.login}](<${user.html_url}>)`
),
};
}
async function main() {
const notes = await generateReleaseNotes();
for (const problem of notes.problems) {
console.warn(problem);
}
console.log();
console.log("=== Github Release Markdown ===");
printMarkdown(changelog, issues, users, statistics,
issue => `${repository}#${issue.number}`,
user => `@${user.login}`,
);
console.log(notes.github);
console.log();
console.log("=== Discord / Changelog Markdown ===");
printMarkdown(changelog, issues, users, statistics,
issue => `[#${issue.number}](<${issue.html_url}>)`,
user => `[@${user.login}](<${user.html_url}>)`
);
console.log(notes.changelog);
}
if (import.meta.main) {
+103
View File
@@ -0,0 +1,103 @@
// Bumps the package versions, adds the release notes to CHANGELOG.md, then commits and tags the release.
// Usage: node scripts/prepare_release.mts [--force] <version>
// --force continues when pull request changelogs have errors or warnings.
import { execFile } from "node:child_process";
import fs from "node:fs/promises";
import path from "node:path";
import { promisify } from "node:util";
import { generateReleaseNotes } from "./pr_to_changelog.mts";
const root = path.resolve(import.meta.dirname, "..");
const versionPattern = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
async function git(...args: string[]) {
return (await promisify(execFile)("git", args, { cwd: root, encoding: "utf8" })).stdout;
}
export function setPackageVersion(text: string, version: string) {
const pattern = /^([ \t]*"version":[ \t]*)"[^"]*"/m;
if (!pattern.test(text)) {
throw new Error("No version field found");
}
return text.replace(pattern, `$1"${version}"`);
}
export function addChangelogEntry(text: string, version: string, notes: string) {
if (new RegExp(`^## Version ${version.replaceAll(".", "\\.")}$`, "m").test(text)) {
throw new Error(`CHANGELOG.md already has an entry for ${version}`);
}
const firstEntry = text.search(/^## /m);
if (firstEntry === -1) {
throw new Error("No existing entry found in CHANGELOG.md");
}
return `${text.slice(0, firstEntry)}## Version ${version}\n\n${notes.trim()}\n\n\n${text.slice(firstEntry)}`;
}
async function packageFiles() {
const files: string[] = [];
for (const parent of ["packages", "plugins"]) {
for (const entry of await fs.readdir(path.join(root, parent), { withFileTypes: true })) {
const file = path.join(parent, entry.name, "package.json");
if (entry.isDirectory() && await fs.stat(path.join(root, file)).catch(() => null)) {
files.push(file);
}
}
}
return files;
}
async function main() {
const args = process.argv.slice(2);
const force = args.includes("--force");
const [version, ...rest] = args.filter(arg => arg !== "--force");
if (!version || rest.length || !versionPattern.test(version)) {
console.error("Usage: node scripts/prepare_release.mts [--force] <version>, e.g. 2.1.2");
process.exitCode = 1;
return;
}
if (await git("status", "--porcelain", "--untracked-files=no")) {
throw new Error("Working tree has uncommitted changes");
}
if (await git("tag", "--list", `v${version}`)) {
throw new Error(`Tag v${version} already exists`);
}
// Done first so a GitHub API failure leaves the working tree untouched.
const notes = await generateReleaseNotes();
for (const problem of notes.problems) {
console.warn(problem);
}
if (notes.problems.length && !force) {
throw new Error(
`Found ${notes.problems.length} changelog problem(s) in merged pull requests. ` +
"Fix the pull request descriptions and run it again, or pass --force to continue anyway."
);
}
const changelogPath = path.join(root, "CHANGELOG.md");
const changelog = addChangelogEntry(await fs.readFile(changelogPath, "utf8"), version, notes.changelog);
const files = await packageFiles();
for (const file of files) {
const filePath = path.join(root, file);
await fs.writeFile(filePath, setPackageVersion(await fs.readFile(filePath, "utf8"), version));
}
await fs.writeFile(changelogPath, changelog);
await git("add", "CHANGELOG.md", ...files);
await git("commit", "--quiet", "-m", `Prepare ${version}`);
await git("tag", `v${version}`);
console.log();
console.log(`Committed "Prepare ${version}" and tagged it v${version}. Nothing was pushed.`);
console.log("Review it with: git show --stat HEAD");
console.log();
console.log("=== Github Release Markdown ===");
console.log(notes.github);
}
if (import.meta.main) {
main().catch(err => {
console.error(err.message ?? err);
process.exitCode = 1;
});
}
View File
File renamed without changes.
+1 -1
View File
@@ -15,7 +15,7 @@
*
* Listed messages are warned about instead of failing the test, and an entry
* with connect skips starting the cluster. Entries for other versions are
* ignored. See docs/contributing.md for when to add an entry.
* ignored. See contributing.md for when to add an entry.
*/
"use strict";
import fs from "node:fs/promises";
+82 -1
View File
@@ -239,6 +239,59 @@ describe("controller/src/Controller", function() {
});
});
});
describe(".loadPlugins()", function() {
const names = ["wait_early", "wait_late", "wait_off"];
let dir;
before(async function() {
addPluginConfigFields(names.map(name => ({ name, version: "1.0.0", controllerEntrypoint: "x" })));
dir = await fs.mkdtemp(path.join(os.tmpdir(), "clusterio-wait-"));
const entrypoints = {
wait_early: `export default async function({ controller, plugins }) {
controller.lateApi = await plugins.waitFor("wait_late");
controller.offApi = await plugins.waitFor("wait_off", 60_000);
}`,
wait_late: "export default function() { return { late: true }; }",
wait_off: "export default function() { return { off: true }; }",
};
for (const [name, content] of Object.entries(entrypoints)) {
await fs.mkdir(path.join(dir, name, "dist", "web"), { recursive: true });
await fs.writeFile(path.join(dir, name, "dist", "web", "manifest.json"), "{}");
await fs.writeFile(path.join(dir, name, "controller.js"), content);
}
});
after(async function() {
for (const name of Object.keys(lib.ControllerConfig.fieldDefinitions)) {
if (names.some(plugin => name.startsWith(`${plugin}.`))) {
delete lib.ControllerConfig.fieldDefinitions[name];
}
}
await fs.rm(dir, { recursive: true, force: true });
});
function pluginController(recoveryMode = false) {
const config = new ControllerConfig("controller", {
"controller.version": controllerVersion, "wait_off.load_plugin": false,
});
const infos = names.map(name => ({
name,
requirePath: path.join(dir, name),
packagePath: path.join(dir, name, "package.json"),
controllerEntrypoint: "controller.js",
}));
return new Controller({}, infos, config, false, recoveryMode);
}
it("should let plugins wait for each other", async function() {
const pluginsController = pluginController();
await pluginsController.loadPlugins();
assert.deepEqual(pluginsController.lateApi, { late: true });
assert.equal(pluginsController.offApi, undefined);
assert.deepEqual([...pluginsController.loadedPlugins].map(p => p.name), ["wait_early", "wait_late"]);
});
it("should load nothing in recovery mode", async function() {
const pluginsController = pluginController(true);
await pluginsController.loadPlugins();
assert.equal(pluginsController.loadedPlugins.size, 0);
});
});
describe(".validateExports()", function() {
let dir;
before(async function() {
@@ -369,9 +422,10 @@ describe("controller/src/Controller", function() {
describe(".serveWeb()", function() {
let server, port;
const config = new Map([["controller.name", "Test Cluster"], ["controller.favicon_url", null]]);
before(async function() {
const app = express();
app.locals.controller = { config: { get: () => "Test Cluster" } };
app.locals.controller = { config: { get: field => config.get(field) } };
app.locals.webBundle = {
main: "static/main.abc.js",
imports: { "react": "static/shared-react.abc.js" },
@@ -405,6 +459,33 @@ describe("controller/src/Controller", function() {
assert(html.includes("src=\"../../../static/main.abc.js\""));
assert(html.includes("new URL(\"../../../static/\", document.location)"));
});
it("should escape the cluster name", async function() {
config.set("controller.name", "A&B \"<x>\"");
try {
const html = await (await fetch(`http://localhost:${port}/`)).text();
assert(html.includes("<title>A&amp;B &quot;&lt;x&gt;&quot;</title>"));
assert(html.includes('<meta name="application-name" content="A&amp;B &quot;&lt;x&gt;&quot;" />'));
} finally {
config.set("controller.name", "Test Cluster");
}
});
it("should link favicon_url relative to the web root", async function() {
let html = await (await fetch(`http://localhost:${port}/`)).text();
assert(!html.includes("rel=\"icon\""));
try {
config.set("controller.favicon_url", "static/icon.png");
html = await (await fetch(`http://localhost:${port}/instances/1/view`)).text();
assert(html.includes('<link rel="icon" href="../../static/icon.png" />'));
config.set("controller.favicon_url", "https://example.com/icon.png?a=1&b=2");
html = await (await fetch(`http://localhost:${port}/instances/1/view`)).text();
assert(html.includes('<link rel="icon" href="https://example.com/icon.png?a=1&amp;b=2" />'));
config.set("controller.favicon_url", "/icon.png");
html = await (await fetch(`http://localhost:${port}/instances/1/view`)).text();
assert(html.includes('<link rel="icon" href="/icon.png" />'));
} finally {
config.set("controller.favicon_url", null);
}
});
});
describe(".parseTrustedProxies()", function() {
it("should parse addresses", function() {
+89 -28
View File
@@ -22,8 +22,8 @@ describe("controller/src/routes", function() {
let port;
beforeEach(async function() {
controller = new mock.MockController();
// Check the progress of requests every 500 ms instead of every 30 seconds.
routes.addRouteHandlers(controller.app, 500);
// Check the progress of requests every 500 ms without a burst allowance.
routes.addRouteHandlers(controller.app, 500, 0);
server = http.createServer(routes.httpServerOptions, controller.app);
server.listen(0, "localhost");
await events.once(server, "listening");
@@ -179,7 +179,7 @@ describe("controller/src/routes", function() {
return status;
}
it("should close a transfer that stops making progress", async function() {
controller.mockConfigEntries.set("controller.transfer_min_progress", 1);
controller.mockConfigEntries.set("controller.transfer_min_speed", 2);
const stream = await routes.createProxyStream(controller.app);
const request = http.request(
`${endpoint}/${stream.id}`, { method: "PUT", headers: { "Content-Length": 1024 * 1024 } }
@@ -196,7 +196,7 @@ describe("controller/src/routes", function() {
});
it("should close a transfer that is trickled in", async function() {
this.timeout(10000);
controller.mockConfigEntries.set("controller.transfer_min_progress", 4);
controller.mockConfigEntries.set("controller.transfer_min_speed", 8);
const stream = await routes.createProxyStream(controller.app);
const start = Date.now();
const upload = putPaced(stream.id, 200, 50);
@@ -208,7 +208,7 @@ describe("controller/src/routes", function() {
});
it("should not close a slow transfer that makes progress", async function() {
this.timeout(10000);
controller.mockConfigEntries.set("controller.transfer_min_progress", 1);
controller.mockConfigEntries.set("controller.transfer_min_speed", 2);
const stream = await routes.createProxyStream(controller.app);
const upload = putPaced(stream.id, 1024, 20);
const download = fetch(`${endpoint}/${stream.id}`).then(response => response.arrayBuffer());
@@ -216,30 +216,41 @@ describe("controller/src/routes", function() {
assert.equal((await download).byteLength, 20 * 1024);
});
it("should not close a transfer held back by a slow receiver", async function() {
this.timeout(20000);
controller.mockConfigEntries.set("controller.transfer_min_progress", 16);
const size = 4 * 1024 * 1024;
const stream = await routes.createProxyStream(controller.app);
const upload = fetch(`${endpoint}/${stream.id}`, { method: "PUT", body: Buffer.alloc(size) });
const received = await new Promise((resolve, reject) => {
http.get(`${endpoint}/${stream.id}`, response => {
let bytes = 0;
response.on("data", chunk => {
bytes += chunk.length;
response.pause();
setTimeout(() => response.resume(), 50);
});
response.on("end", () => resolve(bytes));
response.on("error", reject);
}).on("error", reject);
});
assert.equal(received, size);
assert.equal((await upload).status, 200);
this.timeout(40000);
// The receiver takes about 1.2 MB/s, which the OS hands on in bursts of over a MB.
const slowController = new mock.MockController();
slowController.mockConfigEntries.set("controller.transfer_min_speed", 1024);
routes.addRouteHandlers(slowController.app, 3000);
const slowServer = http.createServer(routes.httpServerOptions, slowController.app);
slowServer.listen(0, "localhost");
await events.once(slowServer, "listening");
const slowEndpoint = `http://localhost:${slowServer.address().port}/api/stream`;
try {
const size = 16 * 1024 * 1024;
const stream = await routes.createProxyStream(slowController.app);
const upload = fetch(`${slowEndpoint}/${stream.id}`, { method: "PUT", body: Buffer.alloc(size) });
const received = await new Promise((resolve, reject) => {
http.get(`${slowEndpoint}/${stream.id}`, response => {
let bytes = 0;
response.on("data", chunk => {
bytes += chunk.length;
response.pause();
setTimeout(() => response.resume(), 50);
});
response.on("end", () => resolve(bytes));
response.on("error", reject);
}).on("error", reject);
});
assert.equal(received, size);
assert.equal((await upload).status, 200);
} finally {
slowServer.close();
}
});
it("should not count the time waiting for the stream to start", async function() {
this.timeout(10000);
controller.mockConfigEntries.set("controller.proxy_stream_timeout", 3);
controller.mockConfigEntries.set("controller.transfer_min_progress", 1);
controller.mockConfigEntries.set("controller.transfer_min_speed", 2);
const stream = await routes.createProxyStream(controller.app);
const download = fetch(`${endpoint}/${stream.id}`);
await lib.wait(1500);
@@ -1257,7 +1268,7 @@ describe("controller/src/routes", function() {
});
it("should close an upload that is trickled in", async function() {
this.timeout(10000);
controller.mockConfigEntries.set("controller.transfer_min_progress", 4);
controller.mockConfigEntries.set("controller.transfer_min_speed", 8);
const modsDirectory = await fs.mkdtemp(path.join(os.tmpdir(), "clusterio-mods-"));
try {
controller.mockConfigEntries.set("controller.mods_directory", modsDirectory);
@@ -1277,15 +1288,65 @@ describe("controller/src/routes", function() {
});
it("should close a request to another route that is trickled in", async function() {
this.timeout(10000);
controller.mockConfigEntries.set("controller.transfer_min_progress", 4);
controller.mockConfigEntries.set("controller.transfer_min_speed", 8);
controller.app.post("/test", express.raw({ type: "*/*", limit: "2mb" }), (req, res) => res.sendStatus(200));
const result = await trickle(`http://localhost:${port}/test`, { "Content-Type": "text/plain" });
assert.equal(result.status, undefined);
assert(result.duration < 2000, `closed after ${result.duration} ms`);
});
describe("with a burst allowance", function() {
let burstServer, burstUrl;
beforeEach(async function() {
// Each check requires 256 KiB/s * 0.5 s - 64 KiB = 64 KiB.
const burstController = new mock.MockController();
burstController.mockConfigEntries.set("controller.transfer_min_speed", 256);
routes.addRouteHandlers(burstController.app, 500, 64 * 1024);
burstController.app.post("/test", express.raw({ type: "*/*", limit: "2mb" }), (req, res) => {
res.sendStatus(200);
});
burstServer = http.createServer(routes.httpServerOptions, burstController.app);
burstServer.listen(0, "localhost");
await events.once(burstServer, "listening");
burstUrl = `http://localhost:${burstServer.address().port}/test`;
});
afterEach(function() {
burstServer.close();
});
async function sendBursts(burstBytes) {
const bursts = 12;
const request = http.request(burstUrl, {
method: "POST", headers: { "Content-Type": "text/plain", "Content-Length": burstBytes * bursts },
});
let status;
request.on("response", response => {
status = response.statusCode;
response.resume();
});
request.on("error", () => {});
const closed = new Promise(resolve => request.on("close", resolve));
for (let i = 0; i < bursts && !request.closed; i++) {
request.write(Buffer.alloc(burstBytes));
await lib.wait(300);
}
if (!request.closed) {
request.end();
}
await closed;
return status;
}
it("should not close a request at the minimum speed arriving in bursts", async function() {
this.timeout(10000);
// 78 KiB every 300 ms is 260 KiB/s, a check can see only one burst.
assert.equal(await sendBursts(78 * 1024), 200);
});
it("should close a request below the minimum speed arriving in bursts", async function() {
this.timeout(10000);
assert.equal(await sendBursts(39 * 1024), undefined);
});
});
it("should not close a trickled in request when the limit is 0", async function() {
this.timeout(10000);
controller.mockConfigEntries.set("controller.transfer_min_progress", 0);
controller.mockConfigEntries.set("controller.transfer_min_speed", 0);
controller.app.post("/test", express.raw({ type: "*/*", limit: "2mb" }), (req, res) => res.sendStatus(200));
const result = await trickle(`http://localhost:${port}/test`, { "Content-Type": "text/plain" });
assert(result.duration >= 5000, `closed after ${result.duration} ms`);
+35
View File
@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
import dgram from "node:dgram";
import events from "node:events";
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";
@@ -250,6 +251,40 @@ describe("host/src/Host", function() {
assert.equal(host.config.restartRequired, true);
});
});
describe(".loadPlugins()", function() {
let dir;
before(async function() {
lib.addPluginConfigFields([
{ name: "host_wait_early", version: "1.0.0", hostEntrypoint: "x" },
{ name: "host_wait_late", version: "1.0.0", hostEntrypoint: "x" },
]);
dir = await fs.mkdtemp(path.join(os.tmpdir(), "clusterio-host-wait-"));
await fs.writeFile(path.join(dir, "early.js"), `export default async function({ host, plugins }) {
host.lateApi = await plugins.waitFor("host_wait_late");
}`);
await fs.writeFile(path.join(dir, "late.js"), "export default function() { return { late: true }; }");
});
after(async function() {
for (const name of Object.keys(lib.HostConfig.fieldDefinitions)) {
if (name.startsWith("host_wait_")) {
delete lib.HostConfig.fieldDefinitions[name];
}
}
await fs.rm(dir, { recursive: true, force: true });
});
it("should let plugins wait for each other", async function() {
const pluginInfos = [["host_wait_early", "early.js"], ["host_wait_late", "late.js"]].map(
([name, hostEntrypoint]) => ({
name, hostEntrypoint, packagePath: path.resolve(dir, "package.json"),
})
);
const hostConfig = new lib.HostConfig("host");
const host = new Host(new HostConnector(hostConfig, pluginInfos), hostConfig, pluginInfos);
await host.loadPlugins();
assert.deepEqual(host.lateApi, { late: true });
assert.deepEqual([...host.loadedPlugins].map(p => p.name), ["host_wait_early", "host_wait_late"]);
});
});
describe(".assignFreeGamePort()", function() {
let host;
let held;
+76 -1
View File
@@ -95,7 +95,9 @@ describe("class Instance", function() {
instanceConfig.set("instance.name", "foo");
src = addr({ instanceId: instanceConfig.get("instance.id") });
connector = new MockConnector(src, dst);
instance = new Instance({}, connector, "dir", instanceConfig, new MockServer());
instance = new Instance(
{ _crashRetryAttempts: new Map() }, connector, "dir", instanceConfig, new MockServer()
);
});
describe(".name", function() {
@@ -308,6 +310,79 @@ describe("class Instance", function() {
});
});
describe("restart after crash", function() {
let errors;
let starts;
beforeEach(function() {
errors = [];
starts = [];
instance.logger = new MockLogger();
instance.logger.error = message => errors.push(message);
instance._saveStats = async () => {};
instance._host._connectInstance = async id => {
starts.push(id);
return { instance: { _startSave: async () => {} } };
};
instance.config.set("instance.restart_after_crash", true);
});
function crash(uptimeMinutes) {
instance.notifyStatus("running");
instance._startedAtMs = Date.now() - uptimeMinutes * 60e3;
instance.notifyExit();
}
it("should restart after running for 10 minutes until the attempts run out", function() {
for (let i = 0; i < 4; i++) {
crash(11);
}
assert.deepEqual(starts, [instance.id, instance.id, instance.id]);
assert.deepEqual(errors, ["Instance foo reached the limit of 3 crash restarts, not restarting it"]);
});
it("should restart without limit when attempts is 0", function() {
instance.config.set("instance.crash_retry_attempts", 0);
for (let i = 0; i < 5; i++) {
crash(11);
}
assert.equal(starts.length, 5);
assert.deepEqual(errors, []);
});
it("should not restart a crash within 10 minutes of starting", function() {
crash(9);
assert.deepEqual(starts, []);
assert.deepEqual(errors, ["Instance foo crashed within 10 minutes of starting, not restarting it"]);
});
it("should not restart when disabled", function() {
instance.config.set("instance.restart_after_crash", false);
crash(11);
assert.deepEqual(starts, []);
assert.deepEqual(errors, []);
});
it("should not restart after a stop or kill", async function() {
instance.server.kill = async () => {};
instance.notifyStatus("running");
instance._startedAtMs = 0;
await instance.handleInstanceKillRequest();
instance.notifyExit();
instance.notifyStatus("stopping");
instance.notifyExit();
assert.deepEqual(starts, []);
assert.deepEqual(errors, []);
});
it("should not restart while the host shuts down", function() {
instance._host._shuttingDown = true;
crash(11);
assert.deepEqual(starts, []);
});
it("should reset the attempts on a manual start", async function() {
instance.config.set("instance.crash_retry_attempts", 1);
instance._startSave = async () => {};
crash(11);
await instance.handleInstanceStartRequest(new lib.InstanceStartRequest());
crash(11);
assert.equal(starts.length, 2);
});
});
describe(".checkModPackVersion()", function() {
function modPack(factorioVersion) {
return lib.ModPack.fromJSON({ name: "pack", factorio_version: factorioVersion });
Loaded 100 of 113 files, more files were not shown because too many files have changed in this diff. Show more